Lyo/GitTips

Git is powerful, but it has a steep learning curve. Here are some tips for using Git to contribute to Lyo.

Use the Command Line

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

• EGit is powerful, but it has many UI elements that can be confusing for new users. 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 any destructive command like "git reset --hard". (Don't forget to stage your files for commit first!) If you've committed your changes at some point, it's virtually impossible to lose them short of wiping out your entire Git repository, and you can always 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.
• Don't forget to do a "git pull" before starting any new work to avoid merge headaches later.
• You don't really 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

• If you have uncommitted changes, stash them.

   $ git stash

• If not currently on the master branch, check out master.

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

• If you want to restore changes stashed changes above, run

   $ git stash apply

• Code your change.
• Run any unit tests.
• Stage the files with "git add" and commit. Running "git status" shows you what files you've changed.

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

• Include the bug ID and a descriptive message in the commit.
• 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

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>