Set up git account

TL; DR:

git config:

• to set up global git account, use git config --global user.name and git config --global user.email. The file is stored in ~/.gitconfig.
• to set up a local git account for a local repo, navigate to this repo, then do git config --local user.name and git config --local user.email. The file is stored in .git/config under the repo directory.

Level of git

If you followed last post and have tested the connection by initiate a git clone, the connection between your local repo and remote repo (GitHub repo) is successfully built.

But this does not necessarily mean you can commit with the account you desired, or can commit at all. It’s the git account that controls which user makes the commit. But before we dive into git account set up, we need to first know the 3 level of git account.

There are 3 levels of git settings. From top to lower hierarchy, they are:

• System level: this is the universal setting for the entire machine. To set the system git, you need to have the admin access to the computer. System setting is stored in /etc/config. In most of the case we do not need to touch this.
• Global level: this applies to all directories for a specific user of the computer, and there can be only one account registered in this level. Global git setting is stored in ~/.gitconfig.
• Project level: as the name suggested, a project level git setting only applies to a particular project folder. Setting is stored in .git/config under the project directory.

Just like setting for any “class”, in git settings, project level overrides global level, and global level overrides system level. When the lower level setting was not available, the setting for one level up will be referred to first.

Set up global git

Since you likely don’t need to touch the system level of git on your own computer, let’s start off from the global level (some article also call this “home directory”)

For mac users, once you open Terminal, by default the directory is pointing to “home directory”, which is the highest path to anything related to the current computer account user. If there are multiple accounts in one computer, each will have it’s own home directory and the settings/documents will be kept separately. The shorthand path to home directory is simply ~. The actual path is /Users/your_login_user. You can also see the path by launching Terminal and type pwd and hit enter.

Under the home directory, there is one file (by default hidden so calling ls won’t be able to make it appear) called .gitconfig, which stores all the git info for global level. For instance now we want to modify the user name to be “global-git” (in reality you likely will name it after yourself, or after your github handle. Here for demonstration purpose and for distinguishing different levels of git, let’s use this name), and with the email “ personal@abc.com”, we can do:

git config --global user.name global-git
git config --global user.email personal@abc.com

Because we specified the level by using condition --global, you can use this command anywhere in the directory, to quickly check or modify the global git settings.

After the modification, you can open up the config file to see for yourself what has changed:

nano ~/.gitconfig #the "~/" here is just to direct you to home directory. If you are in home directory, you can skip this

You will notice the last section, [user] has been added there, with the name and email you just put in. It looks like this:

Figure 1: global git config

This tells you the what the default branch is, and the name and email of your global git account.

The global git account makes things easier as it works as a default account. Since the lower level overrides higher level, when a local git is set up, commits use the local git configurations. But when local git is not set up, this global git account will be used, so if the global git is the account you mostly use, then it saves you time from having to set up local git for each repository.

Set up local git

Local git is the git account for a particular project. Suppose this is for a work project with the repo called product-test, and you have successfully built the connection between your local directory and remote work repo. To set up local git, you need to first navigate to that directory, then:

git config --local user.name local-git
git config --local user.email office@abc.com

Local git configurations are saved in a file .git/config under the project directory. Open that open and you will see something similar:

Figure 2: local git config

Similar to global git account, the last section [user] now is added as a project-level git account.

Note here the --local is optional, ie: you can just use git config user.name to set up local git, once you are in that directory. But to make it explicit I highly recommend always include --local when setting up git for project level. Now when you make a commit, on GitHub it will be your gh-office that makes the contribution.

Set up default git account

📂 Office
├── 📂 product-test
├── 📂 project02
├── 📂 project03
└── 📄 .gitconfig-office

When we have multiple project repo saved under the same directory, for the same account, we may want to set a default git account that applies to all sub-directories. However, a local git that we set up for a particular project does not get inherited by sub-directories. To achieve that, we need to do some creation and modifications.

First, navigate to the office project directory ~/office, create a file .gitconfig-office file (note it is not .git/config):

nano ~/office/.gitconfig-office

Add the following to the file and save it:

[user]
	name = office-git # in reality you'd likely use your name. Here is just a demo
	email = office@abc.com

Then, go back to home directory and modify the global git config file:

nano ~/.gitconfig

Because in previous steps we have already set up a global git, you should see that there. After the [user] section, add the following in the bottom:

[includeIf "gitdir:~/office/"] # don't forget the "/" in the end
        path = ~/office/.gitconfig-office

You should see something like this:

Figure 3: add dir condition

What the [includeIf] does is to specify a condition. Whenever the path of a directory matches the path you provided after “gitdir:”, git will use the configuration file you specified in “path”. To test, open up any sub-directory under ~/office, and run:

git config user.name
git config user.email

It should return your office-git settings.

git setting inheritance:

From the discussion above, we can see that:

• settings saved in .git/config (by git config or git config --local) are only applicable to the specific project directory and will not be inherited by sub-directories.
• settings saved in .gitconfig (by git config --global if you set up global git, or by create and modify a .gitconfig file directly and add the path to global config) are inherited by all sub-directories (but can always be overwritten by local git in sub-directory).

troubleshooting:

Setting up path conditions could be tricky. Here are some common mistakes:

• the [includeIf] is not added in global config but the config in office directory.
• the [includeIf] is placed before [user]. This is often ignored, especially if you needed to change the global git user after setting everything up, and just simply put the [user] section after [includeIf] part. Once [user] is placed after [includeIf], it overrides the condition and make the setting invalid.
• you forgot the forward slash / at the end of “gitdir:…”. The forward slash is necessary to tell git this is a directory not a file, and all sub-directories match this pattern.
• you added a whitespace after “gitdir:..”, so it became something like gitdir: ~/office/ instead of gitdir:~/office. This minor thing can also cause problem

Link GitHub with git

When you push your commit to remote repo, GitHub looks for the email associated with git to identify the user. Depending on what level of git account is set up, the contributor could be different, but the general rule of thumb is, local git is the first to be checked. If local git is missing, global git will be used. Let’s start with the simplest scenario:

local git is set

The local git here refers to the project level git. If it is set up, regardless of what global git setting is, GitHub will always use the local git email, match the GitHub user with the same email address, and make this user a “contributor”. The right GitHub handle and profile will also be shown on the repo page, instead of the user.name you set up for local git.

A potential problem with this is, you can have one user commit to another user’s repo. Suppose that under your personal project repo, you set up local git with your office email, then when making a push, the contributor becomes your office GitHub account. So make sure the git config is what you want, or you can set up default git to avoid the hassle.

local git is not set, but global git is available

Whenever local git is not available, the global git is used, again, via email. If the email registered in git is not a valid GitHub user account’s email, you will still be able to push, but just not able to associate that with a valid GitHub profile. In this case, the git user.name will appear in the commit history. Suppose you named global git user.name as “global-git”, it’d appear like this:

Figure 4: global git user.name

Summary

pull:

• to clone/pull a public repo, you can use github.com, or any of the host alias you set up (such as the ones mentioned in the last post: github-personal and github-office)
• to clone/pull a private repo, you need to use the host alias that is associated with the right GitHub account.
• you do not need to set up a git account if you just want to pull a repo, ie: you can pull as long as the SSH connection allows you to “read”.

push:

• to push/commit to a repo, you need to make sure host alias is the same one as the GitHub account that owns the repo (or the ones that have access to “write”). Otherwise it will fail, ie: the SSH connection must allow you to “write”.
• when commit to the remote repo from locally, the contributor is not automatically linked to your GitHub account. You need to set up git accounts in your machine, and the git account will tell GitHub which account it needs to associate the contributor to.
• anytime when local git is set up (the git account under the local repo directory), the contributor is linked to that local git account.
• if local git is not set up, your global git user will be used.
• git is associated with GitHub via git user.email, not user.name. Ie: if the user.name is different from your GitHub handle, but the user.email is the same, GitHub can successfully identify that it is the same person (ie: the GitHub profile will appear as a “Contributor” on the repo page).