Using Git

The aim of this document is to explain the main useful features and commands of the SCM (aka Source Control Manager) called Git. For each command, only a few options will be explained. To learn more about a specific command, you may use:

$ git help [<command>]

If you want to get help for a specific command, you may give it after the help keyword. For example, if you want help for the git init command, you will type : git help init. Documentation, tutorials, … are also available on the Git website:

http://git-scm.com/

The Git cheatsheet

Configuring Git

With commands

When you use Git for the first time, you have to set your name and your email. This will be used when registering changes.

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

If you have to use patches management by email, you also will have to define some information about your email address.

$ git config --global sendemail.smtpserver <smtp.example.com>
$ git config --global sendemail.smtpserverport 465
$ git config --global sendemail.smtpencryption tls
$ git config --global sendemail.smtpuser <your-id>
$ git config --global sendemail.smtppass <your-passwd>

With file edition

There is another way to define those global parameters, namely define directly the ~/.gitconfig file. The previous commands edit this file and the result is:

[user]
  name = Your Name
  email = your.email@example.com
[sendemail]
  smtpserver = smtp.example.com
  smtpuser = <your-id>
  smtppass = <your-passwd>
  smtpserverport = 465
  smtpencryption = tls

For instance, with an email from Gmail:

[user]
  name = Your Name
  email = <your-id>@gmail.com
[sendemail]
  smtpserver = smtp.gmail.com
  smtpuser = <your-id>@gmail.com
  smtppass = <your-passwd>
  smtpserverport = 587
  smtpencryption = ssl

Create a repository

Create an empty repository

To create an empty git repository, you may go to the root directory of your project and use the following command:

$ git init [--bare]

This creates a directory named .git in your root directory, called GIT DIR hereafter. The GIT DIR contains your config for the project and in a zipped way, the list of commits and tracked files. There is a useful option you may use, --bare, in order to create a bare repository, which consist of just the GIT DIR. This option is very useful when you want to have a main repository to which every project member is synchronized, and to spare memory.

Clone a distant repository

When you clone a distant repository, you create a repository connected to the distant one, getting all tracked files, the history of commits and everything you need to work in the project. To do so, you will use the following command:

$ git clone [--bare] <repository-url>

Now, the distant repository is your remote called origin, namely the repository with whom you are connected. For XLiFE++, you can go to the sources tab on the forge website.

Browse a repository

Files changed in working directory

To know the list of modified files, deleted ones or created ones, you can use the following command:

$ git status

For instance, if you added two files toto.txt and tata.txt, the git status output will be:

On branch main
Untracked files :
  (use "git add <file>..." to include in what will be committed)

      tata.txt
      toto.txt

nothing added to commit but untracked files present (use "git add" to track)

If you didn’t have any modification, the git status output should have been:

On branch main
nothing to commit (working directory clean)

Changes to tracked files

To know the list of changes in tracked files, you can use the following command:

$ git diff [<id1> <id2>] [<file>]

Without any arguments, the git diff command gives every change in every file since the last commit. If you specify a file, then only changes of this file will be shown. If you specify 2 commits id, then changes between the two commits will be shown.

Who change what in a file?

To know who changed what in a file, in order to know who is to blame for the bug you have ;-), you can use the following command:

$ git blame <file>

Manage branches

What makes git very powerful is the management of development branches. A branch is a state of your project in the source control. With Git, you can have very easily different states of your project.

Create another branch

To create a branch based on the HEAD, namely the current state of your project in git, you can use the following command:

$ git branch <name>

Display all branches names

To know the name of each local branch in your project, you can use the following command:

$ git branch [-r]

With the -r, you will have branches on the remote repository instead.

Switch to another branch

To switch to another branch, you may use the following command:

$ git checkout <branch-name>

Caution

You may be aware that uncommitted changes do not belong to a branch. So, be aware of what you are doing when you switch to another branch.

Delete a branch

To delete branch, you may use the following command:

$ git branch -d <branch-name>

All changes made in the branch will be now in the current branch. If you want to delete a branch and all commits in it, you may use:

$ git branch -D <branch-name>

In both cases, make sure you are in another branch than the one you want to delete.

Merge a branch in the current one

To merge a branch in the current one, you may use the following command:

$ git merge <branch-name>

Update a repository

Pull the latest changes in distant repository

To get updates from the remote origin, you can use the following command:

$ git pull

Apply a patch someone sent you

When you receive a patch, by email, you may place it in a particular mailbox – for example patch.mbox – and then use the following command to apply it:

$ git am -3 patch.mbox

The -3 option tells to merge each patch. In case of conflicts, you will have to resolve them manually and apply the following command to achieve the patch application:

$ git am --resolved

Publish in a repository

Commit all changes

To commit all changes you made since the last commit (or since the creation of the repository), you can use the following command:

$ git commit -a [-m <msg>]

You can specify the commit message with the -m option, followed by the string, between quotes, representing the message.

Push changes to distant repository

We saw that git pull is used to get changes from a distant repository. To set our commits to the remote repository, you can use the following command:

$ git push

There is some control mechanism behind the push. Indeed, if there are updates on the remote repository you didn’t pull, the push will not work and will warn you to pull before pushing, to prevent time conflicts. If you generate conflicts, the push will not protect the remote repository insofar as you have no access to it and resolve conflicts. That is why it is often said that pushing commits may be risky.

Manage patches

A safer way to publish changes than pushing is sending a patch. To build a patch from commits, you may use the following command:

$ git format-patch origin [--numbered-files] [-o <dir>]

The patch will contain every commit done since the last pull. In case there are several commits to patch, one file per commit will be generated. Their extension will be .patch. The name of the file will be based on a number and the first line of the commit message. If you use the –numbered-files option, the name will only be based on a number. By default, generated files are in the current working directory. If you want to have them in a particular directory, you may use the -o option.

Your patch is ready, and now, you want to send it to other developers. For that purpose, you can use the following command:

$ git send-email *.patch

It will ask you who to send, who sends the mail, … and send it.

Reverting a repository

Amend the last commit

Instead of creating a new commit, you may fix the last one. For this purpose, you will use the --amend option of the command git commit:

$ git commit -a --amend [-m <msg>]

Undo changes since the last commit

You are in a state where all the changes done since the last commit must be undone. To do so, you may use the following command:

$ git reset --hard

If you omit the --hard option, all commits will be deleted, but files will not be modified.

Undo commits

Undoing a commit generates a new commit which is the inverse of the commit undone. That is why the command dedicated to undo commit is git revert:

$ git revert <commit>

For example, if you want to revert the commit HEAD, you create a new commit undoing it.