restructuring and renaming files/directories with underscores instead of spaces & '-'

5 files changed, 1314 insertions, 0 deletions

diff --git a/lecture_notes/vcs/exercises.rst b/lecture_notes/vcs/exercises.rst
new file mode 100644
index 0000000..de55478
--- /dev/null
+++ b/lecture_notes/vcs/exercises.rst
@@ -0,0 +1,59 @@
+Exercises
+=========
+
+1. ``clone`` the repository from http://fossee.in:9000 into a directory
+   called sees. You should see a folder ``punchagan`` with a lone directory
+   ``01-mercurial`` inside that. The ``log`` should show you the lone commit
+   of the repository. 
+
+#. The next step is to create a folder for yourself inside the repository.
+   The idea is to create a central repository for the course, where every
+   participants files are put in his own folder (within a chapter
+   sub-folder). You are expected to commit future class-work to this
+   repository. 
+
+   Before beginning this exercise, set your username in you global ``hgrc`` 
+
+#. Create a new sub-folder (at the same level as ``punchagan`` with your
+   name.) Add ``01-mercurial`` as a sub-folder to it. Copy the
+   ``questions.txt`` from ``punchagan/01-mercurial`` to
+   ``<your-name>/01-mercurial``. Now, commit your changes with a meaningful
+   commit message and ``push`` . If ``push`` fails, ``pull`` , ``merge``,
+   ``commit`` and then ``push``.
+
+#. Pull from the repo. Update. Use ``hg log`` to see the log history of the
+   repository.
+
+#. Answer the questions in ``questions.txt``. Commit your changes with a
+   meaningful commit message and push them. (If required, ``pull`` ,
+   ``merge``, ``commit`` and then ``push``)
+
+#. Wait for your neighbor to finish making his/her changes. Help him/her if
+   required. Once both of you are ready, pull changes from the repository and
+   update. 
+
+   Now, add one question each, at the bottom of your own ``questions.txt``
+   file and your neighbor's file. Preferably, the questions should be about
+   ``hg`` , but you may, let your creativity run wild. ;) Commit the changes
+   and push them. Resolve merge conflicts, as required.
+
+#. Answer the new questions that were added by your neighbor, both to his/her
+   file and your file. Commit changes. Push.
+
+#. Edit the file ``people.txt`` in ``punchagan/01-mercurial`` . Add your
+   name, followed by a colon, followed by a comma separated list of your
+   interests. Commit your changes and push.
+
+#. Edit the file ``story.txt`` in the folder ``punchagan/01-mercurial`` and
+   add one sentence at the end of the present story. Commit your changes and
+   push them. Wait until at least 3 other people change the file, before you
+   make your next change. This can continue for as long as you like. ;)
+
+.. 
+   Local Variables:
+   mode: rst
+   indent-tabs-mode: nil
+   sentence-end-double-space: nil
+   fill-column: 77
+   End:
+
diff --git a/lecture_notes/vcs/handout.rst b/lecture_notes/vcs/handout.rst
new file mode 100644
index 0000000..6ee0317
--- /dev/null
+++ b/lecture_notes/vcs/handout.rst
@@ -0,0 +1,1208 @@
+.. highlight:: console
+
+===============
+Version Control
+===============
+
+At the end of this session, you will be able to:
+
+-  Understand what Version Control is, and the need for it
+-  Create and use repository on a daily basis
+-  Clone existing repositories, from the web
+-  View the history of a repository
+-  Make changes to a repository and commit them
+-  Work collaboratively with a team
+
+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. 
+
+In this section, we have seen 
+
+  - the motivation to use version control
+  - an analogy of version control with playing a video game
+  - how to check if mercurial is installed, and it's version using ``hg
+    version`` 
+
+Let there be a Repository
+=========================
+
+At the end of this section, you will be able to - 
+
+  - initialize a new repository,
+  - obtain the status of a repository,
+  - add new files to a repository,
+  - take snapshots of a repository,
+  - view the history of a repository, 
+  - and set your user information for ``hg`` 
+
+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 -u "Puneeth Chaganti <punchagan@fossee.in>" -m "Initial Commit."
+
+The ``-u`` parameter allows us to specify the user details. It is a general
+good practice to use full name followed by the email id. The ``-m`` parameter
+allows us to give the commit message --- a message describing the changes
+that are being committed.
+
+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:        Puneeth Chaganti <punchagan@fossee.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 are two things, that can be changed. Firstly, it is unnecessary to
+keep typing the user information each and every time we make a commit.
+Secondly, it is not very convenient to enter a multi-line commit message from
+the terminal. To solve these problems, we set our user details and editor
+preferences in the ``.hgrc`` file in our home folder. (``$HOME/.hgrc`` on
+Unix like systems and ``%USERPROFILE%\.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 and our
+editor preferences. 
+
+::
+
+    $ emacs ~/.hgrc  
+    [ui]
+    username = Puneeth Chaganti <punchagan@fossee.in>
+    editor = emacs
+
+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
+
+
+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 now prompted with a window of our favorite editor. We can now type out
+our commit message in the editor window. 
+
+There are some recommended practices for commit messages, 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 committed.
+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.
+
+In this section, we have learn to - 
+
+  - initialize a new repository using ``hg init``, 
+  - get the status of a repository using ``hg status``,
+  - make sense out of the various status codes in the output of ``hg
+    status``,
+  - use the ``hg help`` to get help about any ``hg`` command, 
+  - make commits of changes to files, using ``hg commit`` 
+  - view the history of the repository using the ``hg log`` command,
+  - and, set our user information in the global ``hgrc`` file. 
+
+But why commit?
+===============
+
+At the end of this section, you will be able to - 
+
+  - undo changes to your repository,
+  - view the differences between any two states of a repository,
+  - understand how revisions are numbered and use it as arguments to
+    commands, 
+
+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. This gives us a brief description of all the changes made, by
+showing us the summary line of all the commits. What if we want to get more
+details? 
+
+We can pass an additional argument, ``-v`` or ``--verbose``,  to ``hg log``
+to get the whole commit message, instead of just the summary. 
+
+::
+
+    $ hg log -v
+
+As you can see, the logs have started getting longer (and hence have been
+dropped from the output) and getting out of our screen. Also, we are not
+always, interested to see the whole history of the project. It would often
+suffice to see the last few commits. 
+
+To limit the output of ``hg log``, we could use the ``-l`` or ``--limit``
+argument 
+::
+
+    $ hg log -v -l3
+
+This will give us log of only the last three commits and not the whole
+history of the project. 
+
+Revision Numbering
+------------------
+
+Often, the level of detail provided by the commit messages is also not
+enough. We would want to see what *exactly* changed with a commit, probably
+as a ``diff``. We could do that using **revision numbers**.
+
+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's say we wish to see the changes between revision 1 and revision 2. We
+shall use the ``diff`` command to do this. 
+::
+
+    $ hg diff -r1 -r2
+
+The diff command takes two revision numbers as arguments and gives the
+changes made from revision in the first argument to revision in the second
+argument. 
+::
+
+    $ hg diff -r0 -r2
+
+The above command will show all the changes made after revision 0 up to
+revision 2. 
+
+The revision number can also be passed as an argument to many other commands.
+For instance, we can check the logs of the very first commit, by saying 
+::
+
+    $ 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
+
+You could also specify a range of commits whose logs you would like to
+see. Say, we would like to see the last two commits, 
+::
+
+    $ hg log -r0:2
+
+You could also see the changes made to a particular file, in the
+specified range of the commits. Say, we wish to see the changes made
+to the ``chapter2.txt`` file in the last two commits. 
+::
+
+    $ hg log -r0:2 chapter2.txt
+    changeset:   1:3163b8db10bb
+    user:        Puneeth Chaganti <punchagan@fossee.in>
+    date:        Fri Jan 28 16:21:29 2011 +0530
+    summary:     Add author info to all the chapters
+
+Notice that it shows only the logs of revision 1, since no changes
+were made to the specified file in the second commit. 
+
+In this section, we have learnt to -
+
+  - undo changes to the repository using ``hg revert``,
+  - view changes done to the repository using ``hg diff`` 
+  - use revision numbers as arguments to different ``hg`` commands
+
+Collaborating with Mercurial
+============================
+
+At the end of this section, you will be able to - 
+
+  - clone existing repositories,
+  - share your repositories with peers, 
+  - use version control for collaborating with your peers,
+
+When motivating the use of version control systems, we spoke a lot about
+collaboration and sharing our changes with our peers. Let us now see how we
+can share our project with our peers and collaborate with them. 
+
+Cloning Repositories
+--------------------
+
+For this purpose let us create a central repository, a copy of our
+repository, which is different from the one in which we are working. The
+``clone`` command is used to **clone** or replicate an existing repository.
+
+::
+
+    $ hg clone book book-repo
+
+This creates a copy of our repository, ``book``, with the name ``book-repo``.
+The syntax of the ``clone`` command is -- ``hg clone SOURCE [DEST]``, where
+the optional argument DEST is being represented in brackets. Here we are
+giving book-repo as the destination. 
+
+The clone command can be used to replicate already existing repositories,
+either on your own machine or on some remote machine somewhere on the
+network. Since, ``hg`` maintains a copy of the full repository with every
+copy of the repository, the two copies that we have are exactly equivalent.
+
+``book-repo`` is the repository we shall be using as a central repository
+and share it with our peers. 
+
+Sharing Repositories
+--------------------
+
+A mercurial repository can be shared in multiple ways. We shall use the
+``http`` protocol to share the repository. Mercurial comes inbuilt with a
+tiny server that can be used to share your repository over the network. To
+start sharing the repository, we say 
+
+::
+
+    $ cd ../book-repo
+    $ hg serve 
+
+This will start serving the repository on the network on the port 8000.
+Anybody in your network can access the repository in their browsers. Let us
+see how it looks, in our own browser. We open the url `http://localhost:8000`
+in our browser.     
+
+Let's say, our friend Madhu, now wants  to clone this repository. He will use
+our ip-address and the port on which  we are serving the repository, to clone
+the repository. Instead of using two machines, for the purposes of
+demonstration, we shall clone into our own machine, with a different name. 
+
+::
+
+    $ hg clone http://192.168.1.101:8000 book-madhu
+
+This will clone the repository to the folder, ``book-madhu``. The log of the
+repository will, obviously, be the same as our original repository. 
+
+::
+
+    $ hg log
+
+Sharing Changes
+---------------
+
+Let's say, Madhu now makes some changes to the repository. 
+
+1. He adds his name to the Authors list. 
+2. He moves down the Getting repositories part into a different section.  
+
+::
+
+    $ hg diff
+    diff -r 98f7f4a1bb4d chapter1.txt
+    --- a/chapter1.txt	Fri Jan 28 16:24:42 2011 +0530
+    +++ b/chapter1.txt	Fri Jan 28 23:03:37 2011 +0530
+    @@ -2,6 +2,7 @@
+                            =======================
+     
+     Author: Puneeth Chaganti 
+    +        Madhusudan CS 
+     Date: 2011-01-28 13:58:47 IST
+     
+     
+    @@ -9,8 +10,9 @@
+     Table of Contents
+     =================
+     1 Introduction and Motivation 
+    -2 Creating and Getting repositories 
+    +2 Creating 
+     3 Revision history 
+     4 Making and sharing changes 
+    -5 Merges and Conflicts 
+    +5 Getting repositories 
+    +6 Merges and Conflicts  
+
+He then commits these changes and **pushes** them to the central repository
+that we have created. 
+
+::
+
+    $ hg commit
+    $ hg push
+    pushing to http://192.168.1.101:8000 
+    searching for changes
+    ssl required
+
+The push failed, obviously, since we have not taken care of access rights
+etc. It doesn't make much sense to allow anybody to make changes to a public
+repository, by default. We will need to make changes to the settings of the
+repository to allow this. **Note**: This is obviously not a safe way to share
+your repository, but for our purposes, this is sufficient.
+
+We add the following lines to the ``.hg/hgrc`` of the ``book-repo``
+repository. 
+::
+
+    [web]
+    push_ssl=False
+    allow_push=*
+
+This will allow anybody to push to the repository, now. 
+
+By the way, this ``hgrc`` is a repository level configuration file. We could
+also set the details of the user information in this file. 
+
+Madhusudan can now push and his changes will appear in the central
+repository. 
+
+::
+
+    $ hg push
+    
+Let's confirm it in the web interface that we started with the ``hg serve``
+command. 
+
+Pulling Changes
+---------------
+
+Let us now **pull** these changes into our original repository ``book`` that
+we have been working with. Before pulling the changes, we can use the command
+``hg incoming`` to see the changes that have been made to the repository
+after our last **pull** and the changesets that will be coming into our
+repository after we do a **pull**. 
+
+::
+
+    $ hg incoming
+    abort: repository default not found!
+
+What is going on here? This is because, we didn't clone our repository
+``book`` from the central repository ``book-repo``. We can now add the
+location of the central repository to the ``hgrc`` file, of this project. 
+
+::
+
+    [paths]
+    default = /home/punchagan/book-repo
+
+Now, we can check the incoming changes. 
+
+::
+
+    $ hg incoming
+    searching for changes
+    changeset:   3:3cd54926dbea
+    tag:         tip
+    user:        Madhusudan CS <madhusudancs@fossee.in>
+    date:        Fri Jan 28 23:08:25 2011 +0530
+    summary:     Add myself as author; Move getting repositories to section 5
+
+
+To now **pull** these changes, we use the ``pull`` command. 
+
+::
+
+    $ hg pull 
+    pulling from /home/punchagan/book-repo
+    searching for changes
+    adding changesets
+    adding manifests
+    adding file changes
+    added 1 changesets with 1 changes to 1 files
+    (run 'hg update' to get a working copy)
+
+
+*Note* that ``hg`` is giving us a message, asking us to run a ``hg update``
+ to get a working copy. Let us try to understand what this is. 
+
+As already explained, ``.hg`` folder has all the information about the
+changesets of the repository. When we do a ``pull`` the changesets from the
+remote repository are pulled to our repository, but our working directory is
+not affected by these changes. To see this, we could use the ``hg parent``
+command. 
+
+::
+
+    $ hg parent
+    changeset:   2:98f7f4a1bb4d
+    user:        Puneeth Chaganti <punchagan@fossee.in>
+    date:        Fri Jan 28 16:24:42 2011 +0530
+    summary:     Replace all occurrences of & with and
+
+As we can see, the parent is still our last commit, and the changes made by
+Madhusudan are still not in our working directory. To get these changes we do
+the update as suggested by ``hg``. 
+
+::
+
+    $ hg up
+    1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+    $ hg parent
+    changeset:   3:3cd54926dbea
+    tag:         tip
+    user:        Madhusudan CS <madhusudancs@fossee.in>
+    date:        Fri Jan 28 23:08:25 2011 +0530
+    summary:     Add myself as author; Move getting repositories to section 5
+    
+As expected the **update** command updates the parent to the latest changes
+that we just pulled from the remote repository. 
+
+The update command can also be used to go back into an older revision, by
+specifying the revision to which we want to go to. 
+
+::
+
+    $ hg up -r1
+    1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+    $ hg parent
+    changeset:   1:3163b8db10bb
+    user:        Puneeth Chaganti <punchagan@fossee.in>
+    date:        Fri Jan 28 16:21:29 2011 +0530
+    summary:     Add author info to all the chapters
+    $ hg cat chapter1.txt
+    # Displays the contents of the chapter1.txt file as in revision 1. 
+
+To return to the latest revision we just use the ``up`` or ``update`` command
+without specifying any revision number. 
+
+::
+
+    $ hg up
+    1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+    $ hg parent
+    changeset:   3:3cd54926dbea
+    tag:         tip
+    user:        Madhusudan CS <madhusudancs@fossee.in>
+    date:        Fri Jan 28 23:08:25 2011 +0530
+    summary:     Add myself as author; Move getting repositories to section 5
+
+Simultaneous Changes
+--------------------
+
+Ok, we have been talking about collaboration, but this is a nice situation,
+where I was not changing anything while Madhusudan was changing the file,
+incidentally.  
+
+Now, let's say, both of us are editing the file at the same time, but
+different parts of it.  Say, I change the title of the section 2. 
+::
+
+    $ hg diff
+    diff -r 3cd54926dbea chapter1.txt
+    --- a/chapter1.txt	Fri Jan 28 23:08:25 2011 +0530
+    +++ b/chapter1.txt	Fri Jan 28 23:45:19 2011 +0530
+    @@ -10,7 +10,7 @@
+     Table of Contents
+     =================
+     1 Introduction and Motivation 
+    -2 Creating 
+    +2 Creating repositories
+     3 Revision history 
+     4 Making and sharing changes 
+     5 Getting repositories 
+    $ hg commit 
+    $ hg push
+    pushing to /home/punchagan/book-repo
+    searching for changes
+    adding changesets
+    adding manifests
+    adding file changes
+    added 1 changesets with 1 changes to 1 files
+    
+Also, let us assume Madhusudan adds an additional section called References. 
+::
+
+    $ hg diff
+    diff -r 3cd54926dbea chapter1.txt
+    --- a/chapter1.txt	Fri Jan 28 23:08:25 2011 +0530
+    +++ b/chapter1.txt	Fri Jan 28 23:47:05 2011 +0530
+    @@ -15,4 +15,4 @@
+     4 Making and sharing changes 
+     5 Getting repositories 
+     6 Merges and Conflicts 
+    -
+    +7 References
+    $ hg commit
+    $ hg log
+
+Let us now compare the logs of the two repositories. You can see that both
+the repositories have their topmost revision numbered as 4, but they are both
+different. The identification number given to each revision is a local
+identification. The hexadecimal string following that number is the actual
+unique identification of that changeset, which will be unique across
+repositories.
+
+What happens now, when Madhusudan tries to push his changes to the central
+repository? 
+
+::
+
+    $ hg push
+    pushing to http://192.168.1.101:8000 
+    searching for changes
+    abort: push creates new remote heads!
+    (did you forget to merge? use push -f to force)
+
+
+The push failed! This is because, both of us have made changes, and they need
+to be merged somehow. **Don't**, just for this one instance, take the advice
+given by ``mercurial``. Using the ``-f`` would be disastrous. We will leave
+out a discussion of that, for this course. 
+
+Madhusudan now needs to pull the new changes that have been pushed to the
+repository after his last pull and **merge** them with his changes. 
+
+::
+
+    $ hg pull 
+    pulling from http://192.168.1.101:8000 
+    searching for changes
+    adding changesets
+    adding manifests
+    adding file changes
+    added 1 changesets with 1 changes to 1 files (+1 heads)
+    (run 'hg heads' to see heads, 'hg merge' to merge)
+    $ hg merge
+    merging chapter1.txt
+    0 files updated, 1 files merged, 0 files removed, 0 files unresolved
+    (branch merge, dont forget to commit)
+
+
+We have now pull the changes from the central repository and merged them with
+the changes in our repository. But, ``hg`` is warning us not to forget to
+commit. Let's see what is the status of the repository at this point in time.
+
+::
+
+    $ hg st
+    M chapter1.txt
+    $ hg diff
+    diff -r bd57162c31f6 chapter1.txt
+    --- a/chapter1.txt	Fri Jan 28 23:51:52 2011 +0530
+    +++ b/chapter1.txt	Sat Jan 29 00:00:39 2011 +0530
+    @@ -10,7 +10,7 @@
+     Table of Contents
+     =================
+     1 Introduction and Motivation 
+    -2 Creating 
+    +2 Creating repositories
+     3 Revision history 
+     4 Making and sharing changes 
+     5 Getting repositories 
+
+As you can see, the changes pushed by us, changing the name of the section 2,
+have now been made in the repository of Madhusudan. We will now need to
+commit these changes. 
+
+::
+
+    $ hg commit
+    
+We shall be using a commit message that makes it clear that we are merging.
+We can now push this changes to the central repository. We could also check
+the changes that will be pushed, before pushing them, using the ``hg
+outgoing`` command. 
+::
+
+    $ hg outgoing
+    tag:         tip
+    parent:      5:bd57162c31f6
+    parent:      4:5c88c36f60de
+    user:        Madhusudan CS <madhusudancs@fossee.in>
+    date:        Sat Jan 29 00:02:53 2011 +0530
+    summary:     Merge heads.
+
+    changeset:   5:bd57162c31f6
+    parent:      3:3cd54926dbea
+    user:        Madhusudan CS <madhusudancs@fossee.in>
+    date:        Fri Jan 28 23:51:52 2011 +0530
+    summary:     Add additional References section
+    $ hg push
+    pushing to http://192.168.1.101:8000 
+    searching for changes
+    adding changesets
+    adding manifests
+    adding file changes
+    added 2 changesets with 2 changes to 1 files
+
+The changes have now been successfully pushed! Let us look at the web
+interface of the repo, to see that the changes have actually taken place. Let
+us also have a look at the graph to, try and understand what has happened. 
+
+As we can see, a branch was created, when both of us started editing the file
+simultaneously, and was then merged by Madhusudan CS. 
+
+Simultaneous Conflicting Changes
+--------------------------------
+
+We were lucky this time, in that we were editing separate parts of the file.
+What will happen if we edited the same portion of the file, at the same time?
+How would merges work? This will be the last thing that we are going to see
+in this part of the course. 
+
+Let's say both of us edit the title of the section 6. 
+
+Let's say, I make the following changes, commit them and push them. 
+
+::
+
+    $ hg diff
+    diff -r ce3469a9446f chapter1.txt
+    --- a/chapter1.txt	Sat Jan 29 00:02:53 2011 +0530
+    +++ b/chapter1.txt	Sat Jan 29 10:30:21 2011 +0530
+    @@ -14,5 +14,5 @@
+     3 Revision history 
+     4 Making and sharing changes 
+     5 Getting repositories 
+    -6 Merges and Conflicts 
+    +6 Merging and resolving conflicts 
+     7 References
+    $ hg commit
+    $ hg push
+    ...
+    added 1 changesets with 1 changes to 1 files
+
+Meanwhile, let's say Madhusudan was changing the same section title, as
+follows.      
+
+::
+
+    $ hg diff
+    diff -r ce3469a9446f chapter1.txt
+    --- a/chapter1.txt	Sat Jan 29 00:02:53 2011 +0530
+    +++ b/chapter1.txt	Sat Jan 29 10:35:29 2011 +0530
+    @@ -14,5 +14,5 @@
+     3 Revision history 
+     4 Making and sharing changes 
+     5 Getting repositories 
+    -6 Merges and Conflicts 
+    +6 Simple Merges and Merges with Conflicts 
+     7 References
+    $ hg commit
+    $ hg push
+    pushing to http://192.168.1.101:8000 
+    searching for changes
+    abort: push creates new remote heads!
+    (did you forget to merge? use push -f to force)
+    $ hg pull 
+    ...
+    added 1 changesets with 1 changes to 1 files (+1 heads)
+    (run 'hg heads' to see heads, 'hg merge' to merge)
+    $ hg merge
+    0 files updated, 1 files merged, 0 files removed, 0 files unresolved
+    (branch merge, dont forget to commit)
+
+
+What happens now actually depends on how Mercurial is configured and the
+programs available in your machine. You will either get a diff view with 3
+panes or ``merge`` will insert markers in your file at the points where the
+conflicts occur.
+
+If you get a 3 pane view, the first pane is the actual file, where you make
+changes, to resolve the conflicts. The second pane shows the changes that you
+made, to the file. The last pane shows the changes that you pulled from the
+original repo. Once you are satisfied with the changes, save and quit. 
+
+If you have a very minimal system, you might end up getting a file with
+change markers, the original file being backed up. Open the file and resolve
+the conflicts, deleting the markers. Once you are done, you need to tell
+mercurial that you have resolved the conflicts manually. 
+
+::
+
+    $ hg resolve -m chapter1.txt
+
+Whatever be the process you have used for the merge, you will now need to
+commit your changes, just like the simple merge that we performed. 
+
+::
+
+    $ hg commit -m "Merge heads."
+    $ hg push
+
+We could look at the graph of the changes, in our web interface, being served
+by the ``hg serve`` command. From the graph it is clear, how the merging has
+occurred. 
+
+That brings us to the end of this tutorial on Mercurial. What we have covered
+is nothing close to all the features of Mercurial. We've only scratched the
+surface, but let's hope that this will get you started and you will be able
+to organize your work and projects, better. 
+
+In this section, we have learnt how to - 
+
+- clone repositories, using ``hg clone``, 
+- serve our repositories via ``http`` using ``hg serve``,
+- push changes to a repository using ``hg push``,
+- check the changesets in a repository after last pull, using ``hg
+  incoming``,
+- pull changes from a repository using ``hg pull`` ,
+- update the working directory, using ``hg update``,
+- merge two heads, using ``hg merge``, 
+- and resolve conflicts using ``hg resolve``. 
+
+Additional Reading
+==================
+
+It is strongly recommended that you to go through the following topics, once
+you are comfortable with using Mercurial on a day-to-day basis.
+
+1. ``.hgignore`` 
+#. ``hg rollback`` 
+#. ``hg bisect`` 
+#. ``hg backout`` 
+
+
+References
+==========
+
+    - `A Visual Guide to Version Control <http://betterexplained.com/articles/a-visual-guide-to-version-control/>`_
+    - `Version Control for the Masses <http://karlagius.com/2009/01/09/version-control-for-the-masses/>`_
+    - `(Illustrated) Intro to Distributed Version Control <http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/>`_
+    - `Understanding Mercurial <http://mercurial.selenic.com/wiki/UnderstandingMercurial>`_
+    - `A Tutorial on Using Mercurial <http://mercurial.selenic.com/wiki/Tutorial>`_
+    - `Hg Init: a Mercurial tutorial <http://hginit.com/>`_
+    - `Beginners Guides <http://mercurial.selenic.com/wiki/BeginnersGuides>`_
+    - `Software Carpentry <http://software-carpentry.org/4_0/vc/>`_
+
+
+Appendix A - Definitions
+========================
+
+Definitions of a few commonly used terms. 
+
+Add
+    Begin tracking a file (or a set of files) with Version Control. 
+
+Branch
+    A diverged line of development. 
+
+Changeset
+    An atomic collection of changes to the files in a repository. 
+
+Clone 
+    Creating a copy of an existing repository; New repo is self-contained. 
+
+Commit
+    Taking a snapshot of the changes made in the repository (after the
+    previous snapshot) 
+
+Conflict 
+    Occurs when two changesets have overlapping sections that have been
+    modified.
+
+Head
+    A changeset with no child changesets. 
+
+History
+    Cumulative of all the changesets of a repository. 
+
+Merge 
+    Combining two separate changesets into one merge changeset. 
+
+Repository (repo) 
+    - Loosely speaking, the folder with all the files and a store
+      of the change history.
+    - Strictly speaking, only the ``.hg`` directory that contains the change
+      history. 
+
+Revert
+    Going back to previous committed state of working directory or a file.
+
+Revision
+    A particular changeset. 
+
+Server
+    A machine which serves the repository. 
+
+Tip 
+    Most recently changed head in a repository. 
+
+Update
+    Updating the working directory to a particular revision or to the tip
+    revision. 
+
+Working Directory
+    The directory where all of the files and directories of the project are
+    present. 
+
+.. 
+   Local Variables:
+   mode: rst
+   indent-tabs-mode: nil
+   sentence-end-double-space: nil
+   fill-column: 77
+   End:
+
diff --git a/lecture_notes/vcs/images/folder.png b/lecture_notes/vcs/images/folder.png
new file mode 100644
index 0000000..42d01a2
--- /dev/null
+++ b/lecture_notes/vcs/images/folder.png
diff --git a/lecture_notes/vcs/images/mercurial_logo.png b/lecture_notes/vcs/images/mercurial_logo.png
new file mode 100644
index 0000000..4cd736e
--- /dev/null
+++ b/lecture_notes/vcs/images/mercurial_logo.png
diff --git a/lecture_notes/vcs/module_plan.rst b/lecture_notes/vcs/module_plan.rst
new file mode 100644
index 0000000..6ad7b47
--- /dev/null
+++ b/lecture_notes/vcs/module_plan.rst
@@ -0,0 +1,47 @@
+Version Control
+===============
+
+Module Objectives
+-----------------
+
+After successfully completing this module a participant will be able to: 
+      
+  - Understand use of Version Control tools                            U
+  - Create and use repository for daily use of assignments/projects    Ap
+  - Browse exsiting repo, make changes and commit back                 Ap
+  - Work collaboratively with a team on live project                   Ap
+
+Suggested Reading:
+------------------
+
+"http://mercurial.selenic.com/wiki/Tutorial"
+
+**Initial Session Plan**
+
++---------+-----------------------+----------+
+| Session | Topic                 | Duration |
++---------+-----------------------+----------+
+|       1 | Introduction          | 20 min   |
+|         | - why version control |          |
+|         | - analogy             |          |
+|         | - why hg?             |          |
+|         |                       |          |
+|         | Let there be a repo   | 30 min   |
+|         | - initializing        |          |
+|         | - status              |          |
+|         | - adding files        |          |
+|         | - taking snapshots    |          |
+|         | - log                 |          |
+|         | - setting userinfo    |          |
++---------+-----------------------+----------+
+|       2 | But Why commit?       | 15 min   |
+|         | - reverting changes   |          |
+|         | - viewing changes     |          |
+|         | - revision numbering  |          |
+|         |                       |          |
+|         | Collaborating         | 30 min   |
+|         | - cloning             |          |
+|         | - serving             |          |
+|         | - pushing and pulling |          |
+|         | - merging & conflicts |          |
++---------+-----------------------+----------+