UsingGitForDevelopment

A wiki page which will serve as an introduction to commonly used git commands and workflows.

Cloning a repository

Get a copy of existing git repository:

# Create a clone of help.github.com repository in your current working directory 
$ git clone https://github.com/github/help.github.com.git 

Get or Set repository options

The git configuration file can be placed in following locations:

• <system-install>/etc
• $GIT_DIR/.git/config
• $HOME/.gitconfig

You can configure git with many customizations like - commit message editor, commit message template, diff tool, color codes etc. You will need to set at least user name and email address which will be used as author and/or committer name in a commit.

$ # Adding config parameters to a specific repository using git-config command 
$ cd /path/to/repo
$ git config user.name "FirstName LastName"
$ git config user.email "blazerid@uab.edu"

# Adding config parameters to a specific repository by directly editing .git/config file 
$ vi /path/to/repo/.git/config 

# Adding config parameters globally using git-config command 
$ git config --global user.name "FirstName LastName"
$ git config --global user.email "blazerid@uab.edu"

# Adding config parameters globally by directly editing ~/.gitconfig file 
$ vi ~/.gitconfig

Initialize a repository for existing project directory

Use git init command to initialize a git repository in existing project directory. Note that git does not commit empty directories by default so you will need at least one file in the project directory. You can create a empty hidden file in empty directories that you wish to be included in a commit.

# Initialize a git repository in a project's directory 
$ cd /path/to/project-dir
$ git init 

Note: You can include empty directories in a commit, but it's usually discouraged unless you want interoperability with other non-git version control system.

Adding remote repositories

You can add multiple remote repositories in your repository so that you can track their branches. This is common practice in collaborative environment where developers track each others repositories.

 $ cd /path/to/repo 

 # Add remote repository 
 $ git remote add <remote-name> <remote-repo-url>

 # Fetch git objects from another repository 
 $ git fetch <remote-name>

Note: When a local repository is initiated using 'git clone' command then a remote called 'origin' is added by default.

Branches

There are probably numerous blogs and tutorials that describe git's branch concept. Following is one of the best description of it from gitglossary's man page ('man gitglossary'). A "branch" is an active line of development. The most recent commit on a branch is referred to as the tip of that branch. The tip of the branch is referenced by a branch head, which moves forward as additional development is done on the branch. A single git repository can track an arbitrary number of branches, but your working tree is associated with just one of them (the "current" or "checked out" branch), and HEAD points to that branch.

Listing branches

$ # List local branches 
$ git branch 

$ # List all branches - local and remote 
$ git branch -a

$ # Create a new branch starting from current HEAD
$ git branch ticket77
$ # Checkout (switch to) ticket77 branch - changes 

$ # Above two commands - creating a branch and switching to it can be done in a single command as
$ git checkout -b ticket77

Fetch and Merge

The git-fetch command downloads git objects and refs from remote repository and stores them in remote refs (remotes/<remote-name>/<branch-name>). It does not modify current working directory. The changes in remote refs can be used to compare with your local branches and merge operations.

$ # Fetch refs from remote repository 
$ git fetch <remote-name>

$ # diff between remote ref and your local branch - inspect diff before performing the merge
$ git diff remotes/<remote-name>/<branch-name>..<local-branch-name>

$ # Merge changes in remote ref in your current local branch 
$ git merge remotes/<remote-name>/<branch-name> 

The fetch and merge operations can be specified using a single command - git pull. However, it is good idea to perform fetch, diff and merge operations separately as it allows you to inspect changes before they are merged in your local branch. See http://longair.net/blog/2009/04/16/git-fetch-and-merge/ for good explanation of about branching, fetching and merging.

Workflows

Integration manager workflow

Create a separate branch for your work

• Pull latest code from the 'blessed' repository in the develop branch.
• Create a ticket for the bugfix or add-on feature.

$ git checkout develop
$ git pull

• Create a bugfix/add-on branch with ticket number or issue name/description.

# Make sure you are on develop branch 
$ git checkout develop

# Optional: Stop your application if working on live personal development copy

# Create bugfix-branch 
$ git checkout -b <describe-bugfix-branch>

# ** Add/Edit/Delete files

# git add-commit 
$ git add <filename>
$ git commit 

# Optional: Start your application  and test your code 
# ** Fix code again if necessary and then commit your changes. 

# ** Once you are satisfied with changes and ready for the merge 
# Go back to develop branch once you bugfix is complete 
$ git checkout develop 

# Merge <describe-bugfix-branch> with develop branch
$ git merge <describe-bugfix-branch>

Sharing your changes

Send pull-request to repository integrator/admin

• Send pull request to repository integrator/admin
• Modify repository directory permissions so that your peers can access your repository.
• Share your git repository path information with your repository integrator/admin so that he/she can pull changes from the repository.

Format patch and email

• Create git formatted patches for your changes

# Following command will create a patch file(s) for commits between commit1 and commit2 (displayed after doing a git merge)
$ git format-patch <commit1>..<commit2>

• Email this patch file to developer mailing list and/or integration manager

# Email command example 
$ /usr/sbin/sendmail mailing-list@example.com < 0001-*.patch 

• Update ticket information with your patch file(s).

Applying Patches

The Git has two command for applying patches - 'git apply' and 'git am'. The 'git apply' is more generic command which can be used to apply regular GNU diff-patch formatted patch files. The 'git am' is more git specific to Git/mbox formatted patch file which includes author and committer information. Also, the 'git apply' command doesn't commit changes by default however 'git am' command will try to commit applied patches immediately by default. 1. Using 'git apply' command:

# Verify patch file 
$ git apply --check /path/to/file.patch 

# Apply patch 
$ git apply /path/to/file.patch 

2. Using 'git am' command:

# Verify patch file 
$ git apply --check /path/to/file.patch 

# Apply patch in mbox/Git format 
$ git am /path/to/file.patch 

Pulling changes from other developers

• Fetch and merge - one way to grab changes from remote official repository or other developer

$ # Following command will fetch master branch of remote-name
$ git fetch <remote-name>

$ # Merge it with your curent branch 
$ git merge <remote-name>/master

Pulling changes from other developers and Pushing them to the blessed repository

• Add remote for the other developer's git repository.

$ # Add remote for a developer's repository  (-f option performs fetch after remote is added)
$ git remote add -f <blazerid-developer> <repository-URL>  

$ # Verifying changes/diff against developer's branch 
$ git log -p develop..remotes/<blazerid-developer>/<developer's branch>

$ # Create a local tracking branch for developer's repo as follows
$ git checkout -b blazerid-develop <blazerid-developer>/develop 

$ # Merge developer's branch changes with your 'blessed' develop branch 
$ git checkout develop
$ # Merge from tracking branch 
$ git merge <blazerid-developer>-develop 
$ # Alternatively you can merge directly using local ref to remote branch 
$ git merge remotes/<blazerid-developer>/<developer's branch>


# Push changes to the blessed repository 
$ git checkout develop 
$ git push

Links for various types of workflows

• http://whygitisbetterthanx.com/#any-workflow
• https://code.djangoproject.com/wiki/CollaborateOnGithub - Explains integration manager workflow with git commands

Links

• ProGit book - Covers almost everything we need to know about Git in simple language
• GitHub learning guide - Quick reference to Git with links to Git man pages and ProGit book
• Git branching model
• Linus's thread on KDE mailing list - 'clarification on git, central repositories and commit access lists'
• Workflows in another DVCS bazaar, most of which can be implemented in Git