1. Git

A version control system allows you to track the history of a collection of files and includes the functionality to revert the collection of files to another version. Each version captures a snapshot of the files at a certain point in time. The collection of files is usually source code for a programming language but a typical version control system can put any type of file under version control.

The collection of files and their complete history are stored in a repository.

The process of creating different versions (snapshots) in the repository is depicted in the following graphic. Please note that this picture fits primarily to Git, other version control systems like CVS don't create snapshots but store file deltas.

These snapshots can be used to change your collection of files. You may, for example, revert the collection of files to a state from 2 days ago. Or you may switch between versions for experimental features.

A distributed version control system does not necessarily have a central server which stores the data.

The user can copy an existing repository. This copying process is typically called cloning in a distributed version control system and the resulting repository can be referred to as clone.

Typically there is a central server for keeping a repository but each cloned repository is a full copy of this repository. The decision which of the copies is considered to be the central server repository is pure convention and not tied to the capabilities of the distributed version control system itself.

Every clone contains the full history of the collection of files and a cloned repository has the same functionality as the original repository.

Every repository can exchange versions of the files with other repositories by transporting these changes. This is typically done via a repository running on a server which is, other than the local machine of a developer, always online.

Git is a distributed version control system.

Git originates from the Linux kernel development and is used by many popular Open Source projects, e.g. the Android or the Eclipse developer teams, as well as many commercial organizations.

The core of Git was originally written in the programming language C, but Git has also been re-implemented in other languages, e.g. Java, Ruby and Python.

After cloning or creating a repository the user has a complete copy of the repository. The user performs version control operations against this local repository, e.g. create new versions, revert changes, etc.

You can configure your repository to be a bare or a non-bare repositories.

If you want to delete a Git repository, you can simply delete the folder which contains the repository.

Git allows the user to synchronize the local repository with other (remote) repositories.

Users with sufficient authorization can push changes from their local repository to remote repositories. They can also fetch or pull changes from other repositories to their local Git repository.

Git supports branching which means that you can work on different versions of your collection of files. A branch separates these different versions and allows the user to switch between these version to work on them.

For example, if you want to develop a new feature, you can create a branch and make the changes in this branch without affecting the state of your files in another branch.

Branches in Git are local to the respository. A branch created in a local repository, which was cloned from another repository, does not need to have a counterpart in the remote repository. Local branches can be compared with other local branches and with remote tracking branches. A remote tracking branch proxies the state of a branch in another remote repository.

Git supports that changes from different branches can be combined. This allows the developer, for example, to work independently on a branch called production for bugfixes and another branch calledfeature_123 for implementing a new feature. The developer can use Git commands to combine the changes at a later point in time.

For example, the Linux kernel community used to share code corrections (patches) via mailing lists to combine changes coming from different developers. Git is a system which allows developers to automate such a process.

The user works on a collection of files which may originate from a certain point in time of the repository. The user may also create new files or change and delete existing ones. The current collection of files is called the working tree.

A standard Git repository contains the working tree (single checkout of one version of the project) and the full history of the repository. You can work in this working tree by modifying content and committing the changes to the Git repository.

If you modify your working tree, e.g., by creating a new file or by changing an existing file, you need to perform two steps in Git to persist the changes in the Git repository. You first add selected files to thestaging area and afterwards you commit the changes of the staging area to the Git repository.

You need to mark changes in the working tree to be relevant for Git. This process is called staging or to add changes to the staging area.

You add changes in the working tree to the staging area with the git add command. This command stores a snapshot of the specified files in the staging area.

The git add command allows you to incrementally modify files, stage them, modify and stage them again until you are satisfied with your changes.

After adding the selected files to the staging area, you can commit these files to permanently add them to the Git repository. Committing creates a new persistent snapshot (called commit or commit object) of the staging area in the Git repository. A commit object, like all objects in Git, are immutable.

The staging area keeps track of the snapshots of the files until the staged changes are committed.

For committing the staged changes you use the git commit command.

This process is depicted in the following graphic.

If you commit changes to your Git repository, you create a new commit object in the Git repository. This commit object is addressable via a SHA-1 checksum. This checksum is 40 bytes long and is a secure hash of the content of the files, the content of the directories, the complete history of up to the new commit, the committer and several other factors.

This means that Git is safe, you cannot manipulate a file in the Git repository without Git noticing thatSHA-1 checksum does not fit anymore to the content.

The commit object points to the individual files in this commit via a tree object. The files are stored in the Git repository as blob objects and might be packed by Git for better performance and more compact storage. Blobs are addressed via their SHA-1 hash.

Packing involves storing changes as deltas, compression and storage of many objects in a single pack file. Pack files are accompanied by one or multiple index files which speedup access to individual objects stored in these packs.

A commit object is depicted in the following picture.

The above picture is simplified. Tree objects point to other tree objects and file blobs. Objects which didn't change between commits are reused by multiple commits.

2. Tools

3. Terminology

The following table provides a summary of important Git terminology.

A file in the working tree of a Git repository can have different states. These states are the following:

4. Commit reference

You can use ^ (caret) and ~ (tilde) to reference predecessor commits objects from other references. Predecessor commits are sometimes also called parent commits. You can combine the ^ and ~ operators.

[reference]~1 describes the first predecessor of the commit object accessed via [reference]. [reference]~2 is the first predecessor of the first predecessor of the [reference] commit. [reference]~3 is the first predecessor of the first predecessor of the first predecessor of the [reference] commit, etc.

[reference]~ is an abbreviation for [reference]~1.

For example, you can use the HEAD~1 or HEAD~ reference to access the first [reference] of the commit to which the HEAD pointer currently points.

[reference]^1 also describes the first predecessor of the commit object accessed via [reference].

The difference is that [reference]^2 describes the second predecessor of a commit. A merge commit has two predecessors.

[reference]^ is an abbreviation for [reference]^1.

You can also specify ranges of commits. This is useful for certain Git commands, for example, for seeing the changes between a series of commits.

The double dot operator allows you to select all commits which are reachable from a commit c2 but not from commit c1. The syntax for this is "c1..c2". A commit A is reachable from another commit B if A is a direct or indirect predecessor of B.

For example, you can ask Git to show all commits which happened between HEAD and HEAD~4.

git log HEAD~4..HEAD 

This also works for branches. To list all commits which are in the "master" branch but not in the "testing" branch, use the following command.

git log testing..master 

You can also list all commits which are in the "testing" but not in the "master" branch.

git log master..testing 

The triple dot operator allows you to select all commits which are reachable either from commit c1 or commit c2 but not from both of them.

This is useful to show all commits in two branches which have not yet been combined.

# show all commits which 
# can be reached by master or testing
# but not both

git log master...testing 

5. Installation

On Ubuntu and similar systems you can install the Git command line tool via the following command:

sudo apt-get install git 

On Fedora, Red Hat and similar systems you can install the Git command line tool via the following command:

yum install git 

To install Git on other Linux distributions please check the documentation of your distribution. The following listing contains the commands for the most popular ones.

# Arch Linux

pacman -S git

# Gentoo 

emerge -av git

# SUSE 

zypper install git 

A Windows version of Git can be found on the msysGit project site. The URL to this webpage is listed below. This website also describes the installation process.

Git for Windows

The easiest way to install Git on a Mac is via a graphical installer. This installer can be found under the following URL.

Git for OS X

As this procedure is not an official Apple one. It can change from time to time and there may be other alternatives.

Git is also installed by default with the Apple Developer Tools on Mac OS X.

6. Git Setup

Git allows you to store global settings in the .gitconfig file located in the user home directory. Git stores the committer and author of a change in each commit. This and additional information can be stored in the global settings.

You setup these values with the git config command.

In each Git repository you can also configure the settings for this repository. Global configuration is done if you include the --global flag, otherwise your configuration is specific for the current Git repository.

You can also setup system wide configuration. Git stores theses values is in the /etc/gitconfig file, which contains the configuration for every user and repository on the system. To set this up, ensure you have sufficient rights, i.e. root rights, in your OS and use the --system option.

The following configures Git so that a certain user and email address is used, enable color coding and tell Git to ignore certain files.

Configure your user and email for Git via the following command.

# configure the user which will be used by git
# of course you should use your name

git config --global user.name "Example Surname"

# same for the email address

git config --global user.email "your.email@gmail.com" 

The following command configure Git so that the git push command pushes only the active branch (in case it is connected to a remote branch, i.e.configured as remote tracking branches) to your Git remote repository. As of Git version 2.0 this is the default and therefore it is good practice to configure this behavior.

# set default so that only the current branch is pushed 

git config --global push.default simple
# alternatively configure Git to push all matching branches
# git config --global push.default matching 

You learn about the push command in Section 13.2, “Push changes to another repository”.

If you pull in changes from a remote repository, Git by default creates merge commits if you pull in divergent changes. This may not be desired and you can avoid this via the following setting.

# set default so that you avoid unnecessary commits

git config --global branch.autosetuprebase always 

The following commands enables color highlighting for Git in the console.

git config --global color.ui true

git config --global color.status auto

git config --global color.branch auto 

By default Git uses the system default editor which is taken from the VISUAL or EDITOR environment variables if set. You can configure a different one via the following setting.

# setup vim as default editor for Git (Linux)

git config --global core.editor vim 

Git does not provide a default merge tool for integrating conflicting changes into your working tree. You have to use third party visual merge tools like tortoisemerge, p4merge, kdiff3 etc. A Google search for these tools help you to install them on your platform.

Once you have installed them you can set your selected tool as default merge tool with the following command.

# setup kdiff3 as default merge tool (Linux)

git config --global merge.tool kdiff3

# to install it under Ubuntu use

sudo apt-get install kdiff3 

All possible Git settings are described under the following link: git-config manual page

To query your Git settings of the local repository, execute the following command:

git config --list 

If you want to query the global settings you can use the following command.

git config --global --list 

7. Setup rules for ignoring files and directories

Git can be configured to ignore certain files and directories. This is configured in a .gitignore file. This file can be in any directory and can contain patterns for files.

You can use certain wildcards in this file. * matches several characters. The ? parameter matches one character. More patterns are possible and described under the following URL: gitignore manpage

For example, the following .gitignore file tells Git to ignore the bin and target directories and all files ending with a ~.

# ignore all bin directories
# matches "bin" in any subfolder

bin/

# ignore all target directories

target/

# ignore all files ending with ~

*~ 

You can create the .gitignore file in the root directory of the working tree to make it specific for the Git repository.

You can also setup a global .gitignore file valid for all Git repositories via the core.excludesfilesetting. The setup of this setting is demonstrated in the following code snippet.

# Create a ~/.gitignore in your user directory

cd ~/

touch .gitignore

# Exclude bin and .metadata directories

echo "bin" >> .gitignore

echo ".metadata" >> .gitignore

echo "*~" >> .gitignore

echo "target/" >> .gitignore

# Configure Git to use this file
# as global .gitignore

git config --global core.excludesfile ~/.gitignore 

The local .gitignore file can be committed into the Git repository and therefore is visible to everyone who clones the repository. The global .gitignore file is only locally visible.

You can also create local per-repository rules by editing the .git/info/exclude file in your repository. These rules are not committed with the repository so they are not shared with others.

This allows you to exclude, for example, locally generated files.

8. Tracking empty directories with .gitkeep

Tip

One problem with this approach is that .gitkeep is unlikely to be ignored by version control systems or build agents, resulting in .gitkeep being copied to the output repository. One possible alternative is to create a .gitkeep file in there, which has the same effect but will more likely be ignored by tools that do build processing and filtering of SCM specific resources.

9. Getting started with Git

In this chapter you create a few files, create a local Git repository and commit your files into this repository. The comments (marked with #) before the commands explain the specific actions.

Open a command shell for the operations.

The following commands create an empty directory which you will use as Git repository.

# switch to home

cd ~/

# create a directory and switch into it

mkdir ~/repo01

cd repo01

# create a new directory

mkdir datafiles 

The following explanation is based on a non-bare repository. See Section 3, “Terminology” for the difference between a bare repository and a non-bare repository with a working tree.

Every Git repository is stored in the .git folder of the directory in which the Git repository has been created. This directory contains the complete history of the repository. The .git/config file contains the configuration for the repository.

The following command creates a Git repository in the current directory.

# initialize the Git repository
# for the current directory

git init 

All files inside the repository folder excluding the .git folder are the working tree for a Git repository.

The following commands create some files with some content that will be placed under version control.

# switch to your new repository

cd ~/repo01

# create an empty file in a new directory

touch datafiles/data.txt

# create a few files with content

ls > test01

echo "bar" > test02

echo "foo" > test03 

The git status command shows the working tree status, i.e. which files have changed, which are staged and which are not part of the staging area. It also shows which files have merge conflicts and gives an indication what the user can do with these changes, e.g. add them to the staging area or remove them, etc.

Run it via the following command.

git status 

Before committing changes to a Git repository you need to mark those that should be committed. This is done by adding the new and changed files to the staging area. This creates a snapshot of the affected files.

# add all files to the index of the Git repository

git add . 

Afterwards run the git status command again to see the current status.

After adding the files to the Git staging area, you can commit them to the Git repository. This creates a new commit object with the staged changes in the Git repository and the HEAD reference points to the new commit. The -m parameter allows you to specify the commit message. If you leave this parameter out, your default editor is started and you can enter the message in the editor.

# commit your file to the local repository

git commit -m "Initial commit" 

10. Looking at the result

The Git operations you performed have created a local Git repository in the .git folder and added all files to this repository via one commit. Run the git log command

# show the Git log for the change

git log 

You see an output similar to the following.

commit e744d6b22afe12ce75cbd1b671b58d6703ab83f5

Author: Lars Vogel <Lars.Vogel@gmail.com>

Date:   Mon Feb 25 11:48:50 2013 +0100

    Initial commit 

Your directory contains the Git repository as well as the Git working tree for your files. This directory structure is depicted in the following screenshot.

11. Remove files and adjust the last commit

If you delete a file which is under version control, git add . does not record this file deletion.

You can use the git rm command to delete the file from your working tree and record the deletion of the file in the staging area.

# create a file and commit it

touch nonsense2.txt

git add .

git commit -m "more nonsense"

# remove the file and record the deletion in Git

git rm nonsense2.txt

# commit the removal

git commit -m "Removes nonsense2.txt file" 

# create a file and put it under version control

touch nonsense.txt

git add .

git commit -m "create a new file"

# remove the file

rm nonsense.txt

# show status, output listed below the command

git status

# on branch master
# Changes not staged for commit:
#   (use "git add/rm <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  deleted:    nonsense.txt
#
# no changes added to commit (use "git add" and/or "git commit -a")

# try standard way of committing -> will NOT work 
# output of the command listed below

git add .

git commit -m "this does NOT remove the file"

# On branch master
# Changes not staged for commit:
#   (use "git add/rm <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  deleted:    nonsense.txt
#
# no changes added to commit (use "git add" and/or "git commit -a") 

# commit the remove with the -a flag

git commit -a -m "File nonsense.txt is now removed"

# alternatively you could add deleted files to the staging area via
# git add -A . 
# git commit -m "remove file nonsense.txt" 

You can use the git reset [filename] command to remove a file from the staging area, which you added with git add [filename]. Removing a file from the staging area, avoids that it included in the next commit.

# create a file and add to staging area

touch unwantedstaged.txt

git add unwantedstaged.txt

# remove it from the staging area

git reset unwantedstaged.txt

# to cleanup, delete it

rm unwantedstaged.txt 

The git commit --amend command makes it possible to replace the last commit. This allows you to change the last commit including the commit message.

Assume the last commit message was incorrect as it contained a typo. The following command corrects this via the --amend parameter.

# assuming you have something to commit

git commit -m "message with a tpyo here" 

git commit --amend -m "More changes - now correct" 

You should use the git --amend command only for commits which have not been pushed to a public branch of another Git repository. The git --amend command creates a new commit ID and people may have based their work already on the existing commit. In this case they would need to migrate their work based on the new commit.

Sometimes you change your .gitignore file. Git will stop tracking the new entries from this moment. The last version is still in the Git repository.

If you want to remove the last version of the files from your Git repository, you need to do this explicitly via the following command.

# remove directory .metadata from git repo

git rm -r --cached .metadata
# remove file test.txt from repo

git rm --cached test.txt 

12. Remote repositories

Remotes are URLs in a Git repository to other remote repositories that are hosted on the Internet, locally or in the network.

Such remotes can be used to synchronize the changes of several Git repositories. A local Git repository can be connected to multiple remote repositories and you can synchronize your local repository with them via Git operations.

It is possible that users connect their individual repositories directly, but a typically Git workflow involves one or more remote repositories which are used to synchronize the individual repository. Typically the remote repository which is used for synchronization is located on a server which is always available.

A remote repository on a server typically does not require a working tree. A Git repository without aworking tree is called a bare repository. You can create such a repository with the --bare option. The command to create a new empty bare remote repository is displayed below.

# create a bare repository

git init --bare 

By convention the name of a bare repository should end with the .git extension.

In this section you create a bare Git repository. In order to simplify the following examples, the Git repository is hosted locally in the filesystem and not on a server in the Internet.

Execute the following commands to create a bare repository based on your existing Git repository.

# switch to the first repository

cd ~/repo01

# create a new bare repository by cloning the first one

git clone --bare . ../remote-repository.git

# check the content of the git repo, it is similar
# to the .git directory in repo01
# files might be packed in the bare repository

ls ~/remote-repository.git 

If you clone a repository, Git implicitly creates a remote named origin by default. The origin remotelinks back to the cloned repository.

If you create a Git repository from scratch with the git init command, the origin remote is not created automatically.

You add more remotes to your repository with the git remote add command.

You created a new Git repository from scratch earlier. Use the following command to add a pointer to your new bare repository using the origin name.

# add ../remote-repository.git with the name origin

git remote add origin ../remote-repository.git 

You can synchronize your local Git repository with remote repositories. These commands are covered in detail in later sections but the following command demonstrates how you can send changes to your remote repository.

# do some changes

echo "I added a remote repo" > test02

# commit

git commit -a -m "This is a test for the new remote origin"

# to push use the command:
# git push [target]
# default for [target] is origin

git push origin 

To see the existing definitions of the remote repositories, use the following command.

# show the details of the remote repo called origin

git remote show origin 

To see the details of the remotes, e.g. the URL use the following command.

# show the existing defined remotes

git remote

# show details about the remotes

git remote -v 

13. Cloning remote repositories and push and pull

Clone a repository and checkout a working tree in a new directory via the following commands.

# switch to home

cd ~
# make new directory

mkdir repo02

# switch to new directory

cd ~/repo02
# clone

git clone ../remote-repository.git . 

The git push command allows you to send data to other repositories. By default it sends data from your current branch to the same branch of the remote repository. See Section 16.6, “Push changes of a branch to a remote repository” for details on pushing branches or Git push manpage for general information.

Make some changes in your local repository and push them from your first repository to the remote repository via the following commands.

# make some changes in the first repository

cd ~/repo01

# make some changes in the file

echo "Hello, hello. Turn your radio on" > test01

echo "Bye, bye. Turn your radio off" > test02

# commit the changes, -a will commit changes for modified files
# but will not add automatically new files

git commit -a -m "Some changes"

# push the changes

git push ../remote-repository.git 

The git pull command allows you to get the latest changes from another repository for the current branch.

To test this in your example Git repositories, switch to your second repository, pull in the recent changes from the remote repository, make some changes, push them to your remote repository via the following commands.

# switch to second directory

cd ~/repo02

# pull in the latest changes of your remote repository

git pull

# make changes

echo "A change" > test01

# commit the changes

git commit -a -m "A change"

# push changes to remote repository
# origin is automatically created as we cloned original from this repository

git push origin 

You can pull in the changes in your first example repository with the following commands.

# switch to the first repository and pull in the changes

cd ~/repo01

git pull ../remote-repository.git/

# check the changes

git status 

14. Online remote repositories

Git supports several transport protocols to connect to other Git repositories; the native protocol for Git is also called git.

The following command clones an existing repository using the Git protocol. The Git protocol uses the port 9148 which might be blocked by firewalls.

# switch to a new directory

mkdir ~/online

cd ~/online

# clone online repository

git clone git://github.com/vogella/gitbook.git 

If you have SSH access to a Git repository, you can also use the ssh protocol. The name preceding @ is the user name used for the SSH connection.

# clone online repository

git clone ssh://git@github.com/vogella/gitbook.git

# older syntax

git clone git@github.com:vogella/gitbook.git 

Alternatively you could clone the same repository via the http protocol.

# the following will clone via HTTP

git clone http://github.com/vogella/gitbook.git 

As discussed earlier cloning repository creates a remote called origin pointing to the remote repository which you cloned from.

You can push changes to this origin repository via git push as Git uses origin as default. Of course, pushing to a remote repository requires write access to this repository.

You can add more remotes via the git remote add [name] [URL_to_Git_repo] command. For example, if you cloned the repository from above via the Git protocol, you could add a new remote with the name github_http for the http protocol via the following command.

# add the HTTPS protocol

git remote add github_http https://vogella@github.com/vogella/gitbook.git 

To rename an existing remote repository use the git remote rename command. This is demonstrated by the following listing.

# rename the existing remote repository from 
# github_http to github_testing

git remote rename github_http github_testing 

It is possible to use the HTTP protocol to clone Git repositories. This is especially helpful if your firewall blocks everything except HTTP or HTTPS.

Git also provides support for HTTP access via a proxy server. The following Git command could, for example, clone a repository via HTTP and a proxy. You can either set the proxy variable in general for all applications or set it only for Git.

This example uses environment variables.

# Linux

export http_proxy=http://proxy:8080

export https_proxy=https://proxy:8443 

# Windows

set http_proxy http://proxy:8080

set https_proxy http://proxy:8080 

git clone http://dev.eclipse.org/git/org.eclipse.jface/org.eclipse.jface.snippets.git 

This example uses the following Git config settings.

# set proxy for git globally

git config --global http.proxy http://proxy:8080
# to check the proxy settings

git config --get http.proxy
# just in case you need to you can also revoke the proxy settings

git config --global --unset http.proxy 

15. What are branches?

16. Commands to working with branches

The git branch command lists all local branches. The currently active branch is marked with *.

# lists available branches

git branch 

If you want to see all branches (including remote tracking branches), use the -a for the git branchcommand. See Section 32.1, “Remote tracking branches” for information about remote tracking branches.

# lists all branches including the remote branches

git branch -a 

The -v option lists more information about the branches.

In order to list branches or tags in a remote repository use the git ls-remote command as demonstrated in the following example.

# lists branches and tags in the
# remote repository called origin 

 git ls-remote origin 

You can create a new branch via the git branch [newname] command. This command allows to specify the starting point (commit id, tag, remote or local branch). If not specified the commit to which the HEAD reference points is used to create the branch.

# syntax: git branch <name> <hash>
# <hash> in the above is optional

git branch testing 

To start working in a branch you have to checkout the branch. If you checkout a branch, the HEAD pointer moves to the last commit in this branch and the files in the working tree are set to the state of this commit.

The following commands demonstrates how you switch to the branch called testing, perform some changes in this branch and switch back to the branch called master.

# switch to your new branch

git checkout testing

# do some changes

echo "Cool new feature in this branch" > test01

git commit -a -m "new feature"

# switch to the master branch

git checkout master

# check that the content of
# the test01 file is the old one

cat test01 

To create a branch and to switch to it at the same time you can use the git checkout command with the -b parameter.

# create branch and switch to it

git checkout -b bugreport12

# creates a new branch based on the master branch
# without the last commit

git checkout -b mybranch master~1 

Renaming a branch can be done with the following command.

# rename branch

git branch -m [old_name] [new_name] 

To delete a branch which is not needed anymore, you can use the following command. You may get an error message that there are uncommited changes if you did the previous examples step by step. Use force delete (uppercase -D) to delete it anyway.

# delete branch testing

git branch -d testing
# force delete testing

git branch -D testing
# check if branch has been deleted

git branch 

You can push the changes in the current active branch to a remote repository by specifying the target branch. This creates the target branch in the remote repository if it does not yet exist.

# push current branch to a branch called "testing" to remote repository

git push origin testing

# switch to the testing branch

git checkout testing

# some changes

echo "News for you" > test01

git commit -a -m "new feature in branch"

# push all including branch

git push 

This way you can decide which branches you want to push to other repositories and which should be local branches. You learn more about branches and remote repositories in Section 32.1, “Remote tracking branches”.

17. Differences between branches

18. Tags in Git

Git has the option to tag a commit in the repository history so that you find it easier at a later point in time. Most commonly, this is used to tag a certain version which has been released.

If you tag a commit, you create an annotated or lightweight tag.

Git supports two different types of tags, lightweight and annotated tags.

A lightweight tag is a pointer to a commit, without any additional information about the tag. Anannotated tag contains additional information about the tag, e.g. the name and email of the person who created the tag, a tagging message and the date of the tagging. Annotated tags can also be signed and verified with GNU Privacy Guard (GPG).

19. Tagging in Git

You can list the available tags via the following command:

git tag 

You can use the -l parameter in the git tag command to search for a pattern in the tag.

git tag -l <pattern> 

To create a lightweight tag don't use the -m, -a or -s option. Lightweight tags are often used for build tags which do not need additional information other than the build number or the timestamp.

# create lightweight tag

git tag 1.7.1

# see the tag

git show 1.7.1 

You can create a new annotated tag via the git tag -a command. An annotated tag can also be created using the -m parameter, which is used to specify the description of the tag. The following command tags the current active HEAD.

# create tag

git tag 1.6.1 -m 'Release 1.6.1'

# show the tag

git show 1.6.1 

You can also create tags for a certain commit id.

git tag 1.5.1 -m 'version 1.5' [commit id] 

You can use the option -s to create a signed tag. These tags are signed with GNU Privacy Guard (GPG)and can also be verified with GPG. For details on this please see the following URL: Git tag manpage.

If you want to use the code associated with the tag, use:

git checkout <tag_name> 

By default the git push command does not transfer tags to remote repositories. You explicitly have to push the tag with the following command.

# push a tag or branch called tagname

git push origin [tagname]

# to explicitly push a tag and not a branch 

git push origin tag <tagname> 

You can delete tags with the -d parameter. This deletes the tag from your local repository. By default Git does not push tag deletions to a remote repository, you have to trigger that explicitly.

The following commands demonstrate how to push a tag deletion.

# delete tag locally

git tag -d 1.7.0

# delete tag in remote repository
# called origin

git push origin :refs/tags/1.7.0 

Tags are frequently used to tag the state of a release of the Git repository. In this case they are typically called release tags.

Convention is that release tags are labeled based on the [major].[minor].[patch] naming scheme, for example "1.0.0". Several projects also use the "v" prefix.

The idea is that the patch version is incremented if (only) backwards compatible bug fixes are introduced, the minor version is incremented if new, backwards compatible functionality is introduced to the public API and the major version is incremented if any backwards incompatible changes are introduced to the public API.

For the detailed discussion on naming conventions please see the following URL: Semantic versioning.

20. Viewing changes in the working tree with git status

The git status command shows the status of the working tree, i.e., which files have changed, which are staged and which are not part of the staging area. It also shows which files have merge conflicts and gives an indication what the user can do with these changes, e.g., add them to the staging area or remove them, etc.

The following commands create some changes in your Git repository.

# make some changes
# assumes that the test01 
# as well as test02 files exist
# and have been committed in the past 

echo "This is a new change to the file" > test01

echo "and this is another new change" > test02

# create a new file

ls > newfileanalyzis.txt 

The git status command show the current status of your repository and suggest possible actions.

# see the current status of your repository 
# (which files are changed / new / deleted)

git status 

The output of the command looks like the following.

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#   (use "git push" to publish your local commits)
#
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  modified:   test01
#  modified:   test02
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#  newfileanalyzis.txt

no changes added to commit (use "git add" and/or "git commit -a") 

21. Analyzing the repository history with git log

The git log commands shows the history of your repository in the current branch, i.e. the list of commits.

# show the history of commits in the current branch

git log 

The oneline parameter fits the output of the git log command in one line.

If you use the abbrev-commit parameter, the git log command uses shorter versions of the SHA-1 identifier for a commit object but keeps the SHA-1 unique.

The graph parameter draws a text-based graphical representation of the branches and the merge history of the Git repository.

# uses shortend but unique SHA-1 values 
# for the commit objects 

git log --abbrev-commit

# show the history of commits in one line
# with a shortened version of the commit id
# --online is a shorthand for "--pretty=oneline --abbrev-commit" 

git log --oneline 

# show the history as graph including branches

git log --graph --oneline 

For more options on the git log command see the Git log manpage.

To see changes in a file you can use the -p option in the git log command.

# git log filename shows the commits for this file

git log [file path]

# Use -p to see the diffs of each commit

git log -p filename

# --follow shows the entire history
# including renames

git log --follow -p file 

You can use the --author tag to filter the log output by a certain author. You do not need to use the full name, if a substring matches, the commit is included in the log output.

The following command lists all commits with an author name containing the word "lvogel".

git log --author=lvogel 

22. Viewing changes with git diff and git show

The git diff command allows the user to see the changes made. In order to test this, make some changes to a file and check what the git diff command shows to you. Afterwards commit the changes to the repository.

# make some changes to the file

echo "This is a change" > test01

echo "and this is another change" > test02

# check the changes via the diff command

git diff

# optional you can also specify a path to filter the displayed changes
# path can be a file or directory

git diff [path] 

To see which changes you have staged, i.e., you are going to commit with the next commit, use the following command.

# make some changes to the file

git diff --cached 

To see the changes introduced by a commit use the following command.

git show <commit_id> 

To see the differences introduced between two commits you use the git diff command specifying the commits. For example, the following command shows the differences introduced in the last commit.

git diff HEAD~1 HEAD 

To see the files which have been changed in a commit use the git diff-tree command. The name-only tells the command to show only the names of the files.

git diff-tree --name-only -r <commit_id> 

23. Analyzing line changes with git blame

24. git shortlog for release announcements

25. Stashing committed changes with git stash

Git provides the git stash command which allows you to record the current state of the working directory and the staging area and go back to the last committed revision.

This allows you to pull in the latest changes or to develop an urgent fix. Afterwards you can restore the stashed changes, which will reapply the changes to the current version of the source code.

In general using the stash command should be the exception in using Git. Typically you would create new branches for new features and switch between branches. You can also commit frequently in your local Git repository and use interactive rebase to combine these commits later before pushing them to another Git repository.

26. Remove untracked files with git clean

If you have untracked files in your working tree which you want to remove, you can use the git cleancommand.

The following commands demonstrates the usage of the git clean command.

# create a new file with content

echo "this is trash to be deleted" > test04

# make a dry-run to see what would happen
# -n is the same as --dry-run 

git clean -n

# delete, -f is required if 
# variable clean.requireForce is not set to false

git clean -f

# use -d flag to delete new directories
# use -x to delete hidden files, e.g. ".example"

git clean -fdx 

27. Revert uncommitted changes

Changes in the working tree which are unstaged can be undone with git checkout command. This command resets the file in the working tree to the last staged or committed version.

# delete a file

rm test01

# revert the deletion

git checkout -- test01

# note git checkout test01 also works but using
# two - ensures that Git understands that test01 
# is a path and not a parameter

# change a file

echo "override" > test01

# restore the file

git checkout -- test01 

For example, you can restore a directory called data with the following command.

git checkout -- data 

If you want to undo a staged but uncommitted change, you can still use the git checkout command if you specify a commit pointer to use.

The following demonstrates the usage of this to restore a delete directory.

# assuming you deleted a tracked directory
# and staged the changes

# restore the working tree and reset the staging area

git checkout HEAD -- your_dir_to_restore 

The additional commit pointer parameter instructs the git checkout command to reset the working tree and to also remove the staged changes.

If you added a new file to the staging area but do not want to commit the file, you can remove it from the staging area via the git reset file command.

# create a file and 
# accidently add it to the staging area

touch incorrect.txt

git add .

# remove it from the staging area

git reset incorrect.txt

# to clean up, delete the file
# not necessary, maybe you want to add it later to the staging area

rm incorrect.txt 

If you have added the changes of a file to the staging area, you can also revert the changes in the staging area and checkout the file from the index.

# some nonsense change

echo "change which should be removed later" > test01

# add the file to the staging area

git add test01

# restore the file in the staging area

git reset HEAD test01

# get the version from the staging area
# into the working tree

git checkout test01 

28. Moving the HEAD pointer with git reset

The commits which were above the commit to which you resetted, can be reached via the git reflogcommand. See Section 31, “Recovering lost commits”.

The git reset --hard command makes the working tree exactly match HEAD but it does not delete untracked files in your working tree. If you want to delete them also, you need to use the git clean -fcommand in addition.

# removes staged and working tree changes
# of committed files

git reset --hard 

# the above does not remove untracked files therefore 
# the next command is needed

# removes new files which are still untracked 

git clean -f -d 

As a soft reset does not remove your change to your files and index, you can use the git reset --softcommand to squash several commits into one commit.

As the staging area is not changed, you have it after the soft reset in the desired state for your new commit, i.e., it has all the changes from the commits that you removed with the reset.

# squashes the last two commits

git reset --soft HEAD~1 && git commit -m "new commit message" 

The interactive rebase adds more flexibility to squashing commits and allows to use the existing commit messages. See Section 37.2, “Interactive rebase to edit history” for details.

29. Retrieving files from the history

The git show command allows to see and retrieve files from branches, commits and tags. It allows to see the status of these files in the selected branch, commit or tag without checking them out into your working tree.

The following commands demonstrate that. You can also make a copy of the file.

# [reference] can be a branch, tag, HEAD or commit ID 
# [filename] is the filename including path

git show [reference]:[filename]

# to make a copy to copiedfile.txt

git show [reference]:[filename] > copiedfile.txt 

You can checkout a file from the commit. To find the commit which deleted the file you can use the git log or the git ref-list command as demonstrated by the following command.

# see history of file

git log -- <file_path>

# checkout file based on predecessors the last commit which affect it
# this was the commit which delete the file

git checkout [commit] ^ -- <file_path>

# alternatively use git rev-list

git rev-list -n 1 HEAD -- <file_path>

# afterwards, the same checkout based on the predecessors 

git checkout [commit] ^ -- <file_path> 

The git log command allows you to determine which commit deleted a file. You can use the -- option in git log to see the commit history for a file, even if you have deleted the file.

# see the changes of a file, works even 
# if the file was deleted

git log -- [file path]

# limit the output of Git log to the 
# last commit, i.e. the commit which delete the file
# -1 to see only the last commit
# use 2 to see the last 2 commits etc

git log -1 -- [file path]

# include stat parameter to see
# some statics, e.g. how many files were 
# deleted

git log -1 --stat -- [file path] 

30. Checkout or revert commits

You can check out older revisions of your file via the commit ID. The commit ID is shown if you enter the git log command.

The following command would show the log.

# displays the commit history of the repository
# which contains the commit ID, author, message etc.

git log 

The following listing shows an example output of a Git log command.

commit 046474a52e0ba1f1435ad285eae0d8ef19d529bf

Author: Lars Vogel <Lars.Vogel@gmail.com>

Date:   Wed Jun 5 12:13:04 2013 +0200

    Bug 409373 - Updates version number of e4 tools 

    Repairs the build

commit 2645d7eef0e24195fc407137200fe7e1795ecf49

Author: Lars Vogel <Lars.Vogel@gmail.com>

Date:   Wed Jun 5 12:00:53 2013 +0200

    Bug 409373 - Updates version number of e4 CSS spy features 

To checkout a specific commit you can use the following command.

# checkout the older revision via 

git checkout [commit_id]

# based on the example output this could be

git checkout 046474a52e0ba1f1435ad285eae0d8ef19d529bf 

You can revert commits via the git revert command. git revert will revert the changes of a commit and record a new commit which documents that the other commit was reverted.

# revert a commit

git revert commit_id 

31. Recovering lost commits

If you checkout a commit or a tag, you are in the so-called detached HEAD mode . If you commit changes in this mode, you have no branch which points to this commit. After you checkout a branch you cannot see the commit you did in detached head mode in the git log command.

To find such commits you can use the git reflog command.

Reflog is a mechanism to record the movements of the HEAD pointer and the branches. HEAD is a pointer to the currently selected commit object.

The Git reflog command gives a history of the complete changes of the HEAD pointer.

git reflog
# <output>
# ... snip ...

1f1a73a HEAD@{2}: commit: More chaanges - typo in the commit message

45ca204 HEAD@{3}: commit: These are new changes

cf616d4 HEAD@{4}: commit (initial): Initial commit 

The git reflog command also list commits which you have removed.

The following example shows how you can use git reflog to reset the current local branch to a commit which isn't reachable from the git log anymore.

# assume the  ID for the second commit is
# 45ca2045be3aeda054c5418ec3c4ce63b5f269f7

# resets the head for your tree to the second commit

git reset --hard 45ca2045be3aeda054c5418ec3c4ce63b5f269f7

# see the log

git log

# output shows the history until the 45ca2045be commit

# see all the history including the deletion

git reflog 

# <output>

cf616d4 HEAD@{1}: reset: moving to 45ca2045be3aeda054c5418ec3c4ce63b5f269f7
# ... snip ...

1f1a73a HEAD@{2}: commit: More chaanges - typo in the commit message

45ca204 HEAD@{3}: commit: These are new changes

cf616d4 HEAD@{4}: commit (initial): Initial commit

git reset --hard 1f1a73a 

32. Remote and local tracking branches

Your local Git repository contains references to the state of the branches on the remote repositories to which it is connected. These local references are called remote tracking branches.

You can see your remote tracking branches with the following command.

# list all remote branches

git branch -r 

To update remote tracking branches without changing local branches you use the git fetch command which is covered in Section 33, “Updating your remote tracking branches with git fetch”.

It is also safe to delete a remote branch in your local Git repository. You can use the following command for that.

# delete remote branch from origin

git branch -d -r origin/[remote_branch] 

The next time you run the git fetch command the remote branch is recreated.

To delete the branch in a remote repository use the following command.

# delete branch in a remote repository

git push [remote] :branch 

Alternatively you can also use the following command.

# delete branch in a remote repository

git push [remote] --delete :[branch] 

For example if you want to delete the branch called testbranch in the remote repository called originyou can use the following command.

git push origin :testbranch 

git push ssh://[URL_to_repo] :testbranch 

Branches can track another branch. This is called to have an upstream branch and such branch can be referred to as tracking branches.

Tracking branches allow you to use the git pull and git push command directly without specifying the branch and repository.

If you clone a Git repository, your local master branch is created as a tracking branch for the masterbranch of the origin repository (short: origin/master) by Git.

You create new tracking branches by specifying the remote branch during the creation of a branch. The following example demonstrates that.

# setup a tracking branch called newbrach
# which tracks origin/newbranch

git checkout -b newbranch origin/newbranch 

Instead of using the git checkout command you can also use the git branch command.

# origin/master used as example, but can be replaced

# create branch based on remote branch

git branch [new_branch] origin/master

# use --track, 
# default when the start point is a remote-tracking branch

git branch --track [new_branch] origin/master 

The --no-track allows you to specify that you do not want to track a branch. You can explicitly add a tracking branch with the git branch -u command later.

# instruct Git to create a branch which does 
# not track another branch

git branch --no-track [new_branch_notrack] origin/master

# update this branch to track the origin/master branch

git branch -u origin/master [new_branch_notrack] 

To see the tracking branches for a remote repository (short: remote) you can use the following command.

# show all remote and tracking branches for origin

git remote show origin 

An example output of this might look like the following.

* remote origin

  Fetch URL: ssh://test@git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git

  Push  URL: ssh://test@git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git

  HEAD branch: master

  Remote branches:

    integration                tracked

    interm_rc2                 tracked

    master                     tracked

    smcela/HandlerAddonUpdates tracked

  Local branches configured for 'git pull':

    integration rebases onto remote integration

    master      rebases onto remote master

    testing     rebases onto remote master

  Local refs configured for 'git push':

    integration pushes to integration (up to date)

    master      pushes to master      (up to date) 

33. Updating your remote tracking branches with git fetch

The git fetch command updates your remote tracking branches, i.e. it updates the local copy of branches stored in a remote repository. The following command updates the remote tracking branchesfrom the repository called origin.

git fetch origin 

The fetch command only updates the remote tracking branches and none of the local branches and it does not change the working tree of the Git repository. Therefore you can run the git fetch command at any point in time.

After reviewing the changes in the remote tracking branch you can merge the changes into your local branches or rebase your local branches onto the remote tracking branch.

Alternatively you can also use the git cherry-pick "sha" command to take over only selected commits.

The git fetch command updates only the remote tracking branches for one remote repository. In case you want to update the remote tracking branches of all your remote repositories you can use the following command.

# simplification of the fetch command
# this runs git fetch for every remote repository

git remote update

# the same but remove all stale branches which 
# are not in the remote anymore

git remote update --prune 

The following code shows a few options how you can compare your branches.

# show the log entries between the last local commit and the
# remote branch  

git log HEAD..origin/master

# show the diff for each patch 

git log -p HEAD..origin/master  

# show a single diff 

git diff HEAD...origin/master

# instead of using HEAD you can also
# specify the branches directly

git diff master origin/master 

The above commands shows the changes introduced in HEAD compared to origin. If you want to see the changes in origin compared to HEAD, you can switch the arguments or use the -R parameter.

You can rebase your current local branch onto a remote tracking branch. The following commands demonstrate that.

# assume you want to rebase master based on the latest fetch
# therefore check it out

git checkout master

# update your remote tracking branch

git fetch

# rebase your master onto origin/master

git rebase origin/master 

The git pull command performs a git fetch and git merge (or git rebase based on your Git settings). The git fetch does not perform any operations on your local branches. You can always run the fetch command and review the incoming changes.

34. Merging

35. Command to merge two branches

36. Merging branches

If the commits which are merged are direct predecessors of the HEAD pointer of the current branch, Git simplifies things by performing a so-called fast forward merge. This fast forward merge simply moves the HEAD pointer of the current branch to the last commit of the branch which is being merged.

This process is depicted in the following graphics. The first picture assumes that master is checked out and that you want to merge the changes of the branch labeled "branch" into your "master" branch. Each commit points to its predecessor (parent).

After the fast forward merge the HEAD pointer of "master" points to the existing commit.

If commits are merged which are not direct predecessors of the HEAD pointer of the current branch, Git performs a so-called three-way-merge between the latest commits of the two branches, based on the most recent common predecessor of both.

As a result a so-called merge commit is created on the current branch which is combining the respective changes from the two branches being merged. This commit points to both of its predecessors.

The -s parameter allows you to specify other merge strategies. This is demonstrated with the following command.

For example, you can specify the ours strategy in which the result of the merge is always that of the current branch head, effectively ignoring all changes from all other branches. This is demonstrated with the following command.

# merge branch "obsolete" ignoring all 
# changes in the branch

git merge -s ours obsolete 

The recursive merge strategy (default) allows you to specify flags with the -X parameter. For example you can specify here the ours option. This option forces conflicting changes to be auto-resolved cleanly by favoring the local version. Changes from the other branch that do not conflict with our local version are reflected to the merge result. For a binary file, the entire contents are taken from the local version.

A similar option to ours is the theirs option. This option prefers the version from the branch which is merged.

Both options are demonstrated in the following example code.

# merge changes preferring our version

git merge -s recursive -X ours [branch_to_merge]

# merge changes preferring the version from 
# the branch to merge

git merge -s recursive -X theirs [branch_to_merge] 

Another useful option is the ignore-space-change parameter which ignores whitespace changes.

For more information about the merge strategies and options see Git merge manpage.

37. Rebase

You can use Git to rebase one branch on another one. As described, the merge command combines the changes of two branches. If you rebase a branch called A onto another, the git command takes the changes introduced by the commits of branch A and applies them based on the HEAD of the other branch. This way the changes in the other branch are also available in branch A.

The processes is displayed in the following picture. We want to rebase the branch onto master.

Running the rebase command creates a new commit with the changes of the branch on top of the master branch.

Performing a rebase from one branch to another branch does not create a merge commit.

The final result for the source code is the same as with merge but the commit history is cleaner; the history appears to be linear.

# create new branch 

git checkout -b rebasetest

# create a new file and put it under revision control

touch rebase1.txt

git add . && git commit -m "work in branch"

# do changes in master

git checkout master

# make some changes and commit into testing

echo "rebase this to rebasetest later" > rebasefile.txt

git add rebasefile.txt

git commit -m "create new file"

# rebase the rebasetest onto master

git checkout rebasetest

git rebase master

# now you can fast forward your branch onto master

git checkout master

git merge rebasetest 

Rebase can be used to place a feature branch in the local Git repository onto the changes of the master branch. This ensures that your feature is close to the tip of the upstream branch until it is finally published.

The rebase command allows you to edit your commit history. For example, you can combine several commits into one commit, reorder or skip commits and edit commit message.

This is useful as it allows the user to rewrite some of the commit history (cleaning it up) before pushing your changes to a remote repository.

The following will create several commits which should be combined at a later point in time.

# create a new file

touch rebase.txt

# add it to git

git add . && git commit -m "add rebase.txt  to staging area"

# do some silly changes and commit

echo "content" >> rebase.txt

git add . && git commit -m "add content"

echo " more content" >> rebase.txt

git add . && git commit -m "just testing"

echo " more content" >> rebase.txt

git add . && git commit -m "woops"

echo " more content" >> rebase.txt

git add . && git commit -m "yes"

echo " more content" >> rebase.txt

git add . && git commit -m "add more content"

echo " more content" >> rebase.txt

git add . && git commit -m "creation of important configuration file"

# check the git log message

git log 

We will combine the last seven commits. You can do this interactively via the following command.

git rebase -i HEAD~7 

This will open your editor of choice and let you configure the rebase operation by defining which commits to pick, squash or fixup.

Pick includes the selected commit. Squash combines the commit messages while fixup will disregard the commit message. The following shows an example of the selection, we pick the last commit, squash 5 commits and fix the sixth commit.

p 7c6472e rebase.txt added to index

f 4f73e68 added content

f bc9ec3f just testing

f 701cbb5 ups

f 910f38b yes

f 31d447d added more content

s e08d5c3 creation of important configuration file

# Rebase 06e7464..e08d5c3 onto 06e7464

#

# Commands:

#  p, pick = use commit

#  r, reword = use commit, but edit the commit message

#  e, edit = use commit, but stop for amending

#  s, squash = use commit, but meld into previous commit

#  f, fixup = like "squash", but discard this commit's log message

#  x, exec = run command (the rest of the line) using shell

#

# These lines can be re-ordered; they are executed from top to bottom.

#

# If you remove a line here THAT COMMIT WILL BE LOST.

# However, if you remove everything, the rebase will be aborted. 

You should always check your local branch history before pushing changes to another Git repository or review system.

Git allows you to do local commits. This feature is frequently used to have commits to which you can go back, if something should go wrong during a feature development. Before pushing you should look at your local branch history and validate, whether or not these commits are relevant for others.

If they all belong to the implementation of the same feature you, most likely, want to summarize them in one single commit before pushing.

The interactive rebase is basically rewriting the history. It is safe to do this as long as the commits have not been pushed to another repository. This means commits should only be rewritten as long as they have not been pushed.

If you rewrite and push a commit that is already present in other Git repositories, it will look as if you implemented something that somebody had already implemented.

For example, assume that a user has a local feature branch and wants to push it onto a branch on the remote repository. However, the branch has evolved and therefore pushing is not possible. Now it is good practice to fetch the latest state of the branch from the remote repository. Afterwards you rebase the local feature branch onto the remote tracking branch. This avoids an unnecessary merge commit. This rebasing of a local feature branch is also useful to incorporate the latest changes from remote into the local development, even if the user does not want to push right away.

# using forced push

git push -f 

38. Selecting individual commits with git cherry-pick

The git cherry-pick command allows you to select the patch which was introduced with an individual commit and apply this patch on another branch. The patch is captured as a new commit on the other branch.

This way you can select individual changes from one branch and transfer them to another branch.

In the following example you create a new branch and commit two changes.

# create new branch

git checkout -b picktest

# create some data and commit

touch pickfile.txt

git add pickfile.txt

git commit -m "adds new file"

# create second commit  

echo "changes to file" > pickfile.txt

git commit -a -m "changes in file" 

You can check the commit history, for example, with the git log --oneline command.

# see change commit history

git log --oneline

# results in the following output

2fc2e55 changes in file

ebb46b7 adds new file

[MORE COMMITS]

330b6a3 initial commit 

The following command selects the first commit based on the commit id and applies its changes to the master branch. This creates a new commit on the master branch.

git checkout master

git cherry-pick ebb46b7 

The cherry-pick command can be used to change the order of commits. git cherry-pick also accepts commit ranges for example in the following command.

git checkout master
# pick the last two commits

git cherry-pick picktest~1..picktest~2 

If things go wrong or you change your mind, you can always reset to the previous state using the following command.

git cherry-pick --abort 

39. Solving merge conflicts

A merge conflict occurs if two commits from different branches have modified the same content and Git cannot automatically determine how both changes should be combined when merging these branches.

If a merge conflict occurs, Git will mark the conflict in the file and the programmer has to resolve the conflict manually. After resolving it, he can add the file to the staging area and commit the change.

In the following example you first create a merge conflict and afterwards you resolve the conflict and apply the change to the Git repository.

The following code creates a merge conflict. It assumes that repo1 and repo2 have the same originrepository defined.

# switch to the first directory

cd ~/repo01
# make changes

echo "Change in the first repository" > mergeconflict.txt
# stage and commit

git add . && git commit -a -m "Will create merge conflict 1"

# switch to the second directory

cd ~/repo02
# make changes

touch mergeconflict.txt

echo "Change in the second repository" > mergeconflict.txt
# stage and commit

git add . && git commit -a -m "Will create merge conflict 2"
# push to the master repository

git push

# now try to push from the first directory
# switch to the first directory

cd ~/repo01
# try to push --> you will get an error message

git push

# get the changes via a pull
# this creates the merge conflict in your
# local repository

git pull origin master 

Git marks the conflict in the affected file. This file looks like the following.

<<<<<<< HEAD

Change in the first repository

=======

Change in the second repository

>>>>>>> b29196692f5ebfd10d8a9ca1911c8b08127c85f8 

The above is the part from your repository and the below one from the remote repository. You can edit the file manually and afterwards commit the changes.

Alternatively, you could use the git mergetool command. git mergetool starts a configurable merge tool that displays the changes in a split screen. git mergetool is not always available. It is also safe to edit the file with merge conflicts in a normal editor.

# either edit the file manually or use

git mergetool
# you will be prompted to select which merge tool you want to use,
# for example, on Ubuntu you can use the tool "meld"
# after merging the changes manually, commit them

git commit -m "merge changes" 

Instead of using the -m option in the above example you can also use the git commit command without this option. In this case the command opens your default editor with a default commit messages about the merged conflicts. It is good practice to use this message.

40. Define alias

An alias in Git allows you to setup your own Git command. For example, you can define an alias which is a short form of your own favorite commands or you can combine several commands with an alias.

The following defines an alias to see the staged changes with the new git staged command.

git config --global alias.staged 'diff --cached'
 

Or you can define an alias for a detailed git log command. The following command defines the git llalias.

git config --global alias.ll 'log --graph --oneline --decorate --all'
 

You can also run external commands. In this case you start the alias definition with a ! character. For example, the following defines the git ac command which combines git add . -A and git commitcommands.

# define alias

git config --global alias.act '!git add . -A && git commit'

# to use it

git ac -m "message" 

41. Submodules - repositories inside other Git repositories

Git allows you to include other Git repositories into a Git repository. This is useful in case you want to include a certain library in another repository or in case you want to aggregate certain Git repositories.

Git calls these included Git repositories submodules. Git allows you to commit, pull and push to these repositories independently.

You add a submodule to a Git repository via the git submodule add command. The git submodule init command creates the local configuration file for the submodules if it does not yet exist.

# add a submodule to your Git repo

git submodule add [URL to Git repo]

# initialize submodule configuration

git submodule init 

To pull in changes into a Git repository including the changes in submodules, you can use the --recurse-submodules parameter in the git pull command.

# pull in the changes from main repo and submodules

git pull --recurse-submodules 

Use the git submodule update command to set the submodules to the commit specified by the main repository.

# setting the submodules to the commit defined by master

git submodule update 

By default, submodules are tracked by commits, i.e., the main Git repository remembers a certain commit of the submodule. The git submodule update command sets the Git repository of the submodule to that particular commit. The submodule repository tracks its own content which is nested into the main repository. This main repository refers to a commit of the nested submodule repository.

If you update your submodule and want to use this update in your main repository, you need to commit this change in your main repository. The git submodule update command sets the submodule to the commit referred to in the main repository.

The following example shows how to update a submodule to its latest commit in its master branch.

# update submodule in the master branch
# skip this if you use --recurse-submodules 
# and have the master branch checked out

cd [submodule directory]

git checkout master

git pull

# commit the change in main repo
# to use the latest commit in master of the submodule

cd ..

git add [submodule directory]

git commit -m "move submodule to latest commit in master"

# share your changes

git push 

Another developer can get the update by pulling in the changes and running the submodules update command.

# another developer wants to get the changes

git pull

# this updates the submodule to the latest
# commit in master as set in the last example

git submodule update 

Since tracking of branches is a very common requirement, Git added the option to track a certain branch in its 1.8.2 release. To track branches you specify the branch with the -b parameter during thesubmodule add command.

This allows you use to use --remote parameter in the git submodule update command.

# add submodule to track master branch

git submodule add -b master [URL to Git repo];

# update your submodule
# --remote will also fetch and ensure that
# the latest commit from the branch is used

git submodule update --remote

# to avoid fetching use

git submodule update --remote --no-fetch 

42. Error search with git bisect

The git bisect command allows you to run a binary search through the commit history to identify the commit which introduced an issue. You specify a range of commits and a script that the bisectcommand uses to identify whether a commit is good or bad.

This script must return 0 if the condition is fulfilled and non-zero if the condition is not fulfilled.

Create a new Git repository, create the text1.txt file and commit it to the repository. Do a few more changes, remove the file and again do a few more changes.

We use a simple shell script which checks the existence of a file. Ensure that this file is executable.

#!/bin/bash

FILE=$1

if [ -f $FILE ];

then

   exit 0;

else

   exit 1;

fi 

Afterwards use the git bisect command to find the bad commit. First you use the git bisect startcommand to define a commit known to be bad (showing the problem) and a commit known to be good (not showing the problem).

# define that bisect should check
# the last 5 commits

git bisect start HEAD HEAD~5 

Afterwards run the bisect command using the shell script.

# assumes that the check script
# is a directory above the current

git bisect run ../check.sh test1.txt 

43. Rewriting commit history with git filter-branch

The git filter-branch command allows you to rewrite the Git commit history for selected branches and to apply custom filters on each revision. This creates different hashes for all modified commits. This implies you also get new IDs for all commits based on any rewritten commit.

The command allows you to filter for several values, e.g., the author, the message, etc. For details please see the following link:

git-filter-branch(1) Manual Page

The following listing shows an example on how to replace the email address from one author of all the commits via the git filter-branch command.

git filter-branch -f \

--env-filter 'if [ "$GIT_AUTHOR_NAME" = "Lars Vogel" ]; then \

GIT_AUTHOR_EMAIL="lars.vogel@gmail.com"; fi' HEAD) 

44. Create and apply patches

A patch is a text file that contains changes to the source code. A patch created with the git format-patch command includes meta-information about the commit (committer, date, commit message, etc) and also contains the diff of any binary data in the commit, for example, an image.

This file can be sent to someone else and this developer can use this file to apply the changes to his local repository. The metadata is preserved.

Alternatively you could create a diff file with the git diff command, but this diff file does not contain the metadata information.

The following example creates a branch, changes several files and creates a commit recording these changes.

# create a new branch

git branch mybranch
# use this new branch

git checkout mybranch
# make some changes

touch test05
# change some content in an existing file

echo "new content for test01" >test01
# commit this to the branch

git add .

git commit -a -m "first commit in the branch" 

The next example creates a patch for these changes.

# creates a patch --> git format-patch master

git format-patch origin/master

# this creates the file:
# patch 0001-First-commit-in-the-branch.patch 

To apply this patch to your master branch in a different clone of the repository, switch to it and use thegit apply command.

# switch to the master branch

git checkout master

# apply the patch

git apply 0001-First-commit-in-the-branch.patch 

Afterwards you can commit the changes introduced by the patches and delete the patch file.

# patch is applied to master
# change can be committed

git add .

git commit -a -m "apply patch"

# delete the patch file

rm 0001-First-commit-in-the-branch.patch 

You can use specify the commit id and the number of patches which should be created. For example, to create a patch for selected commits based on the HEAD pointer you can use the following commands.

# create patch for the last commit based on HEAD

git format-patch -1 HEAD

# create a  patch series for the last three commits 
# based on head

git format-patch -3 HEAD 

45. Git commit and other hooks

Git provides commit hooks, e.g. programs which can be executed at a pre-defined point during the work with the repository. For example, you can ensure that the commit message has a certain format or trigger an action after a push to the server.

These programs are usually scripts and can be written in any language, e.g. as shell scripts or in Perl, Python etc. You can also implement a hook, for example, in C and use the resulting executable. Git calls the scripts based on a naming convention.

Git provides hooks for the client and for the server side. On the server side you can use the pre-receive and post-receive script to check the input or to trigger actions after the commit.

If you create a new Git repository, Git creates example scripts in the .git/hooks directory. The example scripts end with .sample. To activate them make them executable and remove the .samplefrom the filename.

The hooks are documented under the following URL: Git hooks manual page.

46. Line endings on different platforms

47. Migrating from SVN

48. Frequently asked questions

The usage of symlinks requires that the operating system used by the developers supports them.

Git as version control system can handle symlinks.

If the symlink points to a file, then Git stores the path information it is symlinking to, and the file type. This is similar to a symlink to a directory; Git does not store the contents under the symlinked directory.

49. Git series

• Introduction into Git

• Hosting Git repositories at Github, Bitbucket or on your own server

• Typical workflows with Git

• EGit - Teamprovider for Eclipse

50. Get the Book

51. Support free vogella tutorials

Please consider a contribution if this article helped you.

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

52. Links and Literature