Standard Feature-Branch Workflow

This is our default workflow. The central concept of this workflow is that all development occurs in isolated "topic" branches. The "master" branch is kept clean allowing easy branching to address separate features (topics) and bug fixes. Another key feature of this flow is the use of rebases instead of merges to prevent local merge commits.

1. Update “master” branch.

   > git pull upstream master
   

2. Create a new feature-branch “feature1”

   > git branch feature1 master
   > git checkout feature1
   

3. Do some work on your feature, add and commit it

   > git add File1, File2
   > git commit -m "Working my feature"
   

4. OPTIONAL: When you’re ready to push up, squash all of your commits together first

   > git reset --soft master
   > git commit -m "unified feature commit"
   

5. When you’re ready to push your work up to get pulled in, make sure you’re up-to-date first

   > git checkout master
   > git pull upstream master
   

6. “master” is now up-to-date. Switch back to your branch and rebase your work on top of the new “master”

   > git checkout feature1
   > git rebase master
   

7. Push up to github

   > git push origin feature1
   

8. Issue pull request
9. When processed, update “master” to pull down your official change, delete “feature1”

   > git checkout master
   > git pull upstream
   > git branch -D feature1
   

Staying up-to-date

Refreshing your feature branch can be done at any time by calling commands 4-6

Handling merge issues

When you rebase your feature on-top of new stuff in your “master”, you may have to handle file merges. Please note that step 4, squashing all of your work into a single commit is encouraged, otherwise you may end-up processing merges on the same file for every commit you’re rebasing.

How do you know you’re conflicted? Look for the big “CONFLICT” in the results when you issue the rebase

> CONFLICT (content): Merge conflict in index.html

You can either use your IDE to handle the conflicts or if you’ve setup the git merge-tool (http://gitguru.com/2009/02/22/integrating-git-with-a-visual-merge-tool/), issue the following from the command-line

git mergetool CONFLICTED_FILE

Exiting the mergetool should mark the file as resolved. Depending on your mergetool, you may be prompted to tell Git if the merge was successful.

After all conflicted files have been resolved, tell rebase to continue

git rebase --continue

If you’ve made a mistake and just want to cancel out of the rebase, issue the following command:

git rebase --abort

Advanced Git Topics

Diff between branches

Git offers a couple of great commands for comparing branches. To get a comparison of branches in a "status" type format:

git diff --name-status branch1..branch2

Will give you output something like:

M       config/boot.rb
M       config/database.yml
M       config/deploy.rb

Now that you have a list of files, you may wish to get a diff of a specific file:

git difftool branch1:FILE.txt branch2:FILE.txt

This will open the configured mergetool. Note the mergetool and difftools can be setup to use different programs. If mergetool isn't configured, git will use difftoll as a fallback.

Cherry-Picking

When developing a fix or feature across multiple branches, you often cannot just merge one branch onto another. Think of a fix that needs to be applied to versions 1.0, 2.0 and 2.2. Merging would bring in more than your one fix. In this scenario cherry-picking is the answer. Basically it’s capturing a patch-file of one commit and applying it to another branch to create a new commit.

Steps to Cherry-pick
Identify the SHA(s) code for the commit you want to pick-over to another branch. git log or your IDE’s history will work fine.

git checkout TARGET_BRANCH
git cherry-pick 724d9acd 3d4fcf9e

Just like merging or rebasing, you may have to handle a merge. If so, run git mergetool and then git cherry-pick --continue

When cherry-picking, it can be useful to ignore newline differences. This can be done with:

git cherry-pick --strategy=recursive -X ignore-space-at-eol 3d4fcf9e

Other merge strategies supported by git-merge should work as well

Resetting

The reset command does a lot of diferent things. The most basic form is as follows. It will replace the file in your working directory with the last committed version in the repository HEAD.

git reset FILE1

An optional second parameter is the commit from which to pull the file. Since branches are just named commits, you can use a branch name as well

git reset FILE1 COMMIT_SHA_OR_NAME

The second use of reset actually moves the branch to point to another commit. This is often a commit further back in the branch, but can be any commit from any branch, remote or even an orphaned commit in the reflog. You’ll notice we don’t specify a file, that’s because we’re resetting the branch!

git reset --STYLE COMMIT_SHA_OR_NAME

The style of reset you apply makes a huge difference in the result.
--soft
Does not touch the index file nor the working tree at all (but resets the head to <commit>)
(This is great for “squashing” several commits together as they’re changes are on disk and they’re in the staging area (index) ready to be committed.)

--mixed
Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action.

(This is useful when you’re accidentally added too much to the staging area and just want to reset it)

--hard
Resets the index and working tree. Any changes to tracked files in the working tree since <commit> are discarded. The Nuclear option. This is going to reset everything to be that commit. Great for when you just want to basically recreate a branch. The following will reset a branch to be the one on the Pentaho repository

git fetch upstream
git reset --hard upstream/master

--merge and --keep
These are inbetween a --hard and --soft. I don’t use them much, but you can read about them here (https://www.kernel.org/pub/software/scm/git/docs/git-reset.html)

Stashing

Stash is pretty intuitive. It puts your changes somewhere, making it look like you've done nothing (reset to HEAD). Later you to pull them back from the stash. What you may not know is that you can name your stashes with the "save" sub-command (note: save is the default sub-command)

git stash save "My Message Here"

Stash is actually a LIFO queue. You can stash multiple times and "pop" them back off. Stash a couple times and issue the following to see the stash queue

git stash list

This should result in a list like the following:

stash@{0}: On master: My Message Here
stash@{1}: WIP on master: 01fbfb5 Object Factory and PentahoSystem overhaul.

You can apply and remove any stash in any order by passing it's ID to pop or apply:

git stash pop stash@{1}

Most people just the pop command to apply a stash and remove it, but you can apply a stash's changes to a branch and without removing it as pop does. Use this if you want to apply a stash to multiple branches (cheap cherry-pick / reset)

Reflog

Reflog is the command to see all changes to branch pointers. This will include commits, resets, etc.

The Reflog can really save you if you accidently reset or rebase a branch (losing commits), or even delete a branch. Just locate the commit you know was the last in the deleted branch and issue the command to create another branch from it

git branch myRestoredBranch 724d9acd

Exercises

Rebase Merge conflicts

Create a repo:

mkdir pristine && cd pristine
git init

Create a new file “test.txt” with the following content:
“the brown dog jumped over the lazy fox”

git add test.txt
git commit -m "initial commit"

Do some work on a feature branch

git checkout -b feature

edit the test.txt and make the content:
“the purple dog jumped over the lazy fox”

git add test.txt
git commit -m "brown is out of style"

Simulate someone else doing work but making a conflicting commit on master

git checkout master

edit the test.txt to make the content:
“the brown dog jumped over the lazy turtle”

git add test.txt
git commit -m "brown is out of style"

Now back to your feature, rebase on top of master and you’ll have a Merge!

git checkout feature
git rebase master

Handle the merge

git mergetool test.txt
git rebase --continue

Related Links

Developing with Git source controlled projects