Mercurial > hg-website
changeset 204:3989294c82e4
Turned the quick start into HTML
| author | Arne Babenhauserheide <bab@draketo.de> |
|---|---|
| date | Thu, 02 Jul 2009 14:42:04 +0200 |
| parents | b96a398de44c (diff) e25c49f3fe47 (current diff) |
| children | 88364e82ca61 |
| files | hgscm/templates/quick_start.html text/quick_start.txt |
| diffstat | 3 files changed, 116 insertions(+), 128 deletions(-) [+] |
line wrap: on
line diff
--- a/Todo.txt Sat Jun 27 06:44:24 2009 -0400 +++ b/Todo.txt Thu Jul 02 14:42:04 2009 +0200 @@ -12,8 +12,8 @@ Currently in the works: -* quick_start - bab -* learn_mercurial (links to different resources with short descriptions) - bab +* quick_start - bab, concept written in text/ +* learn_mercurial (links to different resources with short descriptions) - bab, concept written in text/ Done:
--- a/hgscm/templates/quick_start.html Sat Jun 27 06:44:24 2009 -0400 +++ b/hgscm/templates/quick_start.html Thu Jul 02 14:42:04 2009 +0200 @@ -1,141 +1,125 @@ -Quick Start -=========== - -*How to get going at once.* - -## 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: +<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 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 <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> +<li> +<p>Like in Subversion, history consists of a number of commits. They're + called changesets in Mercurial.</p> -- 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). - -I you want more than this quick overview, please have a look at our longer [practical guide]({% url workflow_guide %}). - -## Part 2: Understanding Mercurial from Subversion - -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. +</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> -* 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 +</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 --> C2 --> C3</p> +<p>by making three commits. </p> - 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: + <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> - 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 +</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. - - After a pull from you my repository will look like this: - - /-> C2 --> C3 - C1 -< - \-> C2' --> C3' +<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> - 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 +</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. - - When merging with 'hg merge' the task is to figure out the canonical +<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: - - /-> 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 + 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. - - -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" + 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> - * "hg push" and "hg pull" transfer nodes in the graph between two - repositories. +</li><li> +<p>"hg push" and "hg pull" transfer nodes in the graph between two + repositories.</p> - * "hg update" updates the working copy to reflect a given node in +</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". - + next commit, see "hg parents".</p> +</li> +</ul> +</ol> -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* +<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> \ No newline at end of file
--- a/text/learn_mercurial.txt Sat Jun 27 06:44:24 2009 -0400 +++ b/text/learn_mercurial.txt Thu Jul 02 14:42:04 2009 +0200 @@ -2,14 +2,18 @@ *Here you can find links to resources for learning Mercurial* -* Quick_Start (instant Mercurial, this site) +* Quick_Start + Get started using Mercurial and understanding its basic concepts. -* Quick_Start from wiki (learn the basics) +* Quick_Start from wiki: http://mercurial.selenic.com/wiki/QuickStart + Learn the basic Mercurial commands. A bit more verbose than the short quick start above. (* TortoiseHG basics (For the Mercurial GUI) - when acessed from a windows box) -* workflow_guide (learn using Mercurial step by step) +* workflow_guide + Learn using Mercurial step by step in workflows. This guide skips the conceptual explanations to focus only on the practical usage. -* hgbook (an in depth look into Mercurial "This book from ... gives a detailed and easy to read introduction to Mercurial and the philosophy behind it. It goes from the basic to advanced topics like Mercurial Queues for patch management") +* hgbook + The free book from Brian o Sullivan gives a detailed and easy to read introduction to Mercurial and the philosophy behind it. -* Other resources (links in the wiki, publicly editable. If you wrote some guide yourself, maybe for your team or for friends of yours, please add it!) +(* Other resources (links in the wiki, publicly editable. If you wrote some guide yourself, maybe for your team or for friends of yours, please add it!) - it might be useful to have such a page in the wiki! )