There are various source code control systems; in this tutorial you can learn the basics of Subversion (also called svn source code control systems, and Mercurial (or~ hg ), which is an example of the new generation of code control} systems.

26.1 Workflow in source code control systems

crumb trail: > svn > Workflow in source code control systems

Source code control systems are built around the notion of repository : a central store of the files of a project, together with their whole history. Thus, a repository allows you to share files with multiple people, but also to roll back changes, apply patches to old version, et cetera.

The basic actions on a repository are:

Adding your own changes is not always possible: there are many projects where the developer allows you to check out the repository, but not to incorporate changes. Such a repository is said to be read-only.

Figure~ 26.1 illustrates these actions for the Subversion system.

FIGURE 26.1: Workflow in traditional source code control systems such as Subversion

Users who have checked out the repository can edit files, and check in the new versions with the commit command; to get the changes committed by other users you use update .

One of the uses of committing is that you can roll your code back to an earlier version if you realize you made a mistake or introduced a bug. It also allows you to see the difference between different code version. However, committing many small changes may be confusing to other developers, for instance if they come to rely on something you introduce which you later remove again. For this reason, distributed source code control systems use two levels of repositories.

There is still a top level that is authoritative, but now there is a lower level, typically of local copies, where you can commit your changes and accumulate them until you finally add them to the central repository.

FIGURE 26.2: Workflow in distributed source code control systems such as Mercurial

This also makes it easier to contribute to a read-only repository: you make your local changes, and when you are finished you tell the developer to inspect your changes and pull them into the top level repository. This structure is illustrated in figure~ 26.2 .

26.2 Mercurial (hg) and Git

crumb trail: > svn > Mercurial (hg) and Git

of distributed source code control systems. Many commands are the same as for subversion, but there are some new ones, corresponding to the new level of sophistication. Mercurial and git share some commands, but there are also differences. Git is ultimately more powerful, but mercurial is easier to use at first.

Here is a translation between the two systems: https://github.com/sympy/sympy/wiki/Git-hg-rosetta-stone .

Minimal introduction to git: http://rogerdudler.github.io/git-guide/

This lab should be done two people, to simulate a group of programmers working on a joint project. You can also do this on your own by using two clones of the repository, preferably opening two windows on your computer.

Best practices for distributed version control: https://homes.cs.washington.edu/~mernst/advice/version-control.html

26.3 Create and populate a repository

crumb trail: > svn > Create and populate a repository

First we need to have a repository. In practice, you will often use one that has been previously set up, but there are several ways to set up a repository yourself. There are commercial and free hosting services such as http://bitbucket.org . (Academic users can have more private repositories.)

Let's assume that one student has created a repository your-project on Bitbucket. Both students can then clone it:

or

You now have an empty directory your-project .

\practical{Go into the project directory and see if it is really empty.}{There is a hidden directory .hg or .git }{}

26.4 New files

crumb trail: > svn > New files

Creating an untracked file

One student now makes a file to add to the repository:

(where ^D stands for control-D, which terminates the input.) This file is unknown to hg :

Git is a little more verbose:

Adding the file to the repository

FIGURE 26.3: Add local changes to the remote repository

We need to declare the file as belonging to the repository; a subsequent hg commit command then copies it into the repository.

or

Unlike with Subversion, the file has now only been copied into the local repository, so that you can, for instance, roll back your changes. If you want this file added to the main repository, you need the hg push command:

In the push step you were probably asked for your password. You can prevent that by having some lines in your $HOME/.hgrc file: {\footnotesize

} Now the command hg push projectrepo will push the local changes to the global repository without asking for your password. Of course, now you have a file with a cleartext password, so you should set the permissions of this file correctly.

With git you need to be more explicit, since the ties between your local copy and the `upstream' repository can be more fluid.

FIGURE 26.4: Get changes that were made to the remote repository

The second student now needs to update their repository. Just like the upload took two commands, this pass also takes two. First you do \n{hg pull} to update your local repository. This does not update the local files you have: for that you need to do hg update .

\practical{Do this and check that the contents of the file are correct.}{In order to do the update command, you have to be in a checked-out copy of the repository.}

\practical{Let both students create a new directory with a few files. Declare the directory and commit it. Pull and update to obtain the changes the other mde.}{You can do hg add on the directory, this will also add the files contained in it.}{}

Since you will mostly be doing an update immediately after a pull, you can combine them:

Git will report what files are updated; for Hg you need to take the changeset number and query:

26.5 Editing files

crumb trail: > svn > Editing files

Mercurial and Git differ in their behavior regarding edited files. Both show them as modified, but

26.6 Oops! Undo!

crumb trail: > svn > Oops! Undo!

One of the reasons for having source code control is to be able to revert changes. The easiest undo is to go back to the last stored version in the repository.

26.7 Conflicts

crumb trail: > svn > Conflicts

Now let's see what happens when two people edit the same file. Let both students make an edit to firstfile , but one to the top, the other to the bottom. After one student commits the edit, the other can commit changes, after all, these only affect the local repository. However, trying to push that change gives an error:

The solution is to get the other edit, and commit again. This takes a couple of commands: {\small

}

This may seem complicated, but you see that Mercurial prompts you for what commands to execute, and the workflow is clear, if you refer to figure  26.2 .

\practical{Do a cat on the file that both of you have been editing. You should find that both edits are incorporated. That is the `merge' that Mercurial referred to.}{}{}

If both students make edits on the same part of the file, version control can no longer resolve the conflicts. For instance, let one student insert a line between the first and the second, and let the second student edit the second line. Whoever tries to push second, will get messages like this: {\small

}

For git:

There are now the following options:

Both will give you several options. It is easiest to resolve the conflict with a text editor. If you open the file that has the conflict you'll see something like:

indicating the difference between the local version (`mine') and the other, that is the version that you pulled and tried to merge. You need to edit the file to resolve the conflict.

After this, you tell hg that the conflict was resolved:

or

After this you can commit and push again. The other student then needs to do another update to get the correction.

For conflicts in binary files, git has a flag where you can indicate which version to use:

Not all files can be merged: for binary files Mercurial will ask you:

This means that the only choices are to keep your local version (type  l and hit return) or take the other version (type  o and hit return). In the case of a binary file that was obvious generated automatically, some people argue that they should not be in the repository to begin with.

26.8 Inspecting the history

crumb trail: > svn > Inspecting the history

If you want to know where you cloned a repository from, look in the file .hg/hgrc .

The main sources of information about the repository are hg log and hg id . The latter gives you global information, depending on what option you use. For instance, hg id -n gives the local revision number.

To see differences in various revisions of individual files, use hg diff . First make sure you are up to date. Now do hg diff firstfile . No output, right? Now make an edit in firstfile and do \n{hg diff firstfile} again. This gives you the difference between the last commited version and the working copy.

For example:

Check for yourself what happens when you do a commit but no push, and you issue the above diff command.

You can also ask for differences between committed versions with hg diff -r 4:6 firstfile .

The output of this diff command is a bit cryptic, but you can understand it without too much trouble. There are also fancy GUI implementations of hg for every platform that show you differences in a much nicer way.

If you simply want to see what a file used to look like, do \n{hg cat -r 2 firstfile}. To get a copy of a certain revision of the repository, do hg export -r 3 . ../rev3 , which exports the repository at the current directory (`dot') to the directory ../rev3 .

If you save the output of hg diff , it is possible to apply it with the Unix patch command. This is a quick way to send patches to someone without them needing to check out the repository.

26.9 Branching

crumb trail: > svn > Branching

Create branch:

git checkout -b newbranch

List available:

git branch

After that switch:

git checkout branchname

git push --set-upstream origin newbranch

See what branches there are: hg brances

See what branch you are working on: hg branch

Switch to a branch (this undoes local changes): hg update -C branchname

26.10 Pull requests and forks

crumb trail: > svn > Pull requests and forks

Suppose you want to contribute changes to a repository, but you don't have write permissions on a repository. (Of course, you need to have read permissions to the repository in order to make the changes.) Lack of write permission means that you can not create a branch, and push and merge it. A pull request is then a way to communicate your changes so that they can be pulled, rather than you pushing them.

(the name `upstream' is the conventional name; it is not a keyword.)

To make pull request:

(remember that you didn't have write permission to the original repo!)

26.11 Other issues

crumb trail: > svn > Other issues

26.11.1 Transport

crumb trail: > svn > Other issues > Transport

Mercurial and git can use either ssh or http as transport . With Git you may need to redefine the transport for a push :

You can change the transport with git remote set-url :