Commits

Arne Babenhauserheide  committed 3989294 Merge

Turned the quick start into HTML

  • Participants
  • Parent commits b96a398, e25c49f

Comments (0)

Files changed (2)

File hgscm/templates/quick_start.html

+<h1>Quick Start</h1>
+<p><em>How to get going at once.</em></p>
+<h2>Part 0: Instant usage</h2>
+<p><em>(you know this from the main page)</em></p>
+<p>Clone a project and create a patch </p>
+<pre><code>$ hg clone http://hg-scm.org/hello
+$ cd hello
+$ (edit files)
+$ hg add (new files)
+$ hg commit -m 'My changes'
+$ hg export tip &gt; patch.diff
+</code></pre>
+<p>Create a project and commit </p>
+<pre><code>$ hg init (project-directory)
+$ cd (project-directory)
+$ (add some files)
+$ hg add
+$ hg commit -m 'Initial commit'
+</code></pre>
+<h2>Part 1: Using Mercurial</h2>
+<p>Aside from the practical Quick Start above, there are only a few commands you need to start working. </p>
+<p>Even if you stick to these basics, Mercurial is quite powerful. And they are very easy to use, once you see the model behind that: Each repository has the whole history, and history is not necessarily linear (part 2 explains that model in a bit more detail). </p>
+<p>A quick overview of the basic commands: </p>
+<ul>
+<li>hg init: create a new repository
+</li><li>hg commit: save your changes in the current repository
+</li><li>hg log: see all changes in your repository
+</li><li>hg pull: get all changes from another repository int the current one
+</li><li>hg push: get all changes from your repository into another one
+</li><li>hg serve: create an instant-webserver. People can see the history there and pull from it
+</li><li>hg merge: join different lines of history
+</li>
+</ul>
+<p>If you want to see a nice graph of the history, just do "hg serve" in your repository and then direct your browser to </p>
+<pre><code>    http://127.0.0.1:8000
+</code></pre>
+<p>This also helps getting a feeling for what the commands do. </p>
+<p>(you can also do a lot of finegrained stuff by using different command options. Just call "hg help <command>" to see them). </p>
+<p>One step you'll likely want to do is setting your username in your Mercurial config file. </p>
+<p>For this you can configure a proper name and email address in ~/.hgrc (or on a Windows system in %USERPROFILE%Mercurial.ini) by adding lines such as the following: </p>
+<pre><code>[ui]
+username = John Doe &lt;john@example.com&gt;
+</code></pre>
+<p>I you want more than this quick overview, please have a look at our longer <a href="{% url workflow_guide %}">practical guide</a>. </p>
+<h2>Part 2: Understanding Mercurial in 6 steps</h2>
+<p>Now we'll look at some of the basic concepts of Mercurial to get a better understanding of its internals: </p>
+<ol>
+<li>
+<p>Like in Subversion, history consists of a number of commits. They're
+  called changesets in Mercurial.</p>
+
+</li><li>
+<p>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, N+1. This is simple, but it requires a central server to make sure that
+  everybody agrees on the revision numbers.</p>
+
+</li><li>
+<p>Mercurial generalizes this by letting each changeset have multiple
+  children. If I work alone and make commits I'll make</p>
+<p>C1 --&gt; C2 --&gt; C3</p>
+<p>by making three commits. </p>
+
+  <p>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:</p>
+<pre><code>C1 --&gt; C2' --&gt; C3'
+</code></pre>
+<p>Here C3' is a head in your repository and I don't know anything
+  about C2' and C3' yet.</p>
+
+</li><li>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.
+<p>After a pull from you my repository will look like this:</p>
+<pre><code>     /-&gt; C2 --&gt; C3
+C1 -&lt;
+     \-&gt; C2' --&gt; C3'
+</code></pre>
+<p>Here C1 has two child changesets, and the repository has two heads
+  since the development has diverged.</p>
+<p>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.</p>
+
+</li><li>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.
+<p>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:</p>
+<pre><code>     /-&gt; C2 --&gt; C3   -\
+C1 -&lt;                  &gt;-&gt; M
+     \-&gt; C2' --&gt; C3' -/
+</code></pre>
+<p>Note that the merge changeset M has two parents.</p>
+<p>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.
+</p>
+</li><li>
+<p>It helped my understanding a lot to think in terms of the changeset graph. Just remember that:</p>
+<ul><li>
+<p>"hg commit" adds a new node. The parent changesets of the new node
+    is given by "hg parents"</p>
+
+</li><li>
+<p>"hg push" and "hg pull" transfer nodes in the graph between two
+    repositories.</p>
+
+</li><li>
+<p>"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".</p>
+</li>
+</ul>
+</ol>
+
+<p>And if you want to quickly look up something, you can use one of the <a href="http://www.selenic.com/mercurial/wiki/index.cgi/QuickReferenceCardsAndCheatSheets">Mercurial cheatsheets</a>. </p>
+<p><em>Compiled from a great email by Martin Geisler.</em></p>

File text/quick_start.txt

-= Quick Start =
-
-*This site should get you going at once. You can find a slightly longer quick_start [in the wiki](http://mercurial.selenic.com/wiki/QuickStart)*
-
-== Part 0: Instant usage ==
-
-*(you know this from the main page)*
-
-Clone a project and create a patch 
-
-$ hg clone http://hg-scm.org/hello
-$ cd hello
-$ (edit files)
-$ hg add (new files)
-$ hg commit -m 'My changes'
-$ hg export tip > patch.diff
-
-
-Create a project and commit 
-
-$ hg init (project-directory)
-$ cd (project-directory)
-$ (add some files)
-$ hg add
-$ hg commit -m 'Initial commit'
-
-
-== Part 1: Using Mercurial ==
-
-Aside from the practical Quick Start above, there are only a few commands you need to start working. 
-
-Even if you stick to these basics, Mercurial is quite powerful. And they are very easy to use, once you see the model behind that: Each repository has the whole history, and history is not necessarily linear (part 2 explains that model in a bit more detail). 
-
-A quick overview of the basic commands: 
-
-- hg init: create a new repository
-- hg commit: save your changes in the current repository
-- hg log: see all changes in your repository
-- hg pull: get all changes from another repository int the current one
-- hg push: get all changes from your repository into another one
-- hg serve: create an instant-webserver. People can see the history there and pull from it
-- hg 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 also do a lot of finegrained stuff by using different command options. Just call "hg help <command>" to see them). 
-
-One step you'll likely want to do is setting your username in your Mercurial config file. 
-
-For this you can configure a proper name and email address in ~/.hgrc (or on a Windows system in %USERPROFILE%\Mercurial.ini) by adding lines such as the following: 
-
-    [ui]
-    username = John Doe <john@example.com>
-
-I you want more than this quick overview, please have a look at our longer [practical guide]({% url workflow_guide %}). 
-
-== Part 2: Understanding Mercurial ==
-
-Now we'll look at some of the basic concepts of Mercurial to get a better understanding of its internals: 
-
-* 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, N+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.  
-
-
-It helped my understanding a lot to think in terms of the changeset graph. Just 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".
-
-
-And you want to quickly look up something, you can use one of the [Mercurial cheatsheets](http://www.selenic.com/mercurial/wiki/index.cgi/QuickReferenceCardsAndCheatSheets). 
-
-*compiled from a great email by Martin Geisler*