.. highlight:: bash

===============

Version Control

===============

Introduction

============

Version control is just a way to track your files over time and share them.

This allows you to go back to older versions when something goes wrong, see

what changed when and why, collaborate on a single piece of work with a bunch

of people. 

Like this

`blog <http://karlagius.com/2009/01/09/version-control-for-the-masses/>`_

aptly points out, "Version control is one of those weird, geeky things that

never really gained much ground in non-geek fields, despite the fact that

it’s blindingly useful." In this course, we are going to see a handful of

such things, which are widely used in the programmer world, but not so much

in the scientific computing world, even when if they would be very useful.

Version control is just a way of backing up your files, before making changes

to it. Most people would have cooked up their own version control system,

without realizing, there are tools built by others, which make this task much

more organized and systematic. You surely would've saved your files, some

time or the other as ``oldproject.py``, ``latestproject.py`` and so on, or

date-tagging them as ``project-21-01-10.py``, ``project-20-02-10.py`` and so

on. 

It is, in some ways, similar to playing a video game. We generally play games

in stages, saving the game, each time we finish a stage or complete a task.

We continue playing, but we could, if necessary, choose to go back to one of

the saved states and start over. In this manner we could change the state of

the game. 

Why Use Version Control

=======================

We have seen that one of the main motivation to use a version system control

system is the ability to go back to a working version of the file, when

something stops working. Below are a few more advantages of using an

automated version control system.

    - It tracks the history and evolution of a project. It allows you to

      track what changes were made at what point of time, when and by whom. 

    - If you are collaborating, as a team on a project, a version control

      system will make it much easier for you to collaborate. It allows you

      to work simultaneously on the same file, without worrying about merging

      your changes. 

    - A good version control system will help you efficiently track down bugs

      and pin-point the changes that introduced the bug, reducing your

      debugging time. 

Version control is as useful for a one man show, as it is for a big group of

people working on a project. As a student, you can use it to maintain your

course work, too. You could maintain a version controlled repository with all

your code, assignments, and other documents. Keeping your stuff version

controlled will help avoid accidental deletion of individual files etc.

Hosting it on a remote server will protect you from a local hard disk crash. 

Mercurial

=========

Some of Version Control Tools available and used widely are:

  - ``cvs`` (Concurrent Versions System)

  - ``svn`` (Subversion)

  - ``hg`` (Mercurial)

  - ``git`` 

Each of these tools have some unique functionality and their own merits and

de-merits. In this course, we shall learn to use Mercurial or ``hg``.

Once you know how to use ``hg``, you could easily try other tools and switch

to one that you feel most comfortable with.

Why ``hg`` ?

------------

   - easy to learn and use.

   - lightweight.

   - scales excellently.

   - based on Python.

Installation

------------

- For Linux based systems, hg is available in most of package management. So

  for say Ubuntu systems::

   $ sudo apt-get install mercurial

  will be all you need to install hg. Similarly Fedora users can use yum to

  install hg.

- For Windows and Mac OS X systems the setup can be downloaded from

  http://mercurial.selenic.com/downloads/ and standard installation can be

  followed.

Just say ``hg`` in your shell, to see some of the commands that ``hg``

provides and say ``hg version`` to see the version of ``hg`` that has

been installed on your system. 

Let there be a Repository

=========================

To start using Mercurial (or ``hg``) and get the benefits of using a version

control system, we should first have a **repository**. A repository is a

folder with all your files and a store of all the changes that were made to

it. To save disk space, ``hg`` doesn't save all the files, but only saves

only a series of changes made to the files.

We have talked of an example of how we cook up our own version control

systems. Mercurial does almost the same thing with one major difference. It

doesn't keep track of individual files. It keeps snapshots of the whole

directory (or repository), instead of individual files.

A repository can either be started using an ``init`` command or an existing

repository could be **cloned**.

Let us look at creating our own repository, now. We can look at obtaining

already existing repositories, at a later stage.

Let's say we have a folder called ``book``, which has all the chapters of a

book as text files. Let us convert that folder, into a ``hg`` repository.

::

    $ cd book/

    $ ls -a

    . .. chapter1.txt chapter2.txt chapter3.txt 

We have three chapters in the folder. We convert this folder into a mercurial

repository using the ``hg init`` command

::

    $ hg init

    $ ls -a

    . .. .hg chapter1.txt chapter2.txt chapter3.txt 

The ``.hg`` directory indicates that our book directory is now a ``hg``

repository. Mercurial keeps all the history of the changes made, and a few

other config files, etc. in this directory. The directory, ``book`` is called

our **working directory**. 

Adding Files

------------

We now have a fresh repository, but all our files are not being tracked or

watched by ``mercurial``, yet. We need to explicitly ask it to watch the

files, that we want it to.

To see this use the ``hg status`` command. 

::

    $ hg status

    ? chapter1.txt

    ? chapter2.txt

    ? chapter3.txt

We see the three files for the chapters, but they are preceded by a ``?``

mark. What does it mean?

We use the ``help`` command to see what this means. 

::

    $ hg help status 

    ...

    The codes used to show the status of files are:

      M = modified

      A = added

      R = removed

      C = clean

      ! = missing (deleted by non-hg command, but still tracked)

      ? = not tracked

      I = ignored

        = origin of the previous file listed as A (added)        

    ...

By looking at the codes, it is clear that our files are not *yet* being

tracked by ``hg``. We now use the add command to ask ``hg`` to track these

files.

The ``status`` command gives the *status* of our working-directory at this

point in time. Using this command after every ``hg`` command you use, is a

good idea, at least until you are reasonably comfortable with the use of

``hg``.

::

    $ hg add

    adding chapter1.txt

    adding chapter2.txt

    adding chapter3.txt

    $ hg status

    A chapter1.txt

    A chapter2.txt

    A chapter3.txt

This simply adds all the files in the (working) directory, to the repository.

As expected, the ``status`` command shows an ``A`` before he file names. We

could also specify files individually, for example

::

    $ hg add chapter1.txt

    adding chapter1.txt

*Note*: If you have deleted files, ``hg status`` will show you the status

 code ``!``. You can then, tell ``hg`` to stop tracking these files, using

 the ``hg remove`` command. Look at ``hg help remove`` for more details. 

Taking Snapshots

----------------

We have added a set of new files to the repository, but we haven't told

mercurial to remember these changes, i.e., to take a snapshot at this point

in time. We do this by using the ``commit`` command.

::

    $ hg commit 

We are now prompted with a new editor window. We type out our message here

describing the changes that we have made.

::

    Initial Commit

    HG: Enter commit message.  Lines beginning with 'HG:' are removed.

    HG: Leave message empty to abort commit.

Mercurial has now taken a snapshot of our repository and has attached our

description along with it. To see the status of the files in the repository,

use the ``hg status`` command. 

::

    $ hg st

The command does not return anything, when there are no uncommitted changes.

Also, notice that I have started getting lazy and used only a short name

``st`` for the status command. Mercurial accepts short names, as long as they

can be disambiguated (just like tab completion).

Snapshot's Thumbnail views

--------------------------

To see the history of the changes to our repository, we use ``hg log``. We

can view the change that we just made to our repository.

::

    $ hg log

    changeset:   0:cbf6e2a375b4

    tag:         tip

    user:        punchagan@shrike.aero.iitb.ac.in

    date:        Fri Jan 28 14:04:07 2011 +0530

    summary:     Initial Commit

As we already discussed, mercurial keeps track of the changes that are made

to the files in the repository. Notice, that our ``log`` is showing a

**changeset**. A change set is nothing but a set of changes made to the

repository between two consecutive commits (the action of taking snapshots).

Notice that ``hg`` also shows the date at which the commit was made and the

description of the changeset.

User information

----------------

But there is a slight problem with the user details that mercurial is saving.

It saves my username with my machine name. It is a general good practice to

use your full name with your email id. We set our username in the ``.hgrc``

file in our Home folder. (``$HOME/.hgrc`` on Unix like systems and

``%HOME%\.hgrc`` on Windows systems) This is a global setting for all the

projects that we are working on. We could also set the details, at a

repository level. We shall look at this in due course. 

We open the file in our favorite editor and add the username details. 

::

    $ emacs ~/.hgrc  

    [ui]

    username = Puneeth Chaganti <punchagan@fossee.in>

We have now set the username details for mercurial to use, in all our future

commits. (Note: You can also set user preferences at the repository level.

Exercise-N asks you to do that)

Let us now make another commit to see if this has taken effect. Let us

add author information to all the chapters that we have. 

::

    Author: Puneeth Chaganti <punchagan@fossee.in>

Once we have added this to all the files, let us commit this change. We again

used the ``hg commit`` command to commit the changes that we have made.

::

    $ hg commit

We are again prompted with the editor window to enter our commit message and

we type out our commit message. There are some good practices when typing out

a commit message too. It is a general practice to have a summary line in the

commit message which is no longer than 60 to 65 characters giving a summary

of the change we have made. This is followed up with an explanation of why

this was changed, what is the effect of this change, known bugs/issues

remaining, if any, etc.

::

    Add author info to all the chapters

    All the chapters must have an author info. Added Puneeth Chaganti

    as the author. New authors can be added in newlines.              

    HG: Enter commit message.  Lines beginning with 'HG:' are removed.

    HG: Leave message empty to abort commit.

``hg log`` should now show us both the changes that we have made. Notice that

the username settings are being used and also, the summary of the changeset

shows only the first line in the description that we have added. Also, notice

that ``hg`` shows the commits in the reverse chronological order, which is

useful.

But why commit?

===============

You must already be wondering, why we need all the overhead of

``commit`` and ``log``, etc. What is all this fuss about? "Isn't it

just a waste of time?"

Reverting Changes

-----------------

While you were wondering, let's say your friend walks in and together you

make a lot of changes.

1. You replace all the occurrences of ``&`` in ``chapter1.txt`` with

``and``. 

2. You delete the ``chapter3.txt`` file. 

::

    $ rm chapter3.txt

    $ hg st

    M chapter1.txt

    ! chapter3.txt

But after a while, you realize that these changes are unwarranted. You

want to go back to the previous state, undoing all the changes that

you made, after your friend arrived. 

The undo in your editor may allow undoing the first change (if you

haven't closed it after making the changes) but there's no way you

could get back your ``chapter3.txt`` file, using your editor. But

don't worry. Mercurial to the rescue!

We shall use the ``revert`` command of ``hg`` to undo all the changes

after the last commit. As we want to undo all the changes, we use the

``revert`` command with the ``--all`` argument. 

::

    $ hg revert --all

    reverting chapter1.txt

    reverting chapter3.txt

    $ hg st

    ? chapter1.txt.orig

    $ ls

    chapter1.txt  chapter1.txt.orig  chapter2.txt  chapter3.txt

As you can see the ``chapter3.txt`` file has been restored. But ``hg``

gives you a new file ``chapter1.txt.orig``. Mercurial actually doesn't

like to delete any of the changes that you have made. So, it makes a

back-up of the file ``chapter1.txt`` in the present state and gives

you back the old file. 

If we now decide, that we want to ``redo`` the changes that we had

done to the ``chapter1``, we can just overwrite the ``chapter1.txt``

file with the backed up file. 

::

    $ mv chapter1.txt.orig chapter1.txt

    $ hg st

    M chapter1.txt

Viewing Changes

---------------

Let's say we now want to ``commit`` these changes, but we are not sure

of all the changes that we have made to the file, since it's been a

while after we made the changes. We could use the ``diff`` command to

see all the changes that have been made in the file. 

::

    $ hg diff

    diff -r 3163b8db10bb chapter1.txt

    --- a/chapter1.txt	Fri Jan 28 16:21:29 2011 +0530

    +++ b/chapter1.txt	Fri Jan 28 16:22:41 2011 +0530

    @@ -8,9 +8,9 @@

       1 Session

     Table of Contents

     =================

    -1 Introduction & Motivation 

    -2 Creating & Getting repositories 

    +1 Introduction and Motivation 

    +2 Creating and Getting repositories 

     3 Revision history 

    -4 Making & sharing changes 

    -5 Merges & Conflicts 

    +4 Making and sharing changes 

    +5 Merges and Conflicts 

You see some cryptic output, but it's essentially giving you the list

of changes made to the file. All the lines that were deleted are

preceded by a ``-`` and all the new-lines are preceded by a ``+``. You

can see that the ``&`` occurrences have been replaces with ``and``. 

We should note here that, the ``diff`` wouldn't make much sense, if we had

some binary files like ``.jpg`` or ``.pdf`` files. We would see some

gibberish in the output. 

Let us now commit this change. 

::

    $ hg commit

    Replace all occurrences of & with and

    On the suggestion of Madhusudan C S. 

    HG: Enter commit message.  Lines beginning with 'HG:' are removed.

    HG: Leave message empty to abort commit.

::

    $ hg log    

We can see the history of all the commits that we have made in our

project. As you can see, the logs have started getting longer (and

hence have been dropped from the output) and may even be getting out

of our screens. Also, we are not very interested in all the commits in

the project. We usually want to see the last few commits. 

Revision Numbering

------------------

Let us now see how to get logs of specific commits and a range of

commits. Have a look at the logs that the previous ``log`` command has

printed and look at the ``changeset`` line. It shows a number followed

by a semi-colon and some long hexa-decimal string. The number is

called the **revision number**. It is an identifier for the commit,

and can be along with various commands to specify the revision number,

if required. 

Let us now check the logs of the very first commit of the project.

::

    $ hg log -r0

    changeset:   0:cbf6e2a375b4

    tag:         tip

    user:        punchagan@shrike.aero.iitb.ac.in

    date:        Fri Jan 28 14:04:07 2011 +0530

    summary:     Initial Commit

Now, if we wish to get the logs of the latest commit only, how do we

do it? We could specify the exact revision number of the commit (2) or

just use -1 to start counting in the reverse chronological order. 

::

    $ hg log -r-1