Installation

If you have never used Git before, you need to do some setup first. Run the following commands so that Git knows your name and email.

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Setup line endings preferences :

• For Unix/Mac users :

  git config --global core.autocrlf input git config --global core.safecrlf true

• For Windows users :

  git config --global core.autocrlf true git config --global core.safecrlf true

You can also define the following extras :

git config --global color.ui "auto"
git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"
git config --global alias.st "status"
git config --global alias.ci "commit -v"
git config --global alias.co "checkout"
git config --global alias.br "branch"

# By default use rebase during "git pull"
git config --global branch.autosetuprebase always
git config --global branch.master.rebase true  

Branches

The model used for Sonar is inspired by the nvie.com model. It defines the following branches :

• master is the development branch of next release, at anytime. For example it's currently v2.8-SNAPSHOT, while v2.7 is still under testing. It can be considered as the "integration branch" when developers use their own Git repository.
• releases is the production branch. Commits are pushed in this branch only for releases. It contains also the release tags. It's similar of the master branch in the nvie model.
• release-xxx (for example release-2.7) prepares the next release. It's used during pre-releasing testing periods, usually during first RC and final release. Release branches are merged back into "releases" and "master" when releasing, so they can be deleted.

Commit messages

Commits must relate to a JIRA issue. Convention for messages inspired by http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html :

• The first line must be short (50 chars or less) and auto-descriptive in a format "<JIRA KEY> <DESCRIPTION>", for example "SONAR-1937 Code review"
• Write your commit message in the present tense: "Fix bug" and not "Fixed bug".
• The second line is blank.
• Next lines optionally define a short summary of changes (wrap them to about 72 chars or so).

Example :

SONAR-2204,SONAR-2259 Fix URL encoding
    
* For correct URL encoding we must encode parameters on lower level -
  in Query itself, but not in concrete implementation of Connector,
  because in Query we can distinguish concrete parts of URL.

* Moreover in this case any additional encoding routines in Connector
  are useless, so were removed.

Workflow

It's recommended to use your own feature branches (sometimes called "topic branches") when fixing JIRA issues. It allows to on work on multiple isolated features.

The first time the Sonar repository must be forked into your own GitHub workspace. Simply log in GitHub, browse to Sonar reference repository and click on the "Fork" button. Then download sources on your box :

git clone git@github.com:<your github id>/sonar.git
git remote add upstream git@github.com:SonarSource/sonar.git -f

Create the branch when starting to work on a JIRA issue

The branch name is usually the JIRA key and a short auto-descriptive name, for example "SONAR-237_review" :

git checkout -b <branch name> master

Code and test (or the inverse) and regularly update with changes committed into SonarSource codebase :

git fetch upstream
git merge upstream/master

Switch between feature branches 

To switch between feature branches, check that all your local files are committed into local repository (git status). If you don't want to commit them, you can move them when switching :

git stash
git checkout <branch name>
git stash apply

If you don't have any pending changes, then simply execute "git checkout <branch name>"

Push commits to personal GitHub repository 

For example to backup your local branch or to benefit from continuous integration :

git push origin <branch name>

Push commits to SonarSource repository

1. Get your master up to date with SonarSource repo

   git remote update git checkout master git merge upstream/master

2. Rebase your branch so that we have a linear history

   git checkout <branch name> git rebase -i master

3. Merge your branch into your master

   git checkout master git merge <branch name>

4. And finally push your linear-history master to SonarSource repo and delete the feature branch

   git push upstream master git branch -d <branch name> git push origin :<branch name>

Git hints

Split commit

Edit commit during interactive rebasing (see http://book.git-scm.com/4_interactive_rebasing.html)

Split changes in one file

See http://stackoverflow.com/questions/1440050/how-to-split-last-commit-into-two-in-git :

git add -p

Undoing rebase

See http://stackoverflow.com/questions/134882/undoing-a-git-rebase

Delete a remote tag

See http://nathanhoad.net/how-to-delete-a-remote-git-tag :

git push origin :refs/tags/name

Pruning stale remote-tracking branches

See http://kparal.wordpress.com/2011/04/15/git-tip-of-the-day-pruning-stale-remote-tracking-branches/ :

git remote prune origin --dry-run

Remove untracked files from the working tree

git clean

Show staged changes

git diff --staged

Finding issues, reasons for changes ( Bisect )

git bisect start
git bisect good <tag>
git bisect bad master
// check
git bisect [bad|good]
// check
git bisect [bad|good]
...
git bisect reset