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.
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.
- 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 unless you wipe out your entire local repository, and you can easily undo the commit with git reset or change the commit later with git commit --amend.
- 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.
- If your change is already coded and you're not comfortable with Git merges, don't try to pull before pushing. Just push the change to the review server, and a committer can merge any conflicts. Please pull before starting new work, however.
One Time Setup
- Read the Lyo's Contributor's Guide for setting up Git for Gerrit and Lyo.
- Add Change-Id 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.
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. You can add the files one by one or stage an entire src directory with git add src. See the git-add Manual Page and this Stack Overflow post for more.
$ git status $ git add <files>
- Commit the change.
$ git commit -s -m "Bug 414605 - Add JUnits for testing URI resolution"
- (Optional) If you have an editor configured for Git, you may add a more descriptive message. Instead of the above command, leave off the -m flag.
$ git commit -s
When the editor appears, you can enter more paragraphs. 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 <firstname.lastname@example.org>
The first line should have the bug ID and a short description. Ideally this fits on one line because in some views it's all that's displayed.
Add one or more paragraphs below with additional details.
The end of the commit message has the Signed-off-by and Change-Id. The Change-Id may not be visible in the editor, but will be inserted automatically by Git if you added the commit-msg hook above. The Signed-off-by was created when you use -s when committing. If there were additional contributors, you may add an Also-by. No descriptive text can be added below these values or Gerrit will reject the push, and they have to be separated by an empty line.
- (Optional) Review your change before pushing with
$ git show
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 --no-edit $ git push review
As long as you have a Change-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>
You can mark you bug as validated if everything looks good at this point.