Revision as of 15:56, 5 August 2014

One Committer's Git Tips

Git is powerful, but it has a steep learning curve. Following these tips will help you avoid some heartburn. Some of the advice is specific to Lyo, so consider skimming this even if Git is an old friend.

Use the Command Line

If you're new to Git, I recommend the command line for a few reasons:

• EGit, like Git, is powerful, but it has many UI elements and advanced options that can be confusing. The basic Git commands are fairly simple, however.
• WIth the Git command line, a Lyo committer can help you resolve problems by telling you the exact commands to run. This is easier than trying to guide you through a graphical interface.
• There are simply more resources out there to help you with the Git command line.

Having said that, EGit is a great tool. Install it as well. It shows you what projects are under Git source control and what files have changed, and it also has nice diff / compare tools among other features.

Create Branches

I recommend creating branches for your work in Lyo. The main reason: your contributions might be changed slightly by a committer (for instance, to merge them with another change). Keeping your local master branch always in sync with origin/master and free from other work makes it easy to pick up these changes. Otherwise, you need to run potentially destructive commands to get back in sync (e.g., git --reset hard origin/master), and it's easy to lose another pending change you forgot about.

Other Advice

• Commit any pending changes or use git stash before running git pull or a destructive command like git reset --hard. (Don't forget to stage your files with git add before committing!)

Once you've committed a change, you won't accidentally lose the code without wiping out your entire local repository, and you can easily undo the commit with git reset.

• If you have local commits that haven't been reviewed and merged, use git pull --rebase rather than git pull. If you use git pull and there's a conflict, you'll end up with a merge commit that Gerrit will reject next time you push. Rebasing instead will replay your changes on top of the latest from origin, making sure you can push without errors.

Note: if you follow the suggested workflow below, this won't be an issue and shouldn't be necessary.

• Don't forget to git pull before starting any new work to avoid merge headaches later.
• You don't have to pull before pushing a change to our review server if you're not comfortable with Git merges. A committer can merge your changes for you. Please pull before starting new work, however.

Setting Up Git for Lyo

• Add change IDs to your commits by following the instructions Install the commit-msg hook in your repository.
• Follow the instructions in Adding a dedicated remote, which sets up the command git push review.

Suggested Workflow

This workflow should make contributing easy.

When starting new work

• Check the status of your repository. This will tell you the current branch and what pending edits you have. If you have uncommitted changes, stash them (or optionally commit them if not on the master branch).

   $ git status
   $ git stash

• If not on master, check out master. Note that if you didn't stash pending changes, they will follow you to the master branch.

   $ git checkout master

• Update your local repository with git pull. (If you've followed the advice above, you shouldn't have any other commits in your master branch, so you don't need --rebase.)

   $ git pull

• Create a branch for your work.

   $ git checkout -b <your_bug_id>

• (Optional) If you want to restore changes stashed above, run

   $ git stash apply

• Code your change.
• Run any unit tests.
• Stage the files with git add and commit. You can add the files one by one or stage an entire src directory with git add src. See the git-add Manual Page.

   $ git status
   $ git add <files>
   $ git commit -s

• Include the bug ID and a descriptive message in the commit. For example,

   Bug 414605 - Add JUnits for testing URI resolution
   
   Switch to default Maven directory structure and add JUnits to test
   public URI configuration and disabling hostname resolution.
   
   Change-Id: I80487ad74ddf158f860db77f56110294c6e25c7b
   Signed-off-by: Samuel Padgett <spadgett@us.ibm.com>

The change ID will be inserted automatically by Git if you added the commit-msg hook above.

• (Optional) Review your change before pushing with

   $ git show HEAD

You can always amend the commit if things aren't right with git commit --amend (see below).

• When ready, push to the review server.

   $ git push review

• Add Samuel Padgett as a reviewer in Gerrit.

If you receive any comments during review

• Code any additional changes.
• Run any unit tests.
• Amend your commit and upload a new a patch set.

   $ git status
   $ git add <changed files>
   $ git commit --amend
   $ git push review

As long as you have a commit ID in your commit message, this will add a new patch set to the existing review.

After your change has been integrated

Switch back to the master branch, get the latest code, and delete your topic branch.

   $ git checkout master
   $ git pull
   $ git branch -D <your_bug_id>