Configuration & Recommendations#

Caution

This guide has been based on LSST’s Git guide. Please respect the creators and contributor of the original guide as they have done an external work.

This page collects advice for configuring Git for project development.

Some of these configurations are mentioned in the flow. Such configurations are labeled on as page as required (as opposed to recommended practices).

Learning Git#

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

Git’s online docs, and the associated online Pro Git book by Scott Chacon and Ben Staubb.
GitHub Help, which covers fundamental git usage too.
StackOverflow.

Use your employer-hosted email with Git & GitHub#

We use Git commit authorship metadata to audit copyrights project code.

In Git (required configuration)#

Ensure that Git is set up to use your employer-hosted email address in the ~/.config/git/config file. You can do this from the command line:

git config --global user.name "Your Name"
git config --global user.email "your_email@employer.com"

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

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

Then in a ~/.gitconfig-employer file, set your employer configurations:

[user]
name = Your Name
email = your_email@employer.com

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

On GitLab#

Likewise, in your GitLab profile commit email settings, add your employer-hosted email.

We recommend that you set this employee email as your Primary GitLab email address. This step ensures that Git commits you make directly on GitLab.com (such as quick documentation fixes) and merges made via the ‘big blue button’ have proper authorship metadata.

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

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

git config --global push.default simple

This command modifies ~/.config/git/config.

Note

This behavior is the default for Git v2.0 and later.

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

Set up Two-Factor Authentication (2FA) for GitLab#

We encourage you to enable Two-Factor Authentication (2FA) for GitLab through your account settings. 2FA means that you’ll have to enter an authentication code when logging into GitLab.com from a new computer. Apps like 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 account settings. To help you automatically authenticate when pushing to GitLab, we encourage you to follow the next step and enable a credential helper.

Set up a Git credential helper#

Rather than entering your GitLab username and password (or 2FA access token) every time you push, you can set up a Git credential helper to manage this for you.

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 GitLab 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.

Tune your shell for Git#

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

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 "atom --wait"
git config --global core.editor "code --wait"
git config --global core.editor "subl -n -w"

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

Useful Git aliases and configurations#

You can craft custom Git commands (aliases) in your ~/.config/git/config 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 ~/.config/git/config:

[alias]
    # SVN-like shortcuts for often used commands:
    br = branch
    ci = commit
    co = checkout
    di = diff
    st = status

    # Git-like SVN specific commands
    spull = svn rebase
    spush = svn dcommit

    # Shortcuts for often used commands:
    amend = commit --amend --no-edit
    undo = reset --soft HEAD~1
    reword = commit --amend

    # Logs:
    lg1 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
    lg2 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold cyan)%aD%C(reset) %C(bold green)(%ar)%C(reset)%C(bold yellow)%d%C(reset)%n''          %C(white)%s%C(reset) %C(dim white)- %an%C(reset)' --all
    lg = !"git lg1"

    # List available aliases
    aliases = !"git config --get-regexp alias | sed -re 's/alias\\.(\\S*)\\s(.*)$/\\1 = \\2/g'"

    # List local commits that were not pushed to remote repository
    local = !"git lg @{push}.."

[color]
    branch = always
    decorate = always
    diff = always
    grep = always
    interactive = always
    pager = true
    showbranch = always
    status = always
    ui = true

[color "branch"]
    current = green bold
    local = white
    remote = yellow

[color "diff"]
    plain = normal
    meta = bold
    frag = cyan
    old = red bold
    new = green bold
    commit = yellow
    whitespace = normal red

[color "grep"]
    linenumber = magenta bold
    match = yellow bold
    filename = magenta

[color "interactive"]
    prompt = normal
    header = normal bold
    help = normal
    error = red

[color "status"]
    added = green
    changed = yellow
    untracked = red

[core]
    autocrlf = false
    editor = code --wait

[help]
    autocorrect = 1

[status]
    showUntrackedFiles = all


[merge]
    tool = meld

[mergetool "meld"]
    cmd = meld $LOCAL $BASE $REMOTE -o $MERGED
    keepBackup = false
    trustExitCode = false


[diff]
    tool = meld

[difftool "meld"]
    cmd = meld $LOCAL $REMOTE


[user]
    name = "<ENTER YOUR NAME>"
    email = "<ENTER YOUR EMAIL>"