Mercurial > hg-website
diff original/hgscm/templates/quick_start.html @ 244:4b97017259f9
Move the original site into a single folder to reduce clutter.
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Wed, 23 Sep 2009 20:05:13 -0400 |
| parents | hgscm/templates/quick_start.html@c7bf003b17fd |
| children | 960885d6e884 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/original/hgscm/templates/quick_start.html Wed Sep 23 20:05:13 2009 -0400 @@ -0,0 +1,153 @@ +{% extends "base.html" %} + +{% load extras %} +{% block content %} + +<div class="row"> + <div class="col big"> +<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 > 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 them: 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 into 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>hg serve</hg> 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 <john@example.com> + +</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 class="undecorated_list"> +<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> +<pre><code>C1 --> C2 --> C3 + +</code></pre> +<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 --> C2' --> 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> /-> C2 --> C3 +C1 -< + \-> C2' --> 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> /-> C2 --> C3 -\ +C1 -< >-> M + \-> C2' --> 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> + +</div> + <div class="col"> + {% download_button %} + {% mercurial_tricks %} + {% mercurial_tricks_advanced %} + </div> +</div> + +{% endblock %}