--- a/basic_python/intro.rst Tue Sep 08 18:14:15 2009 +0530
+++ b/basic_python/intro.rst Tue Sep 08 18:15:00 2009 +0530
@@ -1,6 +1,6 @@
-=====================
-Basic Python Workshop
-=====================
+============
+Basic Python
+============
This document is intended to be handed out at the end of the workshop. It has
been designed for Engineering students who are Python beginners and have basic
@@ -8,27 +8,404 @@
The system requirements:
* Python - version 2.5.x or newer.
- * IPython
+ * IPython
* Text editor - scite, vim, emacs or whatever you are comfortable with.
-
-
-
Introduction
============
- The Python programming language was created by a dutch named Guido van Rossum.
- The idea of Python was conceived in December 1989. The name Python has nothing
- to do with the reptilian, but its been named after the 70s comedy series
- "Monty Python's Flying Circus", since it happens to be Guido's favourite
- TV series.
+The Python programming language was created by a dutch named Guido van Rossum.
+The idea of Python was conceived in December 1989. The name Python has nothing
+to do with the reptilian, but its been named after the 70s comedy series
+"Monty Python's Flying Circus", since it happens to be Guido's favourite
+TV series.
+
+Current stable version of Python is 2.6.x, although Python 3.0 is also the stable
+version, it is not backwards compatible with the previous versions and is hence
+not entirely popular at the moment. This material will focus on the 2.6.x series.
- Current stable version of Python is 2.6.x, although Python 3.0 is also the stable
- version, it is not backwards compatible with the previous versions and is hence
- not entirely popular at the moment. This material contains material pertaining
- to the 2.6.x series.
-
+Python is licensed under the Python Software Foundation License (PSF License)
+which is GPL compatible Free Software license (excepting license version 1.6 and 2.0)
+It is a no strings attached license, which means the source code is free to modify
+and redistribute.
+
+The Python docs define Python as "Python is an interpreted, object-oriented,
+high-level programming language with dynamic semantics." A more detailed summary
+can be found at http://www.python.org/doc/essays/blurb.html. Python is a language that
+has been designed to help the programmer concentrate on solving the problem at hand
+and not worry about the programming language idiosyncrasies.
+
+Python is a highly cross platform compatible language on account of it being an
+interpreted language. It is highly scalable and hence has been adapted to run on
+the Nokia 60 series phones. Python has been designed to be readable and easy to use
+
+**Resources available for reference**
+
+* Web: http://www.python.org
+* Doc: http://www.python.org/doc
+* Free Tutorials:
+ * Official Python Tutorial: http://docs.python.org/tut/tut.html
+ * Byte of Python: http://www.byteofpython.info/
+ * Dive into Python: http://diveintopython.org/
+
+**Advantages of Python - Why Python??**
+
+* Python has been designed for readability and ease of use. Its been designed in
+ such a fashion that it imposes readability on the programmer. Python does away
+ with the braces and the semicolons and instead implements code blocks based on
+ indentation, thus enhancing readability.
+
+* Python is a high level, interpreted, modular and object oriented language.
+ Python performs memory management on its own, thus the programmer need not bother
+ about allocating and deallocating memory to variables. Python provides extensibility
+ by providing modules which can be easily imported similar to headers in C and
+ packages in Java. Python is object oriented and hence provides all the object oriented
+ characteristics such as inheritance, encapsulation and polymorphism.
+
+* Python offers a highly powerful interactive programming interface in the form
+ of the 'Interactive Interpreter' which will be discussed in more detail in the
+ following sections.
+
+* Python provides a rich standard library and an extensive set of modules. The
+ power of Python modules can be seen in this slightly exaggerated cartoon
+ http://xkcd.com/353/
+
+* Python interfaces well with most other programming languages such as C, C++
+ and FORTRAN.
+
+Although, Python has one setback. Python is not fast as some of the compiled
+languages like C or C++. Yet, the amount of flexibility and power more than make
+up for this setback.
+
+
The Python Interpreter
======================
+
+The Interactive Interpreter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typing *python* at the shell prompt on any standard Unix/Gnu-Linux system and
+hitting the enter key fires up the Python 'Interactive Interpreter'. The Python
+interpreter is one of the most integral features of Python. The prompt obtained
+when the interactive interpreter is similar to what is shown below. The exact
+appearance might differ based on the version of Python being used. The ``>>>``
+thing shown is the python prompt. When something is typed at the prompt and the
+enter key is hit, the python interpreter interprets the command entered and
+performs the appropriate action.
+
+::
+
+ Python 2.5.2 (r252:60911, Oct 5 2008, 19:24:49)
+ [GCC 4.3.2] on linux2
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>>
+
+Lets try with an example, type ``print 'Hello, World!'`` at the prompt and hit
+the enter key.
+
+::
+
+ >>> print 'Hello, World!'
+ Hello, World!
+
+This example was quite straight forward, and thus we have written our first
+line of Python code. Now let us try typing something arbitrary at the prompt.
+For example:
+
+::
-
\ No newline at end of file
+ >>> arbit word
+ File "<stdin>", line 1
+ arbit word
+ ^
+ SyntaxError: invalid syntax
+ >>>
+
+The interpreter gave an error message saying that 'arbit word' was invalid
+syntax which is valid. The interpreter is an amazing tool when learning to
+program in Python. The interpreter provides a help function that provides the
+necessary documentation regarding all Python syntax, constructs, modules and
+objects. Typing *help()* at the prompt gives the following output:
+
+::
+
+ >>> help()
+
+ Welcome to Python 2.5! This is the online help utility.
+
+ If this is your first time using Python, you should definitely check out
+ the tutorial on the Internet at http://www.python.org/doc/tut/.
+
+ Enter the name of any module, keyword, or topic to get help on writing
+ Python programs and using Python modules. To quit this help utility and
+ return to the interpreter, just type "quit".
+
+ To get a list of available modules, keywords, or topics, type "modules",
+ "keywords", or "topics". Each module also comes with a one-line summary
+ of what it does; to list the modules whose summaries contain a given word
+ such as "spam", type "modules spam".
+
+ help>
+
+
+As mentioned in the output, entering the name of any module, keyword or topic
+will provide the documentation and help regarding the same through the online
+help utility. Pressing *Ctrl+d* exits the help prompt and returns to the
+python prompt.
+
+Let us now try a few examples at the python interpreter.
+
+Eg 1:
+::
+
+ >>> print 'Hello, python!'
+ Hello, python!
+ >>>
+
+Eg 2:
+::
+
+ >>> print 4321*567890
+ 2453852690
+ >>>
+
+Eg 3:
+::
+
+ >>> 4321*567890
+ 2453852690L
+ >>>
+
+::
+
+ Note: Notice the 'L' at the end of the output. The 'L' signifies that the
+ output of the operation is of type *long*. It was absent in the previous
+ example because we used the print statement. This is because *print* formats
+ the output before displaying.
+
+Eg 4:
+::
+
+ >>> big = 12345678901234567890 ** 3
+ >>> print big
+ 1881676372353657772490265749424677022198701224860897069000
+ >>>
+
+::
+
+ This example is to show that unlike in C or C++ there is no limit on the
+ value of an integer.
+
+*ipython* - An enhanced interactive Python interpreter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The power and the importance of the interactive interpreter was the highlight
+of the previous section. This section provides insight into the enhanced
+interpreter with more advanced set of features called **ipython**. Entering
+*ipython* at the shell prompt fires up the interactive interpreter.
+
+::
+
+ $ ipython
+ Python 2.5.2 (r252:60911, Oct 5 2008, 19:24:49)
+ Type "copyright", "credits" or "license" for more information.
+
+ IPython 0.8.4 -- An enhanced Interactive Python.
+ ? -> Introduction and overview of IPython's features.
+ %quickref -> Quick reference.
+ help -> Python's own help system.
+ object? -> Details about 'object'. ?object also works, ?? prints more.
+
+ In [1]:
+
+This is the output obtained upon firing ipython. The exact appearance may
+change based on the Python version installed. The following are some of the
+various features provided by **ipython**:
+
+ Suggestions - ipython provides suggestions of the possible methods and
+ operations available for the given python object.
+
+Eg 5:
+
+::
+
+ In [4]: a = 6
+
+ In [5]: a.
+ a.__abs__ a.__divmod__ a.__index__ a.__neg__ a.__rand__ a.__rmod__ a.__rxor__
+ a.__add__ a.__doc__ a.__init__ a.__new__ a.__rdiv__ a.__rmul__ a.__setattr__
+ a.__and__ a.__float__ a.__int__ a.__nonzero__ a.__rdivmod__ a.__ror__ a.__str__
+ a.__class__ a.__floordiv__ a.__invert__ a.__oct__ a.__reduce__ a.__rpow__ a.__sub__
+ a.__cmp__ a.__getattribute__ a.__long__ a.__or__ a.__reduce_ex__ a.__rrshift__ a.__truediv__
+ a.__coerce__ a.__getnewargs__ a.__lshift__ a.__pos__ a.__repr__ a.__rshift__ a.__xor__
+ a.__delattr__ a.__hash__ a.__mod__ a.__pow__ a.__rfloordiv__ a.__rsub__
+ a.__div__ a.__hex__ a.__mul__ a.__radd__ a.__rlshift__ a.__rtruediv__
+
+In this example, we initialized 'a' (a variable - a concept that will be
+discussed in the subsequent sections.) to 6. In the next line when the *tab* key
+is pressed after typing '*a.*' ipython displays the set of all possible methods
+that are applicable on the object 'a' (an integer in this context). Ipython
+provides many such datatype specific features which will be presented in the
+further sections as and when the datatypes are introduced.
+
+Editing and running a python file
+=================================
+
+The previous sections focused on the use of the interpreter to run python code.
+While the interpeter is an excellent tool to test simple solutions and
+experiment with small code snippets, its main disadvantage is that everything
+written in the interpreter is lost once its quit. Most of the times a program is
+used by people other than the author. So the programs have to be available in
+some form suitable for distribution, and hence they are written in files. This
+section will focus on editing and running python files. Start by opening a text
+editor ( it is recommended you choose one from the list at the top of this page ).
+In the editor type down python code and save the file with an extension **.py**
+(python files have an extension of .py). Once done with the editing, save the
+file and exit the editor.
+
+Let us look at a simple example of calculating the gcd of 2 numbers using Python:
+
+**Creating the first python script(file)**
+::
+
+ $ emacs gcd.py
+ def gcd(x,y):
+ if x % y == 0:
+ return y
+ return gcd(y, x%y)
+
+ print gcd(72, 92)
+
+To run the script, open the shell prompt, navigate to the directory that
+contains the python file and run `python <filename.py>` at the prompt ( in this
+case filename is gcd.py )
+
+**Running the python script**
+::
+
+ $ python gcd.py
+ 4
+ $
+
+Another method to run a python script would be to include the line
+
+`#! /usr/bin/python`
+
+at the beginning of the python file and then make the file executable by
+
+$ chmod a+x *filename.py*
+
+Once this is done, the script can be run as a standalone program as follows:
+
+$ ./*filename.py*
+
+Basic Datatypes and operators in Python
+=======================================
+
+Python provides the following set of basic datatypes.
+
+ * Numbers: int, float, long, complex
+ * Strings
+ * Boolean
+
+Numbers
+~~~~~~~
+
+Numbers were introduced in the examples presented in the interactive interpreter
+section. Numbers include types as mentioned earlier viz., int (integers), float
+(floating point numbers), long (large integers), complex (complex numbers with
+real and imaginary parts). Python is not a strongly typed language, which means
+the type of a variable need not mentioned during its initialization. Let us look
+at a few examples.
+
+Eg 6:
+::
+
+ >>> a = 1 #here a is an integer variable
+
+Eg 7:
+::
+
+ >>> lng = 122333444455555666666777777788888888999999999 #here lng is a variable of type long
+ >>> lng
+ 122333444455555666666777777788888888999999999L #notice the trailing 'L'
+ >>> print lng
+ 122333444455555666666777777788888888999999999 #notice the absence of the trailing 'L'
+ >>> lng+1
+ 122333444455555666666777777788888889000000000L
+
+
+Long numbers are the same as integers in almost all aspects. They can be used in
+operations just like integers and along with integers without any distinction.
+The only distinction comes during type checking (which is not a healthy practice).
+Long numbers are tucked with a trailing 'L' just to signify that they are long.
+Notice that in the example just lng at the prompt displays the value of the variable
+with the 'L' whereas `print lng` displays without the 'L'. This is because print
+formats the output before printing. Also in the example, notice that adding an
+integer to a long does not give any errors and the result is as expected. So for
+all practical purposes longs can be treated as ints.
+
+Eg 8:
+::
+
+ >>> fl = 3.14159 #fl is a float variable
+ >>> e = 1.234e-4 #e is also a float variable, specified in the exponential form
+ >>> a = 1
+ >>> b = 2
+ >>> a/b #integer division
+ 0
+ >>> a/fl #floating point division
+ 0.31831015504887655
+ >>> e/fl
+ 3.9279473133031364e-05
+
+
+Floating point numbers, simply called floats are real numbers with a decimal point.
+The example above shows the initialization of a float variable. Shown also in this
+example is the difference between integer division and floating point division.
+'a' and 'b' here are integer variables and hence the division gives 0 as the quotient.
+When either of the operands is a float, the operation is a floating point division,
+and the result is also a float as illustrated.
+
+Eg 9:
+::
+
+ >>> cplx = 3 + 4j #cplx is a complex variable
+ >>> cplx
+ (3+4j)
+ >>> print cplx.real #prints the real part of the complex number
+ 3.0
+ >>> print cplx.imag #prints the imaginary part of the complex number
+ 4.0
+ >>> print cplx*fl #multiplies the real and imag parts of the complex number with the multiplier
+ (9.42477+12.56636j)
+ >>> abs(cplx) #returns the absolute value of the complex number
+ 5.0
+
+Python provides a datatype for complex numbers. Complex numbers are initialized
+as shown in the example above. The *real* and *imag* operators return the real and
+imaginary parts of the complex number as shown. The *abs()* returns the absolute
+value of the complex number.
+
+Variables
+~~~~~~~~~
+
+Variables are just names that represent a value. Variables have already been
+introduced in the various examples from the previous sections. Certain rules about
+using variables:
+
+ * Variables have to be initialized or assigned a value before being used.
+ * Variable names can consist of letters, digits and underscores(_).
+ * Variable names cannot begin with digits, but can contain digits in them.
+
+In reference to the previous section examples, 'a', 'b', 'lng', 'fl', 'e' and 'cplx'
+are all variables of various datatypes.
+
+::
+
+ Note: Python is not a strongly typed language and hence an integer variable can at a
+ later stage be used as a float variable as well.
+
+Strings
+~~~~~~~
+
--- a/latex/handout.rst Tue Sep 08 18:14:15 2009 +0530
+++ b/latex/handout.rst Tue Sep 08 18:15:00 2009 +0530
@@ -545,15 +545,12 @@
::
\begin{verbatim}
- 10 PRINT "HELLO WORLD ";
- 20 GOTO 10
+ from numpy import *
+ a = linspace(0, 5, 50, endpoint = False)
\end{verbatim}
-
-10 PRINT "HELLO WORLD ";
-
-20 GOTO 10
-
+ from numpy import *
+ a = linspace(0, 5, 50, endpoint = False)
Within a paragraph, similar behavior can be accessed with
::
@@ -565,14 +562,14 @@
The starred verstion of the verbatim environment emphasizes the spaces in the text.
::
- \begin{verbatim*}
- 10 PRINT "HELLO WORLD ";
- 20 GOTO 10
- \end{verbatim*}
+ \begin{verbatim}
+ from numpy import *
+ a = linspace(0, 5, 50, endpoint = False)
+ \end{verbatim}
-10␣PRINT␣"HELLO␣WORLD␣";
+ from␣numpy␣import␣*
+ a␣=␣linspace(0,␣5,␣50,␣endpoint␣=␣False)
-20␣GOTO␣10
Tables, Figures and Captions
----------------------------
@@ -659,7 +656,7 @@
+-----------+-------------------------------------------------------------------+
| Specifier | Permission |
-+-----------+-------------------------------------------------------------------+
++===========+===================================================================+
| h | Place the float here |
| | (approximately at the same point it occurs in the source text) |
+-----------+-------------------------------------------------------------------+
@@ -777,11 +774,115 @@
Arrays and Matrices
+++++++++++++++++++
+To typset arrays, use the ``array`` environment. It works similar to the ``tabular`` environment. The ``\\`` command is used to break the lines.
+::
+
+ \begin{equation*}
+ \mathbf{X} = \left(
+ \begin{array}{ccc}
+ x_1 & x_2 & \ldots \\
+ x_3 & x_4 & \ldots \\
+ \vdots & \vdots & \ddots
+ \end{array} \right)
+ \end{equation*}
+
+The ``array`` environment can also be used to typeset piecewise functions by using a “.” as an invisible ``\right`` delimiter
+::
+
+ \begin{equation*}
+ |x| = \left\{
+ \begin{array}{rl}
+ -x & \text{if } x < 0\\
+ 0 & \text{if } x = 0\\
+ x & \text{if } x > 0
+ \end{array} \right.
+ \end{equation*}
+
+The ``array`` environment can be used for typesetting matrices also, but ``amsmath`` provides a better solution using the different matrix environments. There are six versions with different delimiters: ``matrix`` (none), ``pmatrix`` (, ``bmatrix`` [, ``Bmatrix`` {, ``vmatrix`` | and ``Vmatrix`` ‖. The number of columns need not be specified, unlike the ``array`` environment.
+::
+
+ \begin{equation*}
+ \begin{matrix}
+ 1 & 2 \\
+ 3 & 4
+ \end{matrix} \qquad
+
+ \begin{bmatrix}
+ 1 & 2 & 3 \\
+ 4 & 5 & 6 \\
+ 7 & 8 & 9
+ \end{bmatrix}
+ \end{equation*}
+
Bibliography
------------
-You can produce a bibliography with the ``thebibliography`` environment.
+As mentioned previously, you can either use the ``thebibliography`` environment to include your references in the main document file itself, or use BibTeX to generate a database of references and keep using them as and when required. We shall first look at how we can include the reference items within our document itself.
+
+``thebibliography`` environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the thebibliography environment, you simply list down all the bibliography items within the bibliography environment as shown below.
+
+Each item starts with ``\bibitem[label]{marker}``. The marker is then used to cite the bibliography item within the document, using ``\cite{marker}``. If the ``label`` option is not used, the bibliography items get enumerated automatically.
+::
+
+ Lamport's \cite{WBook} book is a good reference for LaTeX.
+
+ \begin{thebibliography}{99}
+
+ \bibitem{WBook} Lamport, Leslie (1994). \emph{LaTeX: A document preparation system: User's guide and reference}.
+ illustrations by Duane Bibby (2nd ed.). Reading, Mass: Addison-Wesley Professional.
+
+ \end{thebibliography}
+
+The ``99`` in the example above indicates the maximum width of the label that the references may get. We here assume that the number of Bibliography items will be less than 100. If your document has less than 10 references, you may want to replace ``99`` with ``9``.
+
+BibTeX
+~~~~~~
+
+The previous section detailed the process of embedding the references at the end of the document's source file and using the ``\cite`` command to cite them. In this section we shall use the BibTeX environment for references.
+
+Using BibTeX you can create a database of all your references in a text file and cite the appropriate ones in each document. This method is much more convinient than writing down all the references for each document at the end of it, when you are writing multiple documents in a field.
+
+The BibTeX database is stored in a ``.bib`` file. The structure of the file is quite simple and an example is shown below.
+::
+
+ @book{Lamport94,
+ author = "Leslie Lamport",
+ title = "A Document Preparation System: User's Guide and Reference",
+ publisher = "Addison-Wesley Professional",
+ year = "1994",
+ edtion = "second",
+ note = "illustrations by Duane Bibby"
+ }
+
+Each bibliography entry starts with a declaration of the type of the reference being mentioned. The reference is in the above example is of the book type. BibTeX has a wide range of reference types, for example, ``article, book, conference, manual, proceedings, unpublished``.
+
+The type of reference is followed by a left curly brace, and immediately followed by the citation key. The citation key, ``Lamport94`` in the example above is used to cite this reference using the command ``\cite{Lamport94}``.
+
+This is followed by the relevant fields and their values, listed one by one. Each entry must be followed by a comma to delemit one field from the other.
+
+To get your LaTeX document to use the bibliography database, you just add the following lines to your LaTeX document.
+::
+
+ \bibliographystyle{plain}
+ \bibliography{LaTeX}
+
+Bibliography styles are files that tell BibTeX how to format the information stored in the ``.bib`` database file. The style file for this example is ``plain.bst``. Note that you do not need to add the ``.bst`` extension to the filename. If you wish to achieve a particular style of listing the bibliography items and citing them, you should use an appropriate style file.
+
+The ``bibliography`` command specifies the file that shoule be used as the database for references. The file used in this example is ``LaTeX.bib``
+
+Compiling
++++++++++
+
+Adding BibTeX based references, slightly complicates the process of coompiling the document to obtain the desired output. The exact workings of LaTeX and BibTeX will not be explained here. The procedure for obtaining the output (without any explanations) is as follows:
+
+1. Compile the ``.tex`` file using ``pdflatex`` - ``$pdflatex LaTeX(.tex)``
+2. Compile the ``.bib`` file using ``bibtex`` - ``$bibtex LaTeX(.bib)``
+3. Compile the ``.tex`` file again.
+4. Compile the ``.tex`` file for one last time!
--------------------------------------------------------
--- a/versionControl/handOut.rst Tue Sep 08 18:14:15 2009 +0530
+++ b/versionControl/handOut.rst Tue Sep 08 18:15:00 2009 +0530
@@ -12,13 +12,12 @@
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.
+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.py and latestxxxxxx.py. 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 loose it. So here are some reasons why is automated version control needed:
+
+One of idea behind Version Control Tools was to build onto very first step which can be creating a empty file, or writing a first buggy program for assignment, 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 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.
@@ -113,6 +112,8 @@
- It scales excellently.
- It is based on Python.
+A small point to notice here, hg cant track binary files for changes, one can add them to repo, but wont be able to track changes made to it. And hg considers, odt, pdf files as binary.
+
Getting Started:
----------------
@@ -147,7 +148,7 @@
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 file-system 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"* ::
@@ -275,14 +276,14 @@
Making Changes:
---------------
-There is feviStick.py file in repo created above with name feviCol. ::
+There is feviStick.py file in repo created above with name Fevicol. *status(alias st)* command prints the revision history of the specified files or the entire project::
$ cd Fevicol
$ hg log
$ hg status
? feviStick.py
-*status(st)* command prints the revision history of the specified files or the entire project. "?" sign in front of file indicates that this file is not yet part of track record. *add* command is used to add new files to repo. ::
+"?" sign in front of file indicates that this file is not yet part of track record. *add* command is used to add new files to repo. ::
$ hg add feviStick.py
$ hg st
@@ -298,13 +299,13 @@
date: Fri Aug 21 23:37:13 2009 +0530
summary: First commit.
-Similar to add there are other commands available for file management in repo. ::
+Similar to add there are other commands available for file management in repo. *copy (alias cp)* command is used to mark files as copied for the next commit. ::
$ hg cp feviStick.py pidiLite.py
$ hg st
A pidiLite.py
-*copy (alias cp)* command is used to mark files as copied for the next commit. ::
+*rename(alias mv)* rename files; equivalent of copy + remove. *tip* command shows newest revision in the repository. ::
$ hg rename pidiLite.py feviCol.py
$ hg st
@@ -317,7 +318,7 @@
date: Sat Aug 22 00:11:25 2009 +0530
summary: Renamed pidiLite.py.
-*rename(alias mv)* rename files; equivalent of copy + remove. *tip* command shows newest revision in the repository.. ::
+*remove* command is used to remove files from a repo. ::
$ hg remove feviCol.py
$ hg st
@@ -337,7 +338,7 @@
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. ::
+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
@@ -397,18 +398,18 @@
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
+ $ 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
+ $ 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.
+Mercurial's hg status command will tell us what Mercurial knows about the files in the repository. 'M' sign in front 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. ::
@@ -426,7 +427,7 @@
- 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.
+ - 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>
@@ -447,7 +448,7 @@
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. ::
+This would be your default system editor(for me it is vim, one can set it also), 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
@@ -474,7 +475,7 @@
date: Sun Aug 23 23:32:01 2009 +0530
summary: Changed tagline for feviStick.py.
-And the hg push command does the actual push. ::
+And the *hg push* command does the actual push. ::
$ hg push ../Fevicol
pushing to ../Fevicol
@@ -503,10 +504,193 @@
$ $ cat feviStick.py
print 'Ab no more Chip Chip'
-Dos and Don'ts with Mercurial:
-==============================
+Merging the Work:
+~~~~~~~~~~~~~~~~~
+
+This is next aspect of any version control, how to merge work done by various participants of project in a way that no one looses changes being made, and still remains updated. Here is simple case study which can help understanding why merging is required:
+
+Two persons, A and B are contributing on same project. Both starts from cloning the same online repo(lets say present state X), so that both have a working local repo. Now A edits one of file, commits the changes and pushes to the repo, hence changing the state of repo to Y, but B, have not updated his repo, makes a change in one of files and reaches to a different state Z. Now when A pulls repo from B, his repo will have multiple heads. This stage is clearly ambiguous, the repo of A is not consistent, it has multiple heads, and from here, whatever changes he makes can take whatsoever direction if it is not fixed, and hence A will have to merge changes so that everything becomes consistent again.
+
+Lets see how this work with working repo, we will use Fevicol and Fevicol-clone repositories created earlier. For now, the status of both repo is: ::
+
+ $ cd Fevicol-clone
+ $ 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.
+
+The tagline for feviCol.py is not complete, so we make changes in that file in this repo. ::
+
+ $ echo "print 'Yeh Fevicol ka Majboot jod hai, tootega nahin'" > feviStick.py
+ $ hg st
+ M feviStick.py
+
+And commit the changes made ::
+
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "Updated tag line for feviCol.py."
+ $ hg st
+ $ hg tip
+ changeset: 4:caf986b15e05
+ tag: tip
+ user: Shantanu <shantanu@fossee.in>
+ date: Tue Aug 25 16:28:24 2009 +0530
+ summary: Updated tag line for feviCol.py.
+
+Now we will make some changes on Fevicol repo. We will add new file here ::
+
+ $ cd Fevicol
+ $ echo "print 'Jor laga ke hayyiya'" > firstAdd.py
+ $ hg st
+ ? firstAdd.py
+ $ hg add firstAdd.py
+ $ hg st
+ A firstAdd.py
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "Added firsAdd.py."
+ $ hg tip
+ changeset: 4:fadbd6492cc4
+ tag: tip
+ user: Shantanu <shantanu@fossee.in>
+ date: Tue Aug 25 16:46:24 2009 +0530
+ summary: Added firsAdd.py.
+
+So now we have two repo, who have different commit history and tree, now if we try to pull changes from one to another, this is how it goes(we are still in Fevicol repo): ::
+
+ $ hg pull ../Fevicol-clone
+ pulling from ../Fevicol-clone
+ 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)
+
+There we go, since both repo were on different track, hg pull command in last line gives some heading from here. *hg heads* command show current repository heads or show branch heads. ::
+
+ $ hg heads
+ changeset: 5:caf986b15e05
+ tag: tip
+ parent: 3:e1ab2aff4ddd
+ user: Shantanu <shantanu@fossee.in>
+ date: Tue Aug 25 16:28:24 2009 +0530
+ summary: Updated tag line for feviCol.py.
+ changeset: 4:fadbd6492cc4
+ user: Shantanu <shantanu@fossee.in>
+ date: Tue Aug 25 16:46:24 2009 +0530
+ summary: Added firsAdd.py.
+
+To get better understanding of what is going on hg have a tool known as *glog* which shows revision history alongside an ASCII revision graph. ::
+
+ $ hg glog
+ o changeset: 5:caf986b15e05
+ | tag: tip
+ | parent: 3:e1ab2aff4ddd
+ | user: Shantanu <shantanu@fossee.in>
+ | date: Tue Aug 25 16:28:24 2009 +0530
+ | summary: Updated tag line for feviCol.py.
+ |
+ | @ changeset: 4:fadbd6492cc4
+ |/ user: Shantanu <shantanu@fossee.in>
+ | date: Tue Aug 25 16:46:24 2009 +0530
+ | summary: Added firsAdd.py.
+ |
+ o changeset: 3:e1ab2aff4ddd
+ | user: Shantanu Choudhary <shantanu@fossee.in>
+ | date: Sun Aug 23 23:32:01 2009 +0530
+ | summary: Changed tagline for feviStick.py.
+ |
+ o changeset: 2:a7912d45f47c
+ | user: Shantanu <shantanu@fossee.in>
+ | date: Sun Aug 23 22:34:35 2009 +0530
+ | summary: Updated Content.
+ |
+ o changeset: 1:d948fb4137c5
+ | user: Shantanu <shantanu@fossee.in>
+ | date: Sat Aug 22 00:11:25 2009 +0530
+ | summary: Renamed pidiLite.py.
+ |
+ o changeset: 0:84f5e91f4de1
+ user: Shantanu <shantanu@fossee.in>
+ date: Fri Aug 21 23:37:13 2009 +0530
+ summary: First commit.
+To bring repo on single track/branch once again we will have to merge these two branches. Without merging them even hg update wont work for obvious reason of confusing track record. ::
+
+ $ hg up
+ abort: crosses branches (use 'hg merge' or 'hg update -C')
+
+*hg merge* command merge working directory with another revision. ::
+
+ $ hg merge
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ (branch merge, don't forget to commit)
+ $ hg tip
+ changeset: 5:caf986b15e05
+ tag: tip
+ parent: 3:e1ab2aff4ddd
+ user: Shantanu <shantanu@fossee.in>
+ date: Tue Aug 25 16:28:24 2009 +0530
+ summary: Updated tag line for feviCol.py.
+
+After merging two branches, until we commit the results of merge it will keep on showing two heads. ::
+
+ $ hg ci -u "Shantanu <shantanu@fossee.in>" -m "Merged branches of add and tag line."
+ $ hg heads
+ changeset: 6:edbe97209954
+ tag: tip
+ parent: 4:fadbd6492cc4
+ parent: 5:caf986b15e05
+ user: Shantanu <shantanu@fossee.in>
+ date: Tue Aug 25 17:06:03 2009 +0530
+ summary: Merged branches of add and tag line.
+
+Here is brief and meaningful output of glog ::
+
+ $ hg glog
+ @ changeset: 6:edbe97209954
+ |\ tag: tip
+ | | parent: 4:fadbd6492cc4
+ | | parent: 5:caf986b15e05
+ | | user: Shantanu <shantanu@fossee.in>
+ | | date: Tue Aug 25 17:06:03 2009 +0530
+ | | summary: Merged branches of add and tag line.
+ | |
+ | o changeset: 5:caf986b15e05
+ | | parent: 3:e1ab2aff4ddd
+ | | user: Shantanu <shantanu@fossee.in>
+ | | date: Tue Aug 25 16:28:24 2009 +0530
+ | | summary: Updated tag line for feviCol.py.
+ | |
+ o | changeset: 4:fadbd6492cc4
+ |/ user: Shantanu <shantanu@fossee.in>
+ | date: Tue Aug 25 16:46:24 2009 +0530
+ | summary: Added firsAdd.py.
+
+And we are back on track.
+
+Workflow:
+=========
+
+This is chain of steps which can be followed for working against a project that has a centralized copy, you may want to make sure you're up to date first. This means pulling its changes and then updating.
+
+For example: ::
+
+ $ hg pull
+ $ hg update
+
+This will grab the remote changes from the location you first cloned from. Then it will apply the changes. You can do this in one go with: ::
+
+ $ hg pull -u
+
+Now let's say you make some changes. You edit a file and you want to commit your change. You can do this with: ::
+
+ $ hg commit
+
+An editor will pop-up asking you to write a message describing your change. This is required. When you're done for the day, and you have required changesets sitting in your repository. Before pushing to upstream make sure to pull and update and merge branches if required, once everything looks okay and you have single track, push the changes, ::
+
+ $ hg push
Suggested Reading:
==================
@@ -516,3 +700,4 @@
* http://en.wikipedia.org/wiki/Revision_control
* http://hgbook.red-bean.com/
* http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/
+ * http://wiki.alliedmods.net/Mercurial_Tutorial