Difference between revisions of "Lyo/GitTips"

Revision as of 10:56, 5 August 2014

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 add in a copyright header or license file or to merge them with other changes). Having a branch that is always in sync with origin/master makes it very 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 other changes.

It's probably a good practice anyway.

Other Advice

• Add your changed files and commit (or at least use "git stash") before running "git pull" or any destructive command like "git reset --hard". 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".
• Use "git pull --rebase" rather than "git pull" if you have any pending commits. Gerrit will reject merge commits since they don't meet the Eclipse requirements (for one, they're not signed off). 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 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 pending changes, stash them.

   $ git stash

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

   $ git checkout master

• Then

   $ git pull
   $ git checkout -b <your_bug_id>

This updates your local Git repository with the latest from Lyo and creates a branch for your work.

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

   $ git stash apply

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

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

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