Git Setup

SSH Keys

One-time setup of ssh keys to avoid needing a password with each repository transaction.

1. Create your ssh key using the ssh-keygen utility:

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

   2. Make sure that your ssh directory (~/.ssh) is readable only by you.

      $ chmod -R go-rwx ~/.ssh
      

2. Install the key in Bitbucket:

   1. Log in to http://mybitbucket.llnl.gov

   2. Click on the profile drop down in the far top right of the window and select “Manage Account”

   3. Click on the “SSH keys” link on the left of the screen and then “Add key”

   4. Paste your key into the text box. The text of the key is the contents of the file ~/.ssh/id_rsa.pub

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

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

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

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

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

1. 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"
   

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

Cloning the Repository

To clone a copy of the SUNDIALS repository use one of the following commands:

1. Clone the repository with SSH Keys:

   $ git clone ssh://git@mybitbucket.llnl.gov:7999/sundials/sunrepo.git
   

— OR —

1. Clone the repository with your OUN and AD password:

   $ git clone https://YourOUN@mybitbucket.llnl.gov/scm/sundials/sunrepo.git
   

After cloning the repository you will be on the develop branch by default however, the develop and master 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, 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.