Version Control using Git¶

Before you start¶

The following resources contain useful information on version control systems:

A Visual Guide to Version Control:

a simple explanation of version control with Subversion examples.
A successful Git branching model: a clear and structured workflow.

Git CheatSheet¶

Source

Overview¶

When you first setup Git, set up your user name and email address so your first commits will record them properly:

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

Basic Git Workflow Example¶

Initialise a new git repository, then stage all the files in the directory and finally commit the initial snapshot:

$ git init
$ git add .
$ git commit -m 'initial commit'

Create a new branch named feature_A, check it out so it is the active branch, then edit and stage some files and finally commit the new snapshot:

$ git branch feature_A
$ git checkout feature_A
$ (edit files)
$ git add (files)
$ git commit -m 'add feature A'

Switch back to the master branch, reverting the feature_A changes you just made, then edit some files and commit your new changes directly in the master branch context.:

$ git checkout master
$ (edit files)
$ git commit -a -m 'change files'

Merge the feature_A changes into the master branch context, combining all your work. Finally delete the feature_A branch.:

$ git merge feature_A
$ git branch -d feature_A

Setup & Init¶

Git configuration, and repository initialisation & cloning.

command description

git config [key] [value] set a config value in this repository

git config global [key] [value] set a config value globally for this user

git init initialise an existing directory as a Git repository

git clone [url] clone a Git repository from a URL

git help [command] get help on any Git command

Stage & Snapshot¶

Working with snapshots and the Git staging area.

command description

git status show the status of what is staged for your next commit and what is modified in your working directory

git add [file] add a file as it looks now to your next commit (stage)

git reset [file] reset the staging area for a file so the change is not in your next commit (unstage)

git diff diff of what is changed but not staged

git diff --staged diff of what is staged but not yet committed

git commit commit your staged content as a new commit snapshot

git rm [file] remove a file from your working directory and unstage

Branch & Merge¶

Working with Git branches and with the stash.

command description

git branch list your branches. a * will appear next to the currently active branch

git branch [branch-name] create a new branch at the current commit

git checkout [branch] switch to another branch and check it out into your working directory

git checkout -b [branch] create a branch and immediately switch to it

git merge [branch] merge another branch into your currently active one and record the merge as a commit

git log show commit logs

git stash stash away the currently uncommitted modifications in your working directory temporarily

git stash apply re-apply the last stashed changes

Share & Update¶

Fetching, merging and working with updates from another repository.

command description

git remote add [alias] [url] add a git URL as an alias

git fetch [alias] fetch down all the branches from that Git remote

git merge [alias]/[branch] merge a branch on the server into your currently active branch to bring it up to date

git push [alias] [branch] push the work on your branch to update that branch on the remote git repository

git pull fetch from the URL tracked by the current branch and immediately try to merge in the tracked branch

Inspect & Compare¶

Examining logs, diffs and object information.

command description

git log show the commit history for the currently active branch

git log branchB..branchA show the commits on branchA that are not on branchB

git log --follow [file] show the commits that changed file, even across renames

git diff branchB...branchA show the diff of what is in branchA that is not in branchB

git show [SHA] show any object in Git in human-readable format

Contributing on GitHub¶

To contribute to a project that is hosted on GitHub (or another repository hosting site, such as BitBucket) you can fork the project online, then clone your fork locally, make a change, push back to GitHub and then send a pull request, which will email the maintainer.:

fork project on github
$ git clone https://github.com/my-user/project
$ cd project
$ (edit files)
$ git add (files)
$ git commit -m 'Explain what I changed'
$ git push origin master
go to github and click ‘pull request’ button

Visual Git Cheatsheet¶

Source

A list of Git commands, categorized on what they affect.

The interactive online version provides a description for each of the commands.

Stash¶

A place to hide modifications made to the workspace, while working on something else. (The stash area is not required in a “normal” workflow.)

Workspace¶

The local working area.

Staging area¶

The “index”– or “staging area” – holds a snapshot of the content of the working area, and it is this snapshot that is taken as the contents of the next commit.

Local repository¶

A local area under version control. Typical branches: master, dev (for local development), feature_x, bugfix_y

Upstream repository¶

Typically a remote area under version control. Default name is ‘origin’. Typical branches here: master, shared_feature_x, release_y.

How to…¶

This section include miscellaneous Git commands to perform different operations.

Set up a merge tool to resolve conflicts¶

Configure kdiff3 as the merge tool (in Windows):

$ git config --global mergetool.kdiff3.path 'C:\Program Files (x86)\KDiff3\kdiff3.exe'
$ git config --global merge.tool kdiff3

Invoke kdiff3:

$  git mergetool <file>

Force an update from the upstream repository¶

This operation will discard all changes in the local repository:

$ git reset --hard HEAD
$ git pull

Add untracked files to the set of files under version control¶

A pattern can be used. For example, this will add any new or untracked *.rst file:

$ git add $(git ls-files --other *.rst)

Remove multiple files from the set of files under version control¶

This will remove multiple files that have already been deleted from disk:

$ git rm $(git ls-files --deleted)

Alternatively, edit the .git\config file, and add the following lines:

[alias]
   rma = !git ls-files --deleted -z | xargs -0 git rm

Then run the command using the alias:

$git rma

Disable quoted file names¶

Special character and spaces in file names can be problematic. To disable quotes file names (Windows Unicode Support), use:

$  git config [--global] core.quotepath off