diff options
Diffstat (limited to 'lecture_notes/vcs/handout.rst')
| -rw-r--r-- | lecture_notes/vcs/handout.rst | 1208 |
1 files changed, 1208 insertions, 0 deletions
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: + |