--- a/versionControl/handOut.rst Mon Aug 24 00:49:24 2009 +0530
+++ b/versionControl/handOut.rst Mon Aug 24 01:17:45 2009 +0530
@@ -1,29 +1,30 @@
-Version Control
-===============
+=================
+ Version Control
+=================
Introduction
-------------
+============
The following words are from a blogpost "http://karlagius.com/2009/01/09/version-control-for-the-masses/"
"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.
-Version control (or source control) is nothing more arcane than keeping copies of ones work as one make changes to it. On the surface, it’s all straight-forward; make a copy of every file before making any changes to it. That way, if something seriously messes up, one can always fall back to something that worked before, or at least compare the broken copy with one that used to work so one can figure out where it went off kilter.Accidentally deleted half of thesis and closed the word processor? No problem – out comes the backup."
+Version control (or source control) is nothing more arcane than keeping copies of ones work as one make changes to it. On the surface, it’s all straight-forward; make a copy of every file before making any changes to it. That way, if something seriously messes up, one can always fall back to something that worked before, or at least compare the broken copy with one that used to work so one can figure out where it went off kilter. Accidentally deleted half of thesis and closed the word processor? No problem – out comes the backup."
Now, in the real world, it’s not so easy. One probably cooks up their own version control system without realizing it had such a geeky name. For instances files with names oldxxxxxx.odt and latestxxxxxx.odt. Every time to make some change in a file, one save it with different name then the original one. Luckily there are like, loads of version control systems out there to do this heavy lifting.
Why Use Version Control
------------------------
+=======================
"Its the start which most people fail to attempt".
-One of idea behind Version Control Tools was to save that "one" step, to build onto it, rather then simply lose it. So here are some reasons why is automated version control needed:
+One of idea behind Version Control Tools was to save that "one" step, to build onto it, rather then simply loose it. So here are some reasons why is automated version control needed:
- It will track the history and evolution of a project, so one don't have to do it manually. It allows to track what changes where made, when were they made, by whom and why.
- - For a team on people working on same project, revision control software makes it easier to collaborate. For example, when people more or less simultaneously make potentially incompatible changes, the software will help them to identify and resolve those conflicts.
+ - For a team of people working on same project, revision control software makes it easier to collaborate. For example, when people more or less simultaneously make potentially incompatible changes, the software will help them to identify and resolve those conflicts.
- It can help to recover from mistakes. If a change made at some moment of time, turns out to be in error in future, one can revert to an earlier version of one or more files. In fact, a really good revision control tool will even help in efficiently figure out exactly when a problem was introduced.
-Most of these reasons are equally valid for the project having one man show, or hundred people. Beyond this, even it can be used to maintain assignments related to one particular subject/course, it will help manage things in way much better way. Rather use these tools for *resource management*. All codes, documents, presentation, assignments related to one course maintained in such a inventory,and one would never need (excuse)/(face the embarrassament), "I accendently deleted my all data!"(for those who have actually done that after completing assignments), and Internet hosting for version control will make the work immune to local hard-disk crash, unless hosting crashes itself.
+Most of these reasons are equally valid for the project having one man show, or hundred people. Besides projects, even it can be used to maintain assignments related to one particular subject/course, it will help manage things in way much better way. These tools can be used for better *resources management*. All codes, documents, presentation, assignments related to one course maintained in such a inventory can help avoiding accidental lose of data(deletion) and Internet hosting for version control will make the work immune to local hard-disk crash, unless hosting crashes itself.
Some of Version Control Tools available and used widely are:
@@ -36,12 +37,12 @@
Each of above mentioned tools have sets of feature which it offers in unique way. For this session we are going to concentrate on hg (mercurial). After covering the basics of hg, one can easily try other tools, and use what-ever he/she is most comfortable with.
Learning the Lingo
-------------------
+==================
Each Version Control uses its own nomenclature for more or less the same features. Here are some of terms which are going to used through out the rest of session:
Basic Setup
-~~~~~~~~~~~
+-----------
Repository(repo):
The database/folder storing the files.
@@ -55,13 +56,13 @@
The “primary” location for code in the repo. Think of code as a family tree — the “trunk” is the main line. This is generally what is present on server.
Basic Actions
-~~~~~~~~~~~~~
+-------------
Add:
Put a file into the repo for the first time, i.e. begin tracking it with Version Control.
Revision:
What version a file is on.
- Head:
+ Head/Tip:
The latest revision of the repo.
Check out:
Initial download of repo onto machine.
@@ -77,7 +78,7 @@
Throw away the local changes and reload the latest version from the repository.
Advanced Actions:
-~~~~~~~~~~~~~~~~~
+-----------------
Branch:
Create a separate copy of a file/folder for private use (bug fixing, testing, etc).
@@ -91,9 +92,9 @@
Fixing the changes that contradict each other and checking in the correct version.
Types of Version Control:
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
-Based on how source management is carried out in a tool there are two categories of Version Control Systems(VCS):
+Based on how source/code management is carried out in a tool there are two categories of Version Control Systems(VCS):
- Centralized VCS:
In this kind of system all the revision control functions are performed on a shared server. If two developers try to change the same file at the same time, without some method of managing access the developers may end up overwriting each other's work. Centralized revision control systems solve this problem in one of two different "source management models": file locking and version merging. Both svn and cvs follows this kind of management.
@@ -102,10 +103,10 @@
In a distributed model, every developer has their own repo. Diffs, commits, and reverts are all done locally, one needs Internet only to share the changes with others. It makes work faster, handles branching and merging in better way, with less management. hg, bzr and git uses this work flow.
Get Going with Hg:
-------------------
+==================
Why hg?
-~~~~~~~
+-------
- It is easy to learn and use.
- It is lightweight.
@@ -113,9 +114,9 @@
- It is based on Python.
Getting Started:
-~~~~~~~~~~~~~~~~
+----------------
-Following command tells the version of hg installed on machine:
+Following command tells the version of hg installed on machine: ::
$hg version
@@ -144,9 +145,9 @@
NOTE:____________
Let there be Repository:
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
-In Mercurial, everything happens inside a repository. The repository for a project contains all of the files that “belong to” that project, along with a historical record of the project's files.A repository is simply a directory tree in filesystem that Mercurial treats as special.
+In Mercurial, everything happens inside a repository. The repository for a project contains all of the files that “belong to” that project, along with a historical record of the project's files. A repository is simply a directory tree in filesystem that Mercurial treats as special.
There can be two ways to create a repo, either getting local copy for existing repo available on Internet or machine, or creating a new repo. For getting already existing repo hg uses command *"clone"* ::
@@ -167,11 +168,11 @@
Every Mercurial repository is complete, self-contained, and independent. It contains its own private copy of a project's files and history.
-To start a new repository hg uses *"init"*: ::
+To start a new repository use *hg init*: ::
- $ mkdir feviCol
- $ cd feviCol/
- $ echo "print 'Yeh Fevicol ka Majboot jod hai!'" > feviStick.py
+ $ mkdir Fevicol
+ $ cd Fevicol/
+ $ echo "print 'Yeh Fevicol ka Majboot jod hai'" > feviStick.py
$ ls -a
. .. feviStick.py
$ hg init
@@ -188,14 +189,14 @@
newCopy is exact copy of already existing repo. And this command can be used to create branch of locally created repo also: ::
- $ hg clone feviCol feviCol-pull
+ $ hg clone Fevicol Fevicol-pull
updating working directory
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
These local branches can prove really handy at times. It allows keep multiple copies of local branch for different purposes, say for debugging, testing, working version.
History or Logs:
-~~~~~~~~~~~~~~~~
+----------------
For the new repo created, first thing which can be tried is to check the logs/history. What changes were made and when and why, answers to all those questions are stored in logs safely. So for the the cloned repo the history can be viewed using command *"log"* (following commands are wrt localCopyhello repo). ::
@@ -272,11 +273,11 @@
Get make to generate the final binary from a .o file.
Making Changes:
-~~~~~~~~~~~~~~~
+---------------
There is feviStick.py file in repo created above with name feviCol. ::
- $ cd feviCol
+ $ cd Fevicol
$ hg log
$ hg status
? feviStick.py
@@ -331,12 +332,184 @@
feviCol.py feviStick.py
Sharing Changes:
+----------------
+
+Pulling from repo:
+~~~~~~~~~~~~~~~~~~
+
+As mentioned earlier that repositories in Mercurial are self-contained. This means that the changeset just created exists only in Fevicol repository and not in previously cloned fevicol-pull. There are a few ways that can be used to propagate this change into other repositories. ::
+
+ $ hg clone Fevicol Fevicol-clone
+ updating working directory
+ 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+Or traverse into the any dir which is a working hg repo(using hg init) and pull command will download all changeset from main repo. ::
+
+ $ mkdir Fevicol-pull
+ $ cd Fevicol-pull
+ $ hg init
+ $ hg pull ../Fevicol
+ pulling from ../Fevicol
+ requesting all changes
+ adding changesets
+ adding manifests
+ adding file changes
+ added 2 changesets with 2 changes to 2 files
+ (run 'hg update' to get a working copy)
+
+*changeset* means a list of changes made to a file. In words of *hg help*, pull command is: ::
+
+ pull changes from the specified source
+
+ Pull changes from a remote repository to a local one.
+
+ This finds all changes from the repository at the specified path
+ or URL and adds them to the local repository. By default, this
+ does not update the copy of the project in the working directory.
+
+Some times, even before pulling changesets, one may need to see what changes would be pulled, Mercurial provides *hg incoming* to tell what changes *hg pull* would pull into repo, without actually pulling the changes. This command is really handy in case of avoiding unwanted changesets into the repo.
+
+With Mercurial, *hg pull* does not(by default) touch the working directory. Instead there is *hg up (alias update, co, checkout)* command to do this. ::
+
+ $ cd Fevicol-pull
+ $ ls -a
+ . .. .hg
+ $ hg up
+ 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ ls -a
+ . .. feviCol.py feviStick.py .hg
+
+To update to specific version, give a version number to the *hg update* command. ::
+
+ $ hg update 0
+ 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
+ $ hg parent
+ changeset: 0:84f5e91f4de1
+ user: Shantanu <shantanu@fossee.in>
+ date: Fri Aug 21 23:37:13 2009 +0530
+ summary: First commit.
+
+If no version number is specified *hg up* will update to the tip version. Version number of hg starts from 0. Compare *hg parent* output to the one before doing update to see the difference.
+
+Making Changes:
+~~~~~~~~~~~~~~~
+
+After getting the desired version of local repo, one can make changes as he/she needs and then make them available(share) for others. For these operations we will be working in Fevicol-clone repo which we created earlier. It's often good practice to keep a “pristine” copy of a remote repository around, which you can then make temporary clones of to create sandboxes for each task you want to work on. ::
+
+ $ cd Fevicol-clone/
+ $ cat cat feviStick.py
+ print 'Yeh Fevicol ka Majboot jod hai'
+
+This tagline is correct for feviCol.py but for feviStick.py it should be different. ::
+
+ $ echo "print 'Ab no more Chip Chip'" > feviStick.py
+ $ cat cat feviStick.py
+ print 'Ab no more Chip Chip'
+ $ hg st
+ M feviStick.py
+
+Mercurial's hg status command will tell us what Mercurial knows about the files in the repository. 'M' sign infront of feviStick.py indicates that Mercurial has noticed change.
+
+It's somewhat helpful to know that feviStick.py was modified, but one might prefer to know exactly what changes were made to it. To do this, use the *hg diff* command. ::
+
+ $ hg diff
+ diff -r a7912d45f47c feviStick.py
+ --- a/feviStick.py Sun Aug 23 22:34:35 2009 +0530
+ +++ b/feviStick.py Sun Aug 23 22:47:49 2009 +0530
+ @@ -1,1 +1,1 @@
+ -print 'Yeh Fevicol ka Majboot jod hai'
+ +print 'Ab no more Chip Chip'
+
+We can modify files, build and test our changes, and use hg status and hg diff to review our changes, until we're satisfied with what we've done and arrive at a natural stopping point where we want to record our work in a new changeset. All the diffs prior to committing the changes would be done wrt earlier marked record.The hg commit command lets us create a new changeset.
+
+Mercurial records your name and address with each change that you commit, so that you and others will later be able to tell who made each change. Mercurial tries to automatically figure out a sensible username to commit the change with. When we try to use *hg commit* there are various ways by which one can specify User name, some of those are:
+
+ - Specify a -u option to the hg commit command on the command line, followed by a username.
+ - set HGUSER environment variable.
+ - Edit hgrc file present in .hg folder to set this property, add following lines to that file and Mercurial will read those parameters from that location.
+
+ [ui]
+ username = Firstname Lastname <email.address@example.net>
+
+For me the hgrc file looks like this: ::
+
+ [paths]
+ default = /home/baali/Fevicol
+ [ui]
+ username = Shantanu Choudhary <shantanu@fossee.in>
+
+Once this parameter is set, *hg commit* command drops us into a text editor, to enter a message that will describe the modifications we've made in this changeset. This is called the commit message. It will be a record for readers of what we did and why, and it will be printed by hg log after we've finished committing. ::
+
+ Changed tagline for feviStick.py.
+ HG: Enter commit message. Lines beginning with 'HG:' are removed.
+ HG: --
+ HG: user: Shantanu Choudhary <shantanu@fossee.in>
+ HG: branch 'default'
+ HG: changed feviStick.py
+
+This would be vi sort of editor, where you can enter the log message in first line, once you are done with log message quit the editor using *[ESC] key ":wq"*.Once we've finished the commit, we can use the hg tip command to display the changeset we just created. ::
+
+ $ hg tip
+ changeset: 3:e1ab2aff4ddd
+ tag: tip
+ user: Shantanu Choudhary <shantanu@fossee.in>
+ date: Sun Aug 23 23:32:01 2009 +0530
+ summary: Changed tagline for feviStick.py.
+
+One can do above mentioned procedure using following one line command: ::
+
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "Changed tagline for feviStick.py."
+
+Sharing Changes:
~~~~~~~~~~~~~~~~
-As mentioned earlier that repositories in Mercurial are self-contained. This means that the changeset just created exists only in Fevicol repository and not in previously cloned feviVol-pull. There are a few ways that can be used to propagate this change into other repositories.
+The *hg outgoing* command tells us what changes would be pushed into another repository. ::
+
+ $ hg outgoing ../Fevicol
+ comparing with ../Fevicol
+ searching for changes
+ changeset: 3:e1ab2aff4ddd
+ tag: tip
+ user: Shantanu Choudhary <shantanu@fossee.in>
+ date: Sun Aug 23 23:32:01 2009 +0530
+ summary: Changed tagline for feviStick.py.
+
+And the hg push command does the actual push. ::
+
+ $ hg push ../Fevicol
+ pushing to ../Fevicol
+ searching for changes
+ adding changesets
+ adding manifests
+ adding file changes
+ added 1 changesets with 1 changes to 1 files
+
+As with hg pull, the hg push command does not update the working directory in the repository that it's pushing changes into. One has to use hg update to populate the changes in desired repo. ::
+
+ $ cd ../Fevicol
+ $ hg tip
+ changeset: 3:e1ab2aff4ddd
+ tag: tip
+ user: Shantanu Choudhary <shantanu@fossee.in>
+ date: Sun Aug 23 23:32:01 2009 +0530
+ summary: Changed tagline for feviStick.py.
+ $ cat feviStick.py
+ print 'Yeh Fevicol ka Majboot jod hai'
+
+changesets are imported, but update is yet to be done. ::
+
+ $ hg up tip
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ $ cat feviStick.py
+ print 'Ab no more Chip Chip'
+
+Dos and Don'ts with Mercurial:
+==============================
+
+
Suggested Reading:
-------------------
+==================
* http://karlagius.com/2009/01/09/version-control-for-the-masses/
* http://betterexplained.com/articles/a-visual-guide-to-version-control/