Git Configuration Standards & Recommendations

This page collects advice for configuring Git for DM development.

Some of these configurations are mentioned in the DM Development Workflow with Git, GitHub, JIRA and Jenkins. Such configurations are labeled on as page as required (as opposed to recommended practices).

See also:

Learning Git

If you’re new to Git, there are many great learning resources, such as

Use your institution’s email with Git & GitHub

We use Git commit authorship metadata to audit copyrights in DM code (RFC-45, for background).

In Git (required configuration)

Ensure that Git is set up to use your institution-hosted email address (only AURA employees should use their lsst.org email addresses) in the ~/.gitconfig file. You can do this from the command line:

git config --global user.name "Your Name"
git config --global user.email "your_email@institution.edu"

You might not want to use your institution’s email when you contribute to non-LSST projects. Since Git 2.13, you can set directory-based conditional configurations. For example, if you always work on LSST projects from your ~/lsst/ directory, you can add this to the bottom of your ~/.gitconfig file:

[includeIf "gitdir:~/lsst/"]
path = .gitconfig-lsst

Then in a ~/.gitconfig-lsst file, set your LSST-specific configurations:

[user]
name = Your Name
email = your_email@institution.edu

Whenever you work on a repository inside ~/lsst/, the configurations in ~/.gitconfig-lsst are applied, and possibly override previous configurations from the ~/.gitconfig file.

On GitHub

Likewise, in your GitHub account email settings, add your institution-hosted email.

We recommend that you set this institutional email as your Primary GitHub email address. This step ensures that Git commits you make directly on GitHub.com (such as quick documentation fixes) and merges made via the ‘big green button’ have proper authorship metadata. Alternatively, remember to choose your institution email from the email address drop-down menu before committing. See the GitHub help page Editing files in your repository for details.

Set up Two-Factor Authentication (2FA) for GitHub

We encourage you to enable Two-Factor Authentication (2FA) for GitHub through your account security settings. 2FA means that you’ll have to enter an authentication code when logging into GitHub.com from a new computer. Apps like 1Password (see their guide), Authy, and the Google Authenticator App can help you generate these authentication codes. When pushing commits with a 2FA-enabled account, you’ll use a personal access token instead of your password. You can create and revoke tokens from your GitHub settings page. To help you automatically authenticate when pushing to GitHub, we encourage you to follow the next step and enable a credential helper.

Set up a Git credential helper

Rather than entering your GitHub username and password (or 2FA access token) every time you push, you can set up a Git credential helper to manage this for you. A credential helper is especially important for working with our Git LFS-backed repositories.

Mac users can use the secure macOS keychain:

git config --global credential.helper osxkeychain

Linux users can use a credential cache to temporarily keep credentials in memory. To have your credentials cached for 1 hour (3600 seconds):

git config --global credential.helper 'cache --timeout=3600'

Linux users can alternatively have their credentials stored on disk in a ~/.git-credentials file. Only do this for machines where you can ensure some level of security.

git config --global credential.helper store

Once a credential helper is enabled, the next time you git push, you will add your credentials to the helper.

Remember that if you have 2FA enabled, you will create and use a personal access token instead of your GitHub password.

If you find that git push is not working but also not asking you for credentials, you may need to manually insert the username/password or token into the credential store or macOS keychain.

The DM Git LFS documentation has further information about authenticating with our LFS storage backend.

Tune your shell for Git

You can build an effective development environment and workflow by tuning your Git setup. Here are some ideas:

  1. Add git status to your prompt (see the instructions under “To enable:” at the top of the file). Some more complicated suggestions are discussed on this Community thread, including this git bash prompt project. Colorized git information in your prompt can help you easily know what branch you are on, or if you forgot to finish a rebase.

  2. Enable shell autocompletion, to allow things like tab-completing git branch names and files to commit. Linux users can install the “bash-completion” package to automatically gain this, and other, autocomplete functionality.

  3. Craft aliases for common workflows.

  4. Use hub to interact with GitHub features from the command line.

Set up your editor

You’ll want to configure your preferred editor (or its command line hook) as your Git editor. For example:

git config --global core.editor "vim"
git config --global core.editor "emacs"
git config --global core.editor "atom --wait"
git config --global core.editor "subl -n -w"

See GitHub’s help for setting up Atom and Sublime Text as Git editors.

Useful Git aliases and configurations

You can craft custom Git commands (aliases) in your ~/.gitconfig to refine your workflow. When you run an alias (git <alias> [arguments]) the alias’s name is effectively replaced with the alias’s content in the command line statement.

Here are some aliases try in ~/.gitconfig:

[alias]
    # List things
    tags = "tag -l"
    branches = "branch -a"
    remotes = "remote -v"

    # Shorten common commands
    co = "checkout"
    st = "status"
    br = "branch"
    ci = "commit"
    d = "diff"

    # Log that shows titles of last 16 commits
    l = "log -16 --color=always --all --topo-order --pretty='%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"

    # Log that starts a pager with titles of all the commits in your tree
    ll = log --color=always --all --topo-order --pretty='%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

    # Log that shows the last 10 commits as a graph
    lg = "log -10 --color=always --all --graph --topo-order --pretty='%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"

    # Log that shows all commits as a graph (using a pager)
    lgl = "log --color=always --all --graph --topo-order --pretty='%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

    # Show outgoing commits
    out = "log @{u}.."

    # Print the title of the current branch; sometimes useful for scripting
    currentbranch = "!git branch --contains HEAD | grep '*' | tr -s ' ' | cut -d ' ' -f2"

    # Better diffs for prose
    wdiff = "diff --color-words"

    # Safer pulls; don't do anything other than a fast forward on merge
    pull = "pull --ff-only"

    # Amend last commit without modifying commit message
    amend = "!git log -n 1 --pretty=tformat:%s%n%n%b | git commit -F - --amend"

    # Create a commit that will be automatically squashed as a fixup when you
    # run `git rebase --autosquash`
    fixup = "commit --fixup=HEAD"

Configure ‘plain’ pushes in Git (required for Git prior to v2.0)

Note

This behavior is the default for Git v2.0 and later; this section is only here for reference for those coming from an earlier version of git who may have set a different config option for this.

In earlier versions of Git, push.default=matching was the default. See the git-config documentation for details.

Ensure that git push only pushes your currently checked-out branch by running this command:

git config --global push.default simple

This command modifies ~/.gitconfig.