Recommended git setup
Contents
There are a number of required settings and a number of other helpful settings to streamline your git experience. These settings need to be made once per machine. They apply for all git repositories that you work with on that machine.
The following settings are used to add author information to your commits:
git config --global user.name "Your Name" git config --global user.email [email protected]
You can set which editor to use for log messages, etc., with:
git config --global core.editor [editor of your choice: emacs, vi, vim, etc]
This setting generates better patches than the default:
git config --global diff.algorithm histogram
This setting is unnecessary for Git 2.0 or later, but helps when using an older version. This ensures that only the currently checked-out local branch will be pushed to the remote repository (e.g., your GitHub fork):
git config --global push.default simple
The following settings are mainly useful for integrators - that is, people who are making changes to the master branch.
This is important when merging a branch to master, in order to create
actual merge commits; it is equivalent to specifying --no-ff when
doing a merge:
git config --global merge.ff false
This prevents you from using git pull if your local branch has
evolved. This is particularly important when working with master, with a
typical workflow of doing git pull in order to update your local
copy of master:
git config --global pull.ff only
You do not need a GitHub account to simply clone and run CTSM. However, you will need a GitHub account in order to contribute changes back.
If you will be pushing changes to GitHub (either to your own fork or to shared forks), or if you will be pulling changes from private repositories on GitHub, then it's worth the time to set up ssh keys for each machine you'll be using. By doing so, you won't have to enter your password when pushing to or pulling from GitHub.
See https://help.github.com/articles/connecting-to-github-with-ssh/ for
instructions. After doing this, you can use the ssh form of GitHub URLs
(e.g., [email protected]:ESCOMP/ctsm.git) in place of the https form.
There are two helpful things you can do to streamline your use of git if you use the bash shell. These are also documented here: https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Bash
With bash, many command-line tools support smart tab-completion, so that
(for example) if you type git ch[Tab], you will get a list of
possible completions; if there is only one possible completion (e.g.,
git chec[Tab]), it will be filled in for you.
On a mac, if you use homebrew, you can install bash completion for many
commands with brew install bash-completion, and there are probably
similar things you can do on other systems.
To just install bash completion for git, you can copy
https://github.com/git/git/blob/master/contrib/completion/git-completion.bash
to some location on your system, then add the following to your
.bashrc file:
source /path/to/git-completion.bashIt can sometimes be hard to keep track of the state of your working copy: you could have changes that are committed but not yet pushed, changes that have been staged but not committed, and/or changes that have not yet been staged. There are git commands to show you these things, but it can be more convenient to have that information right in front of you in your terminal at all times. This is where git-prompt comes in.
For example, I have configured my prompt to look like this:
or:
The magenta line shows the git information. This shows:
- What branch I'm on (master)
- Whether there are changes that have not yet been staged with
git add, indicated by a* - Whether there are chagnes that have been staged but not yet committed,
indicated by a
+ - If the current branch has an upstream tracking branch: Whether this
branch is up-to-date with the upstream branch (indicated by
=), ahead of the upstream branch (indicated by>: in this case, you should do agit pushat some point), or behind the upstream branch (indicated by<- for example, if you have fetched from the upstream but not yet merged into your local branch). (It's also possible to see<>, in which case there are some commits that exist only in your local branch and some other commits that exist only in the upstream branch; this can happen after a rebase.)
The git prompt can be configured in many ways to suit your needs. In my case, I have the entire path in my standard bash prompt, so I wanted the git prompt on a separate line to avoid having an even longer prompt line.
You can obtain git-prompt.sh from
https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh
. Put this anywhere on your system, then add the following in your
.bashrc file:
source /path/to/git-prompt.shThere are a number of environment variables that you can set to control
git-prompt. The two I find most useful are these (which I have in my
.bashrc file after the above source command):
export GIT_PS1_SHOWDIRTYSTATE=1
export GIT_PS1_SHOWUPSTREAM="auto"Caution: I recommend NOT setting GIT_PS1_SHOWDIRTYSTATE on super-computers with slow file systems (e.g., cheyenne).
Finally, you need to set your prompt variable. I use:
export PS1='\[\e[1m\]\[\e[35m\]$(__git_ps1 "(%s)\n\[ \b\]")\[\e[0m\][\h:\w]\$ 'Here are details on the above prompt, if you're interested:
- The key part is
__git_ps1, which inserts the prompt from git-prompt. - My basic prompt is given by
[\h:\w]\$, which prints the hostname and current working directory in square brackets, followed by$. - Inserting a newline in a pretty way was tricky. I managed to
accomplish this by giving git-prompt the formatting argument
(%s)\n\[ \b\]:\nis a newline, but without anything following the newline character, the newline didn't appear for some reason. You can fix this simply by putting a space after the newline, but I didn't like that, aesthetically. Putting a backspace (\b) after the space fixed that problem, but resulted in problems with line wrapping. Enclosing the space and backspace in\[ ... \]fixed the line wrapping problem (treating the combination as a non-printing character, I think). - Most of the rest of the prompt controls the colors
We highly recommend the free pdf book Pro Git. The first three chapters, along with sections 6.1 and 6.2 on GitHub, are particularly useful if you're getting started with git.
Git also offers extensive built-in help, although it can be hard to understand until you are familiar with basic git concepts:
git help git help COMMAND