16.2.1. Git Setup
16.2.1.1. SSH Keys
One-time setup of ssh keys to avoid needing a password with each repository transaction.
Create your ssh key using the ssh-keygen utility:
Skip this first command if you already have a public/private ssh key (i.e., you already have an
id_rsa.pub
file in your~/.ssh
directory):$ ssh-keygen -t rsa
Make sure that your ssh directory (
~/.ssh
) is readable only by you.$ chmod -R go-rwx ~/.ssh
Install the key in GitHub following the instructions here
16.2.1.2. Git Configuration
Global Git configuration information is stored in ~/.gitconfig
and can be
set with the git config --global
command or by editing the .gitconfig
file manually. More information is available in the git config documentation. Note in the comments in the
.gitconfig
file begin with #
.
Tell Git who you are:
$ git config --global user.name "Your Name" $ git config --global user.email "yourname@example.com"
— OR —
[user] name = Your Name # name recorded in commits email = yourname@example.com # email recorded in commits
Tell Git to only push changes on your current branch and only if the upstream branch has the same name i.e., don’t default to push changes to all branches or branches with a different name. Note the behavior is the default beginning with Git v2.0.
$ git config --global push.default simple
— OR —
[push] default = "simple" # push current branch to upstream branch with same name
Tell Git about the .git-blame-ignore-revs file.
git config blame.ignoreRevsFile .git-blame-ignore-revs
Tell Git which editor you want to use by default (e.g., Emacs):
$ git config --global core.editor "emacs"
— OR —
[core] editor = emacs # default editor
Enable color output in Git
$ git config --global color.ui "true"
— OR —
[color] ui = true # enable color output
The following settings enable using a graphical diff tool to resolve conflicts during a merge or when viewing diffs between files. These settings are optional but may be useful. The settings below are given for the meld diff tool. Similar settings can be used with emerge, gvimdiff, kdiff3, vimdiff, and tortoisemerge.
To add a merge tool (invoked by
git mergetool
), add the following to the~/.gitconfig
file:[mergetool "meld"] # command to invoke the merge tool for newer versions of # meld which use the '--output' option cmd = meld "$LOCAL" "$MERGED" "$REMOTE" --output "$MERGED"
To add a diff tool (invoked by
git difftool
), add the following to the~/.gitconfig
file:[diff] # which diff tool Git should use tool = meld [difftool] # do not prompt before each invocation of the diff tool prompt = false [difftool "meld"] # command to invoke the diff tool cmd = meld "$LOCAL" "$REMOTE"
Additionally, Git provides helpful scripts to enable auto-completion of Git
commands and to display the current status in the command line prompt for
various shells. The scripts git-completion.*
and git-prompt.sh
can be
obtained from the contrib/completion directory in the Git source
repository on GitHub.
For example with Bash, auto-completion can be enabled by adding
source <some-path>/git-completion.bash
to your .bashrc
file. Similarly displaying the Git command line prompt
information can be enabled by adding
export GIT_PS1_SHOWDIRTYSTATE="true" # unstaged *, staged +
export GIT_PS1_SHOWSTASHSTATE="true" # stashed $
export GIT_PS1_SHOWUNTRACKEDFILES="true" # untracked %
export GIT_PS1_SHOWUPSTREAM="auto verbose" # ahead +, behind -, diverged +-, same =
export GIT_PS1_SHOWCOLORHINTS="true"
source <some-path>/git-prompt.sh
export PROMPT_COMMAND='__git_ps1 "[$(date +%k:%M:%S)] \u@\h \w" "\n$"'
to your .bashrc
file.
16.2.1.3. Cloning the Repository
To clone a copy of the SUNDIALS repository use one of the following commands:
Clone the repository with SSH Keys:
$ git clone --recurse-submodules git@github.com:LLNL/sundials.git
— OR —
Clone the repository with https (requires authenticating with your username and password or access token to push)
$ git clone --recurse-submodules https://github.com/LLNL/sundials.git
After cloning the repository you will be on the main
branch by default
however, the develop
and main
branches are protected branches and can
not be updated directly. In order to make changes to either of these branch you
must create a new branch from develop
, make the desired modifications, and
issue a pull request to have the changes merged into the parent branch. See the
Workflow section for more information.