diff text/quick_start.txt @ 105:7a057bf137c5

Added a bastic draft for a quick_start - copied from the mailing list :) .

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/text/quick_start.txt	Wed Apr 22 13:26:05 2009 +0200
@@ -0,0 +1,137 @@
+= Quick Start =
+
+When you've been using Mercurial for some time, many things become 
+second nature, so it's sometimes hard to remember that its basic concepts are 
+quite revolutionary compared to Subversion. 
+
+Please don't let that intimidate you. Mercurial is damn powerful, even if you 
+just use the basics (init, commit, log, pull, push, serve, merge). And the 
+basics are very easy to use, once you see the model behind that: Each 
+repository has the whole history, and history is not necessarily linear. 
+
+Just stick to these and learn the rest of its commands as you need them. 
+
+As a short intro: 
+
+- init: create a new repository
+- commit: save your changes in the current repository
+- log: see all changes in your repository
+- pull: get all changes from another repository int the current one
+- push: get all changes from your repository into another one
+- serve: create an instant-webserver. People can see the history there and 
+pull from it
+- merge: join different lines of history
+
+If you want to see a nice graph of the history, just do "hg serve" in your 
+repository and then direct your browser to 
+
+        http://127.0.0.1:8000
+
+This also helps getting a feeling for what the commands do. 
+
+(you can do more finegrained stuff with command options. Just call "hg help 
+<command>" to see them). 
+
+
+I hope your experience with Mercurial will be as great as mine!
+
+- Arne Babenhauserheide
+
+= Basic concepts of Mercurial =
+
+//If you're interested in the concepts behind Mercurial, please come with us and listen to a great explanation from Martin Geisler: //
+
+Let me try to make
+some of the basic concepts clear:
+
+* Like in Subversion, history consists of a number of commits. They're
+  called changesets in Mercurial.
+
+* Subversion requires a strict linear ordering of the commits and
+  gives nice linear revision numbers to them. So revision N has only
+  one child revision, rN+1.
+
+  This is simple, but it requires a central server to make sure that
+  everybody agrees on the revision numbers.
+
+* Mercurial generalizes this by letting each changeset have multiple
+  children. If I work alone and make commits I'll make
+
+    C1 --> C2 --> C3
+
+  by making three commits. The commit C3 with no children is a "head".
+  It is also the newest changeset in the repository -- called "tip".
+
+  If I shared C1 with you and you started your work from that, your
+  commits will build a repository like this:
+
+    C1 --> C2' --> C3'
+
+  Here C3' is a head in your repository and I don't know anything
+  about C2' and C3' yet.
+
+* If I pull from you, or you push to me, the two repositories are
+  compared. By default, all missing changesets are transferred. This
+  is all there is to push/pull: compare two graphs of changesets and
+  transfer the missing ones.
+
+  After a pull from you my repository will look like this:
+
+         /-> C2 --> C3
+    C1 -<
+         \-> C2' --> C3'
+
+  Here C1 has two child changesets, and the repository has two heads
+  since the development has diverged.
+
+  The changeset C3' will be the new tip since it is the newest
+  changeset in the repository. Note that tip is always a head, but a
+  head need not be the tip.
+
+* Having two heads suggest that someone should merge them -- otherwise
+  the changes from one will never be combined with the changed made in
+  the other head.
+
+  When merging with 'hg merge' the task is to figure out the canonical
+  way to combine the changesets. If the changes do not overlap this is
+  usually trivial, otherwise you have to do a three-way merge. The
+  merge must be committed and this creates a changeset which explains
+  to the world how you think the two heads should be combined:
+
+         /-> C2 --> C3   -\
+    C1 -<                  >-> M
+         \-> C2' --> C3' -/
+
+  Note that the merge changeset M has two parents.
+
+  If you do not merge C3 and C3' and try to push you get the 'new
+  remote head' message and push aborts. It aborts since it is a little
+  "impolite" to leave the job of merging to someone else -- he who
+  created the two heads by pulling in some code should also normally
+  do the merging.
+  
+
+> Sometimes it's hard to keep the several DVCS workings in my mind
+  
+  It helped me a lot to think in terms of the changeset graph. Remember
+that:
+
+  * "hg commit" adds a new node. The parent changesets of the new node
+    is given by "hg parents"
+
+  * "hg push" and "hg pull" transfer nodes in the graph between two
+    repositories.
+
+  * "hg update" updates the working copy to reflect a given node in
+    the history graph. This also changes the parent changeset of the
+    next commit, see "hg parents".
+
+> Is there not a simple Mercurial cheat sheet somewhere?
+
+There are some here:
+
+http://www.selenic.com/mercurial/wiki/index.cgi/QuickReferenceCardsAndCheatSheets
+
+- Martin Geisler
+
+PS: These descriptions were written on the [Mercurial mailinglist](http://selenic.com/mailman/listinfo/mercurial). 
\ No newline at end of file