|
The iOS app development team is using Gerrit for code review. The following instructions assume you‘re using a recent version of Mac OS X.
Contents
[hide]
New to Git?
If you are new to Git I suggest you take the time to read the first three chapters of the official git book, this will simplify your life later.
If you don‘t read it now, at least come back to it after you are thoroughly frustrated with Git.
Here is a link to an introduction to the Gerrit Code Review tool.
We have come up with a Common Workflow that will help you be more productive and avoid common pitfalls. Please read and follow it.
Here is an
Activate your code review account
- Sign in to the code review website with your LDS Account.
- Ask an admin for access to the project.
Get the code onto your machine
- If you haven‘t already done so, set up password caching.
- Clone the project you‘re working on (be sure to replace "PROJECT" in this and all further instructions with the name of the actual project you‘re working on). Use your LDS Account password for this step (password caching makes it so you only have to use this password once):
git clone https://tech.lds.org/mobile/codereview/p/PROJECT
- Clone any libraries the project uses. Not all projects have them, but it doesn‘t hurt. Use your LDS account credentials for this step.
cd PROJECT
git submodule update --init --recursive
- Set up a commit hook. This hook will automatically add the appropriate change ID to every commit. The change ID will help the code review tool to group multiple commits as a single change. This aids the back and forth process of polishing the code until it is ready to be committed to the master repository. If you skip this step, you‘ll be unable to push, but it won‘t be obvious why.
curl https://tech.lds.org/mobile/codereview/tools/hooks/commit-msg > .git/hooks/commit-msg
chmod u+x .git/hooks/commit-msg
- Configure the git push command to request a code review. If you skip this step, you‘ll be unable to push.
git config remote.origin.push HEAD:refs/for/master
- Set up your name and email. The email will need to match what you have registered in LDS Tech. If you skip this step, you‘ll be unable to push any commits you make.
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
If you have already committed with the wrong information, you can:
git commit --amend --author="Author Name <[email protected]>"
If there are multiple commits with the wrong information, follow these more in-depth steps.
Make changes and request a code review
- Make sure you‘re on branch master:
git checkout master
- Make sure you‘re working with the latest code:
git pull origin master
- Create a new branch for your changes:
git checkout -b <branchname>
- Make your changes.
- Verify your changes:
git diff
git status
- Commit your changes locally:
git commit -a
You‘ll be asked to enter a commit message. Use the following format:
(PROJECT-245) Short summary of change (~50 chars max, issue ID in parentheses if applicable)
A more elaborate summary of the committed changes and suggested tests.
May have bullet points or paragraphs. Break at 72 chars. This is shown
when users view the full commit.
- Request a code review:
git push
You will be asked for your username (LDS Account username) and password (LDS Account password).
We recommend you use git credential caching, here‘s how you set up git to cache your username and password.
Update your code
The code review process exists to maintain a high level of code quality, to make sure that more than one set of eyes has seen every line of code, and to provide an opportunity for both the contributor and the reviewer to learn. It is rare that any code review request does not require some change, even if minor. When that happens:
- Checkout the submitted code review.
- Find the "Download" option by going to your submitted code in Gerrit (the code review tool) and scrolling down to the latest patch set.
- Make sure the "Checkout" and "HTTP" options above the command are selected.
- Copy the git fetch https... line next to "Download" and execute it in your terminal.
- Make your changes. Note: Make sure you don‘t rebase your change, as that makes it impossible to view only the differences in gerrit.
- Verify your changes:
git diff
git status
- Commit and request another code review. Do not use the -m argument for commit as this will overwrite the change ID. Update the commit description in the editor.
git commit -a --amend
git push
When Gerrit Fails to Submit Due to Merge Errors
If you get the error "Your change could not be merged due to a path conflict" when submitting a change set in the code review tool, you need to resolve the conflict by following these steps:
- Make sure your master branch is up to date: git pull origin master
- Checkout the conflicting change set. You can copy/paste the correct command from the ‘Download‘ section in the code review tool. It will look something like: git fetch https://[email protected]/mobile/codereview/PROJECT refs/changes/08/8/2 && git checkout FETCH_HEAD
- Rebase against master (this should give you a conflict warning. this is OK!): git rebase master
- If you haven‘t already done so, set up your mergetool (see related section in Tips and Tricks).
- Run git mergetool to resolve the conflicts. Save and close each file.
- Tell the rebase to continue now that the issue is resolved: git rebase --continue
- Push the resolved conflict for review: git push
- Re-review the change set in the code review tool, and then submit the changes to be merged to master.
When The Code Won‘t Run
Many build/run problems can be solved by doing one or all of the following:
- In the git repository, run git submodule update --init --recursive
- In the iOS Simulator click on "iOS Simulator" -> "Reset Content and Settings..."
- In Xcode, type command-option-shift-k (or alternately, hold down option while selecting "Product" -> "Clean")
Git Tips and Tricks
Squash multiple commits into one
- Supply the parent of the last commit you want to edit (for example 3):
git rebase -i HEAD~3
(that‘s dash i and tilde 3)
- You should see a list of commits in your text editor you‘ll want to change the commits you‘d like to squash from ‘pick‘ to ‘s;:
pick f7f3f6d changed my name a bit
s 310154e updated README formatting and added blame
s a5f4a0d added cat-file
- Save and exit your text editor
:wq
- All your commit messages will then be shown. Combine them into one message, making sure you only have one change-id.
- Magic happens! And your commits are squashed.
- If the short version above isn‘t sufficient for your purposes, you can visit the link for more details. Learn about interactive rebasing for more details (specifically the section about squashing commits).
Get rid of uncommitted changes
WARNING: This will lose all of your uncommitted or unstashed changes.
To get rid of uncommitted changes, perform git reset --hard HEAD.
If you want to get rid of them temporarily, do git stash.
Reset your git repository to match the public repository
WARNING: These steps will get rid of all of your unpublished changes on the branch you perform this on, even if they have been committed to that branch. (If they have been committed to a separate branch or stashed (Google "git stash"), they should be fine, but be careful.)
If you get into a state that you don‘t like and you want to blow away your changes and get to a clean state, follow these steps on your preferred branch (most likely branch master):
- Get rid of unwanted commits by performing git reset --hard HEAD~<number>. Replace <number> with a value slightly more than the number of unwanted commits you want to get rid of. For instance, if you see from your git log that you have 3 commits you want to blow away, then git reset --hard HEAD~5 would do the trick. (Note the tilde)
- Update to public repository state by performing git pull origin master.
If this doesn‘t work, use one of the destructive blunt instruments described on Stack Overflow.
Set up difftool and mergetool
git config --global diff.tool opendiff
git config --global merge.tool opendiff
By default, mergetool keeps ".orig" backup files. To disable this, run git config --global mergetool.keepBackup false.
This page was last modified on 4 December 2013, at 15:15. This page has been accessed 6,903 times.
|
