Wiki

Clone wiki

petsc / quick-dev-git

Quick Summary of Git Commands for PETSc Developers

This is a quick summary of Git commands for our workflow. Read the detailed description for more details.

Setup

  • Set your name: git config --global user.name "Barry Smith"
  • Set your email: git config --global user.email "me@example.com"
  • Do not push local branches nonexistent on upstream by default: git config --global push.default simple (older versions of git require git config --global push.default tracking)

Starting and Working on a New Feature Branch

  • Make sure you start from master: git checkout master
  • !! NEVER create a branch from next !!
  • Create and switch to a new feature branch:

     git checkout -b <loginname>/<affected-package>-<short-description>
    

    For example, Barry's new feature branch on removing CPP in snes/ will use

    git checkout -b barry/snes-removecpp. Use all lowercase and no additional underscores.

  • Write code

  • Inspect changes: git status
  • Commit code:
    • Commit all files changed: git commit -a or
    • Commit selected files: git commit file1 file2 file1 or
    • Add new files to be committed: git add file1 file2 followed by git commit. Modified files can be added to a commit in the same way.
  • Push feature branch to the remote for review: git push -u origin barry/snes-removecpp

    (or equivalently, git push --set-upstream origin barry/snes-removecpp)

Switching between and Handling Branches

  • Switch: git checkout <branchname>, for example git checkout barry/snes-removecpp
  • Show local and remote-tracking branches: git branch -a
  • Show available remotes: git remote -v
  • Show all branches available on remote: git ls-remote. Use git remote show origin for a complete summary.
  • Delete local branch: git branch -d <branchname> (only after merge to master is complete)
  • Delete remote branch: git push origin :<branchname> (mind the colon in front of the branch name)
  • Checkout and track a branch available on remote: git checkout -t knepley/dm-hexfem (if you inspect other feature branches, e.g. Matt's hexfem feature branch).

    If you have multiple remotes defined, use git checkout -t <remotename>/knepley/dm-hexfem, e.g. git checkout -t origin/knepley/dm-hexfem

  • Checkout a branch from remote, but do not track upstream changes on remote: git checkout --no-track knepley/dm-hexfem

Merging a Feature Branch into Next

  • Check out next-branch: git checkout next
  • Ensure that you are up-to-date: git pull
  • Merge via git merge barry/snes-removecpp
  • Push back to server: git push origin next
  • !! Never merge next into your branch !!

Merging directly to Master

  • !! Don't do this unless you are certain that the feature-branch does not break master !!
  • git checkout master
  • git pull
  • git merge barry/snes-removecpp
  • git push origin master
  • !! Never merge next into master !!

Retry after losing a merge race

  • You have lost a merge race if you try to push and see: ! [rejected] next -> next (fetch first)
  • Fix by discarding your merge, and trying again:

    git reset --hard HEAD^ git pull git merge my/topic-branch ... build and test ... git push

Reading Commit Logs

  • Show logs: git log
  • Show logs for file or folder: git log file
  • Show changes for each log: git log -p (add file or folder name if required)
  • Show diff:
    • Current working tree: git diff path/to/file
    • To other commit: git diff <SHA1> path/to/file
    • Compare version of file in two commits: git diff <SHA1> <SHA1> path/to/file
  • Show changes that are in master, but not yet in my current branch:
    • At any path: git log ..master
    • Only affecting a path: git log ..master src/dm/impls/plex/
    • In my branch, but not yet in next: git log next.. src/dm/
    • Tabulated by author: git shortlog v3.3..master src/dm/impls/plex
  • Showing branches:
    • Not yet stable: git branch --all --no-merged master
    • Being tested by early users: git branch --all --merged next
    • Will be in the next release: git branch --all --merged master
    • Remove --all to the above to not include remote tracking branches (work you have not interacted with yet).
  • Find where to fix a bug:
    • Find the bad line (e.g., using a debugger)
    • Find the commit that introduced it: git blame path/to/file
    • Find the branch containing that commit: git branch --contains COMMIT (usually one topic branch, plus next)
    • Fix bug: git checkout topic-branch-name, fix bug, git commit, and merge to next, etc.

Miscellaneous

  • Discard changes to a file which are not yet committed: git checkout path/to/file
  • Discard all changes to the current working tree: git checkout -f
  • Forward-port local commits to the updated upstream head on master: git rebase master (on feature branch)
  • Delete local branch: git branch -D <branchname>
  • Delete remote branch: git push origin :<branchname> (only after successful integration into master)

Updated