GIT Playbook

git

If you are unfamiliar with Git you may want to take a few moments to familiarize yourself with it. A simple guide can be found at http://rogerdudler.github.io/git-guide/.

Git-flow

Git-flow enables you to work on your own feature branch in isolation before committing to the main project branches, i.e. develop and master. Features are driven from Pivotal Tracker as assigned tasks which are numbered with a story ID, e.g. 007. In this way git flow helps manage the Git history to reflect the progress against specific Pivotal Tracker issues.

References: http://danielkummer.github.io/git-flow-cheatsheet/ http://nvie.com/posts/a-successful-git-branching-model/ https://github.com/nvie/gitflow

Install Git-Flow

OS X
```
$ brew install git-flow
```
Linux
```
$ apt-get install git-flow
```
Windows via Cygwin. Note: wget and util-linux are required to install git-flow. For more detailed instructions please see https://github.com/nvie/gitflow/wiki/Windows
```
$ wget -q -O - --no-check-certificate https://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | bash
```

References: http://danielkummer.github.io/git-flow-cheatsheet/

Git-Flow initialization and settings

From the local repository directory (e.g. /universal-imports),
```
$ git flow init
```

Use the following settings when prompted for the git-flow prefixes,

master = master
develop = develop
feature = feature/
release = release/
hotfix = hotfix/
support = support/
versiontag = -v

Git-Flow workflow

Before starting a feature branch ensure that you have latest code from the develop branch,
```
$ git checkout develop
$ git pull
```
Start a feature branch by typing, git flow feature start , e.g. if your TRACKER story ID is 007, you would execute,
```
$ git flow feature start 007
```
Now, start committing on your feature.

- You can propose changes (add it to the Index) using,

        $ git add <filename>

        or

        $ git add *

- To actually commit these changes to your local repository, use, (be sure to start the message with #<TRACKER ID #>

        $ git commit -m "#007 Commit message"

Please use the following guidelines when writing commit messages. For example,

PSE-007: Summarize clearly in one line what the commit is about

Describe the problem the commit solves or the use case for a new feature. Justify why you chose the particular solution.
Optionally, publish a feature branch to the remote server so it can be used by other users,
```
$ git flow feature publish 007
```

When done with the feature, use,

$ git flow feature finish 007

$ git push

Then delete the remote feature branch (if it was created),
```
$ git push origin :feature/007
```
Then delete the local branch (if it still exists - git flow will usually delete it for you),
```
$ git branch -d feature/007
```

Feel free to use any tool that supports git flow on your operating systems. ex, SourceTree, Tower, etc

Resolve Un-staged Change Warnings

Resolve un-staged change warnings using,

    $ git stash
    $ git push (i.e. push your staged commits)

Switch to another branch to work on another feature, etc.
Afterward to bring back your stashed changes,

    $ git stash pop

Avoid Fast-forward Merges

Suppose you were working on "feature/007" and there have been changes in the meantime to the "develop" branch.

Approach 1 - Pre-sync the target branch

    $ git checkout develop
    $ git pull
    $ git checkout feature/007
    $ git flow feature finish 007

Approach 2 - Merge the branches with the "no fast-forward" flag

    $ git flow feature start 007
    $ git flow feature publish 007

Instead of using "git flow feature finish 007" (because it causes a fast forward at this point)

    $ git checkout develop
    $ git pull
    $ git merge --no-ff feature/007
    $ git push origin develop

Git Tips and Tricks

Configure your username and password

Checkout a specific tag

Useful if you want to use a specific tagged version for a deployment,

List the available tags,

$ git tag -l

...
v3.10.0
v3.11.0
v3.14.0
v3.15.0
v3.16.0
v3.17.0

Checkout a specific tag,

$ git checkout tags/v3.16.0

M   /universal-imports/modules
Note: checking out 'tags/v3.16.0'.
...

Undo or rollback a Git commit

Assuming you have not yet pushed the commits to the remote repository.

To rollback to the previous commit,

    $ git reset --soft HEAD^

To rollback the last three commits,

    $ git reset --hard HEAD~3

Resetting a local branch to exactly match a remote branch

Setting your local branch to exactly match the remote branch using,

    $ git fetch origin
    $ git reset --hard origin/develop

If you want to save your current branch's state before doing this (just in case),

    $ git commit -a -m "Saving my work, just in case"
    & git branch my-saved-work

Rollback a release in the Master branch to a previous tag

WARNING: This alters history. Do not try this on the DEVELOP branch.

Ensure that you are on the MASTER branch,
```
$ git checkout master
```

Find the commit number of the previous tag (e.g. dc7e7b5 3.15.0.RELEASE),

$ git log --oneline

ecdd645 Merge branch 'release-3.16.0'
c023314 3.16.0.RELEASE
72a9524 Added some changes
f2e68e5 3.16.0.SNAPSHOT
3414a30 Merge branch 'release-3.15.0' into develop
5078f25 Merge branch 'release-3.15.0'
dc7e7b5 3.15.0.RELEASE
9e5c0d2 Updated some other changes
...

Make the previous tag commit the current one (e.g. 3.15.0.RELEASE),
```
$ git reset --hard dc7e7b5
```
Remove the other release's now uncommitted changes locally,
```
$ git reset HEAD^
```
Force push the new HEAD commit to the remote repository,
```
$ git push origin +HEAD
```
If you want to still have it in your local repository and only remove it from the remote, instead use,
```
$ git push origin +HEAD^:master
```

Merging

Open the Git merge tool,

$ git mergetool

        ...Fix merge issues...

Execute the merge,

$ git merge

        ...will merge resolved conflicts and reset the merge head appropriately...

Undo a failed merge

If you see something like the following Git error/warning message,

"You have not concluded your merge (MERGE_HEAD exists). Please, commit your changes before you can merge."

    $ git merge --abort

Open a specific commit on Github

Use the following URL format,

    https://github.com/pivotalservices/universal-imports/commit/<commit id>

e.g.
    https://github.com/pivotalservices/universal-imports/commit/a5a49eea2b45d213ece491c7fa3f350cd48c972e

Open a specific line of code in a file on Github

To reference a specific line of code in a file,

    https://github.com/pivotalservices/universal-imports/<name>/<branch>/<path to file>#L<line number>