Jump to: navigation, search

GIT Cheat Sheet

Overview

This page is intended to provide some quick tips on getting started with GIT as well as provide some help tips. For more detailed description of git commands please search this wiki for addition pages on pulling, hacking and pushing code, such as this page GettingStarted:Pulling,_Hacking,_and_Pushing_All_the_Code_from_the_CLI.

GITK

GITK is a graphically tool that can help visually compare how any of your local and remote branches align with each other, as well as perform some of the basic tasks defined below. See GettingStarted:Development Environment Setup for details on how to install.

GIT Commands

The following GIT commands assume you have set up a gerrit account OpenDaylight_Controller:Gerrit_Setup for SSH access. These git commands should be run from the git repository root directory unless noted. The git repository root directory is the directory which contains the .git file (e.g. the 'controller' folder which is created when cloning the controller for example).

Download Source

  • Git clone copies down the initial source
git clone ssh://<user_name>@git.opendaylight.org:29418/<repository>.git

e.g.

git clone ssh://john_doe@git.opendaylight.org:29418/controller.git

Note: This command can be run from any directory. It will create a .git directory under the folder that the command is run from. This folder will become the .git repository root underwhich other .git commands should be run.

Automatically Generate Change IDs

  • Set up your git source to automatically generate change IDs
scp -p -P 29418 $<user_name>@git.opendaylight.org:hooks/commit-msg .git/hooks/;chmod 755 .git/hooks/commit-msg;

To Pull Down New Source

Retrieves new source from the repository. Note, if you have a local branch (see below) then this simply pulls the new source from the local head. See below for a sample workflow to update your local branch.

git pull

Get Information About your Current GIT Repository Status

Provides information about what local / remote branch you are tied too, distance from the head of the remote master branch, number of outstanding commits etc.

git status

Create Branch

Creates a local branch in which you can do work. A local branch essentially places a marker in the master code stream at the time the branch was created. Creating a local branch from master allows you to quickly reset and pull down the latest source without loosing any modifications you made. The follow command creates a new branch:
git branch <branch_name>  #creates the branch only, does not switch to it
Note 1: You can name a branch anything you want, such as a feature name, gerrit ID, or bug_zilla ID.


The above command does not switch you into your new branch. To do that you will need to follow the command in the next section. Optionally, you can create the branch and check it out in one command.
git checkout -b <branch_name>

Switching to and from a Branch

You can quickly switch to and from a branch in your .git repository by running:

git checkout <branch_name>

To switch back to the master branch, you can run

 git checkout master

Download the Latest Source to your Branch

Let assume you have a branch which was previous up to date in master. Time has now passed, and you want to bring down the rest of the changes from master and replay your changes on top. There are two ways to accomplish this. The first updates your master branch as well, the second updates just the branch.

To update your master and your branch:

  1. Commit or stash your changes
    git commit #see above for more details
    or
    git stash  #removes your changes and saves them for later retrieval
  2. Checkout master
    git checkout master  #move back to the master from the local branch
  3. Pull down the latest source
    git pull  #get the most recent version of master from origin
  4. Checkout the branch
    git checkout <branch>   #move back to the branch
  5. Rebase
    git rebase master # pulls down all of the source from master, and replays any of your commits on top.
  6. Pop the stash (if you stashed the files)
    git stash pop
A git pull is basically a git fetch, followed by a merge.

To update only your branch:

  1. Commit or stash your changes
    git commit #see above for more details
    or
    git stash  #removes your changes and saves them for later retrieval
  2. Fetch the latest source
    git fetch
  3. Rebase from origin/master
    git rebase origin/master
  4. Pop the stash (if you stashed the files)
    git stash pop
The disadvantage is that your local master will not be updated, but it is a more optimized flow.

Commit your Change

To commit your change ( i.e. stage the files you have modified to prepare them to get pushed to gerrit so others can access the changes), follow these steps.

  1. Add your files to the git index by running:
    git add <file_name>
    You can optionally skip this step and add the -a flag below to automatically add all modified files to the index.
  2. Mark the files in the index as a "Commit" by running the following commands:
    git commit -s  #The -s adds a "signed off" statement in the commit message. This is is required to push the commit to gerrit.
    Note 1: You can add the -a argument to add all modified files to the index here, skipping the step above.
    Note 2: You can install a git hook to avoid having to specify the -s eachtime. See this link for details.
  3. Add a comment to the editor that pops up. Note, the first line will be displayed as the subject. It is suggested that if your commit fixes a bug, that you start the subject with BUG <bug_zilla_id>. This should then be followed by a quick description of the change and your sign-off id (which should have been automatically added due to the -s argument above). For example:
    Bug 12345 - Fixed Version in Pom.xml
    
Modified the pom file to fix the version mismatch. Signed-off-by: jdoe <john.doe@example.com>

Note this will automatically create a new change ID (gerrit work item) when pushed. See below if you wish to add another patch to an existing change ID.

  • Finally push the commit to the remote system (and create a gerrit item).
    • To push a publicly visible work item (and thus kick off a Jenkins build):
      git push
    • To push a draft, which will only be visible to you and those who you add as a reviewer (and DONT start a jenkins build):
      git push ssh://<user_name>@git.opendaylight.org:29418/<repository>.git HEAD:refs/drafts/master
      e.g.
      git push ssh://johndoe@git.opendaylight.org:29418/controller.git HEAD:refs/drafts/master

To Add an Additional Patch to an Existing Change ID

There maybe times when you want to add additional files to an existing change ID. In this case you can follow these steps:

  1. Add (stage) files to the git index using the 'git add' or '-a' option as defined above.
  2. Commit files, but this time use the --amend argument for the git commit, indicating that we need to add files to an existing commit.
    git commit -a --amend -s
    Note the optional -a argument for adding all files to the git index'
    When the editor opens, the change ID should already be present in the description. This ID is the last change ID in your git repository. You can optionally modify the change ID to match the gerrit ticket that would would like to associate the change to.
  3. Push out your change publicly using 'git push' or keep it as a draft by specifying the draft (see previous example).

To Discard a Change from a Local Branch

When removing changes form your local branch you want to be careful to not go back too far in history.
git reset --hard HEAD~#
where the # can be replaced with any positive, non-zero number. This numer indicates how many commits you want to remove. This will delete the changes associated with the commit from this branch, overwriting any local changes. e.g.
git reset --hard HEAD~2   # goes back two changes

Get a Log of Recent Changes

To get a log of recent changes in your git branch you can run the following command:
git log
This will show details about all of the commits in your local branch, including IDs etc.

To Pull a Commit from one Local Branch to a Second Local Branch

To pull a commit from one local branch to a second branch you can use the git cherry-pick command. This allows you to pull a commit directly from one branch to another branch. First use git log in the source branch to determine the commit ID. Then use git cherry-pick to pull int the specific change.
git checkout branch1
git log  #note commit id
git checkout branch2
git cherry-pick <commit_id> #use commit ID noted above

Tips and Tricks

Create aliases for 'git'

  • Modify your bash/zsh to alias 'git' to 'g' to further avoid unnecessary typing.

Change your commit editor

  • You can change your git commit editor from vi to vim by running this command
    git config --global core.editor "vim"

Change the Author Name/Email

  • To change the author name or email used for signing off a commit you need to modify your git global config, by running these commands
    git config --local user.name "Your Name"
    git config --local user.email yourname@example.com

GIT Aliases

You can define aliases in your .gitconfig profile to save typing alot of commands. here is an example of a .gitconfig for a contributing member:

Show Gerrit notes in logs

Gerrit automatically creates a note for merged commits in refs/notes/review. This note contains useful information such as a list of reviewers, URL of the review, date of initial submission, etc. It is possible to make this information show up when running 'git log'. Inside the repo, run
git config core.notesRef refs/notes/review
Alterntively, if you don't want to make the change permanent, you can use the environment variable GIT_NOTES_REF:
GIT_NOTES_REF=refs/notes/review git log

Common Errors

[remote rejected] HEAD -> refs/for/master (you are not allowed to upload merges)

The above error is thrown during 'git push' because you committed on the master branch, and then pulled code, the remote master branch and your local master branch diverged, and had to merged. The remote master only allows fast forward commits, not merge commits. To resolve the above error, the following steps are recommended:

  1. Identify the commits sha_id
    git log
  2. Save the patch locally
    git show <sha_id> > patch
  3. Delete the local master branch
    git branch -D master
  4. Checkout the remote master branch
    git checkout -b master origin/master
  5. Create your local work branch off master
    git checkout -b <branch_name>
  6. Apply the saved patch
    git apply patch
  7. Push again.

When you modify and commit code, you should work on a local branch, different from master (or if you really want to work on master, you should push your changes before you pull new code).

Further Reading