Git Introduction

Developing and maintaining patches on top of Qt with Git

This document is a simple guide showing the procedures necessary to develop and maintain patches on top of Qt. It is not a replacement for the Git manual.

Setting up for Git and Gerrit

Setting up Gerrit explains how to configure git, and how to clone Qt repositories.

Getting the Qt source code

This section shows how to download the source code and explains the concept of a Git repository.

This creates a new directory called “qt” and downloads the source code into it. It also downloads the entire history of all files in all versions, therefore creating an identical copy – called repository – of what is stored on the server. That is why the process is called cloning. The source of the clone is remembered as the “origin”.

You can create new clones simply by copying the directory, for example onto a USB stick. The new directory will be self-contained, too.

Now that you have all the changes inside the repository, you can work 100% offline. An internet connection is necessary only when you need to fetch new source code changes or push upstream.

Inspecting the source code

This section introduces the Git log, show and blame commands to find out the history of the project.

Run the log command to view recent changes:

This command launches a pager program allowing you to scroll through the list of committed changes with the cursor and Page Up/Down keys. To return to the shell press the ‘q’ key.

The log command accepts options, such as -n to limit the number of changes. For example to list the last three changes run:

To limit the output of the log command, e.g., to show only changes that affect one or multiple files/directories, you can use the following options:

There are various ways of limiting the output of the log command, beyond the ones described here. Refer to git log’s documentation [kernel.org] or more details, particularly the “Commit Limiting” section.

Changes in Git are identified with a unique SHA1 checksum. The checksum is on the first line of the git log output. For example:

You can inspect commits using the git show command with the commit id as argument. The following command shows the entire change above including a diff:

To see the last commit you made use show without any arguments:

To inspect a whole series of commits, use:

The git show and log commands allow you to inspect the history of the project or individual files. Sometimes it is also useful to inspect source code on a line-by-line basis, for example when you would like to find out who introduced a certain snippet of code. Git provides this functionality with the blame command:

The output of this command – shown in a pager – is split into columns. The first column shows the commit id, followed by the author and date for each line.

Git specializes in tracking the content of files, the name of a file is less important than the source code it contains. Therefore git blame can automatically detect, for example, that a function was moved from one file to another.

Making changes

Setting up for changes

The previous sections explained how to clone the repository and how to find out the history of the project. This section finally shows how to create history, through the recording of changes in new commits and the tracking of commits in branches.

The first step is to identify on what branch of development we are working. In Git, branches are a very lightweight concept that allows identifying commits by name. Each commit has a reference to its parent commit(s), which forms the history. The Git branch command, without any arguments, displays the list of local branches as well as the branch currently checked out:

The output shows that we have only one local branch called “master” and the “*” indicates that it is the current branch. The name “master” in Git development usually describes the main line of development.

Besides your local branches Git also remembers the branches in the origin repository. The “-r” option shows them, prefixed with “origin”:

For the purpose of developing a new feature we can create a new branch with the same command:

The “my-feature” branch is based on the origin’s “master” branch, now visible in the list of branches:

The git checkout command can also change the current branch:

This will also update the files in your working directory to match the latest commit in the new current branch. New commits will be recorded in “my-feature” instead of the previous “master” branch.

You can have as many local branches as you like, they are very cheap. Each branch uses only few bytes of disk space. Please see the documentation of the git branch command [git-scm.com] for instructions on how to delete branches.

Actually making the changes

Now we can go ahead and start making changes:

The diff command shows us what we have changed:

The status command gives an overview of what “git commit” would do:

Following the recommendation in the output we mark qstring.cpp and .h as files to be included in the next commit:

And finally we create a new commit:

Normally Git will open a new text editor if you omit the -m parameter.

Marking files to be included in commits means adding them to Git’s staging area. The staging area is a powerful concept, making it easy to work on multiple files simultaenously while still creating small incremental commits.

Use the

git gui

command for a comfortable way to create highly selective commits.

Common operations and fixing mistakes

This section gives recipes for fixing common mistakes and explains common operations such as reviewing your changes before committing using the diff command.

You can undo changes to a file before it is committed with the checkout command:

If you have accidentially marked a file for the next commit you can reset it like this:

This will exclude the file from the next commit and leave it in your working directory unchanged with your modifications intact.

After changing a file the git diff command shows the lines you have modified. The difference is calculated from the file in your working directory and the file when it was added to the staging area using git add.

If you want to show the difference between the file in the staging area and the last commit you have to pass an option to the diff command:

The diff command optionally takes directories and files as argument, to limit the output.

Files are renamed in Git by renaming them in your working directory using a command/tool of your choice. Once you’ve renamed a file you have to tell Git:

Alternatively you can use the convenience mv command:

One of Git’s strengths is that it does not care how exactly you change your files. It is optimized to find out what changed after the fact. For example when copying a file in your source code it is enough to simply run “git add” with the new file. Git automatically finds out where the file was copied from.

Sending and updating your changes

After studying the previous chapters you should be able to develop small changes by creating commits in your local branches. This chapter guides you through the steps of combining your changes with the latest changes from the upstream repository and explains how to create separate patch files for submission into the project.

Obtaining updates

While developing code in your local clone of the project, the original repository evolves and sees new changes. First we update our mirror of the commits in the original repository using the fetch command:

The output indicates that the “master” branch in the original gitorious.org repository has been updated with new commits and these commits are now available in the locally mirrored origin/master branch.

You can inspect the new changes using the log or show commands:

The log command will include the diffs of the individual commits if you specify the -p argument.

Updating your branch with the downloaded, new changes

To combine the new changes with our own local commits we use a technique called rebasing:

After making “my-feature” the current branch, git rebase will first re-initialize the branch to be identical to origin/master, which includes the new commits. Then it will apply each of your commits, basing them on top of the newly initialized branch.

Sending your feature for review

When you decide that the work in your “my-feature” branch is complete then the next step is to make your changes available for upstream inclusion.

This is described in the Gerrit Introduction.

Conclusion

We hope that this introductions helps you familiarize yourself with the use of Git. The official
Git documentation web page [git-scm.com] is a very good continuation point.