
               Cheat Sheet for Git - 10 Aug 2017


This file contains details on setting up Git and helpful commands for working
with Git. For information on the Git workflow for SUNDIALS see the
gitWorkflow.txt file.
____________________________

SSH Keys (optional)

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

[Taken from: https://myconfluence.llnl.gov/pages/viewpage.action?pageId=99844309]

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

   a) 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

   b) Make sure that your ssh directory (~/.ssh) is readable only by you.
      > chmod -R go-rwx ~/.ssh

   c) Copy the ssh key to any other machines that you want to be able to SSH to:
      > ssh-copy-id <destination host name>

2. Install the key in Bitbucket:

   a) Log in to http://mybitbucket.llnl.gov
   b) Click on the profile drop down in the far top right of the window and
      select "Manage Account"
   c) Click on the "SSH keys" link on the left of the screen and then "Add key"
   d) 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 at https://git-scm.com/docs/git-config

[ NOTE: 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.
   > git config --global push.default simple

   --- OR ---

   [push]
       default = "simple" # push current branch to upstream branch with same name

   [ NOTE: 'simple' became the default setting in Git v2.0 ]

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 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:

   [merge]
       # which merge tool Git should use
       tool = meld
   [mergetool]
       # prompt before each invocation of the merge tool
       prompt = false
   [mergetool "meld"]
       # command to invoke the merge tool for meld 1.3.1
       cmd = meld "$LOCAL" "$MERGED" "$REMOTE"

   For Newer Version of Meld the first two settings are the same and the last
   setting is:

   [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]
       # prompt before each invocation of the diff tool
       prompt = false
   [difftool "meld"]
       # command to invoke the diff tool
       cmd = meld "$LOCAL" "$REMOTE"
____________________________

Cloning the SUNDIALS Repository

After cloning the repository you will be on the 'develop' branch by default. You
cannot work directly on the 'master' or 'develop' branches as you are not
allowed to push to these branches. You must branch from 'master' or 'develop'
and create a pull request to have changes merged into the parent branch. See the
gitWorkflow.txt file for more information.

A. Clone the repository with SSH Keys:
   > git clone ssh://git@mybitbucket.llnl.gov:7999/sundials/sunrepo.git

--- OR ---

B. Clone the repository with your OUN and AD password:
   > git clone https://YourOUN@mybitbucket.llnl.gov/scm/sundials/sunrepo.git
____________________________

Helpful Git Commands

Command Help

  Common Git commands used in various situations
  > git --help

  Print full man page for a Git command
  > git <git-command> --help

  Print description of available options for a Git command
  > git <git-command> -h

Graphical Tools (availability depends the Git installation)

  Visualize repo history
  > gitk

  Graphical interface to Git
  > git gui

Branch

  List all local branches (* denotes the current branch)
  > git branch

  List all local branches with additional information
  > git branch -vv

  List all remote branches
  > git branch -r

  Create a new branch from an existing reference point (e.g. branch, commit
  hash, etc.)
  > git branch <new-branch-name> <reference>

  Create a new branch from an existing reference point (e.g. branch, commit
  hash, etc.) and immediately checkout the new branch
  > git checkout -b <new-branch-name> <reference>

Add

  Stage local changes to a file
  git add <file-name>

  Stage changes from a file in chunks
  git add -p <file-name>

  Unstage a committed file
  git reset HEAD -- <file-name>

  Abandon local changes to a file and get the previously committed version
  > git checkout -- <file-name>

Commit

  Commit staged files, this opens an editor for writing a commit message, an
  empty commit message will abort the commit
  > git commit

  The desired format for a commit message is a short descriptive title followed
  by a blank line, and then a detailed commit message. For example, a commit
  turning on new regression tests might have following message:

      Turning on regression tests with 32bit integers

      Updated testing script to run sunindextype = 32bit_t. The following
      regression tests fail:
          *  16 - fark_roberts_dnsL
          *  17 - ark_bruss
          *  38 - fcvAdvDiff_bnd
          *  41 - fcvRoberts_dns
          *  42 - fcvRoberts_dnsL
          * 100 - fidaRoberts_dns
          * 101 - fidaRoberts_dns_openmp

  Commit staged files with short message
  > git commit -m "short commit message"

  Amend the most recent commit (assuming it has not been pushed) to include the
  changes in this commit.
  > git commit --amend

  This is useful for adding forgotten changes to the last commit or for editing
  the commit message in the last commit (if not files are staged).

Push / Pull

  Push a new branch and its commits to the remote repository and set the
  upstream tracking branch
  > git push -u origin <branch-name>

  Push committed changes on the current branch to the remote repository
  > git push

  [ NOTE: This is the same as 'git push origin <current-branch-name>' ]

  Fetch and merge remote changes for the current branch
  > git pull

  [ NOTE: This is the same as 'git pull origin <current-branch-name>' ]

  Fetch and merge changes from a specific remote branch into the current branch
  > git pull origin <branch-name>

  Fetch and rebase remote changes for the current branch
  > git pull --rebase

  [ NOTE: USE CAUTION when rebasing, see 'Notes on Rebasing in the
    gitWorkflow.txt file for more details ]

  Fetch and rebase changes from a specific remote branch into the current branch
  > git pull --rebase origin <branch-name>

  [ NOTE: USE CAUTION when rebasing, see 'Notes on Rebasing in the
    gitWorkflow.txt file for more details ]

Merge

  Merge a different local branch to your current branch
  > git merge <branch-name>

  Resolve merge conflicts with a visual diff/merge tool
  > git mergetool

  Find the newest common ancestor (fork point) of two reference points
  (branches, commits, etc.)
  > git merge-base <branch1> <branch2>

Status / Diffs

  Print information on current local repo status including unstaged (changed and
  not added) files, staged (changed and added) files, and untracked files.
  > git status

  Show ALL differences between unstaged changes and the current HEAD
  > git diff

  Show the differences between unstaged changes and the current HEAD for a
  specific file
  > git diff <file-name>

  Show differences between ALL staged files and current HEAD
  > git diff --staged

  List ALL files changed in the current branch compared to different reference
  point (branch, commit hash, etc.)
  > git diff --name-only <reference>

  Compare files between two branches
  > git diff <branch1>..<branch2> -- <file-name>

  To view the differences going from the remote file to the local file
  > git diff remotename/branchname:remote/path/file1.txt local/path/file1.txt

  To view the differences going from the local file to the remote file
  > git diff HEAD:local/path/file1.txt remotename/branchname:remote/path/file1.txt

  To view the differences between files at any two reference points (e.g.
  branches, commit hashes, etc.)
  > git diff ref1:path/to/file1 ref2:path/to/file2

  [ NOTE: In the above commands 'diff' can be replaced with 'difftool' if a
    visual diff tool has been setup with Git. ]

Log

  Show commit log
  > git log

  Show commit log with more change information
  > git log --stat

  Show all commits impacting a specific file
  > git log <file-name>

Stash

  Save uncommitted changes in the stash
  > git stash save <stash-message>

  View saved changes in the stash
  > git stash list

  Apply changes from the stash
  > git stash apply <stash-name>

  Remove changes from the stash
  > git stash drop <stash-name>

  Show difference between current HEAD and stashed work
  > git stash show -p <stash-name>
