# HG changeset patch # User Arne Babenhauserheide # Date 1246538524 -7200 # Node ID 3989294c82e4961f1ef2a78d60cbdd6a14388f27 # Parent b96a398de44cf102da82264221d076c130151fe2# Parent e25c49f3fe476d6a4f492b2e8efd95a65a84a882 Turned the quick start into HTML diff -r b96a398de44c -r 3989294c82e4 hgscm/templates/quick_start.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/hgscm/templates/quick_start.html Thu Jul 02 14:42:04 2009 +0200 @@ -0,0 +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:

+ +

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 " 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.

+

Part 2: Understanding Mercurial in 6 steps

+

Now we'll look at some of the basic concepts of Mercurial to get a better understanding of its internals:

+
    +
  1. +

    Like in Subversion, history consists of a number of commits. They're + called changesets in Mercurial.

    + +
  2. +

    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.

    + +
  3. +

    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.

    + +
  4. 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.

    + +
  5. 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. +

    +
  6. +

    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 if you want to quickly look up something, you can use one of the Mercurial cheatsheets.

+

Compiled from a great email by Martin Geisler.

\ No newline at end of file diff -r b96a398de44c -r 3989294c82e4 text/quick_start.txt --- a/text/quick_start.txt Thu Jun 25 00:27:59 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,147 +0,0 @@ -= 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 " 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 - -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*