|
Size: 4594
Comment:
|
Size: 8020
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| Mercurial's decentralized development model can be confusing to new users. This page attempts to illustrate some of the basic concepts. See the ["Tutorial"] for step-by-step instructions. ''(Translations: [:BrazilianPortugueseUnderstandingMercurial:Brazilian Portuguese], [:ChineseUnderstandingMercurial:Chinese], [:FrenchUnderstandingMercurial:French], [:GermanUnderstandingMercurial:German], [:ItalianUnderstandingMercurial:Italian], [:JapaneseUnderstandingMercurial:Japanese], [:KoreanUnderstandingMercurial:Korean], [:RussianUnderstandingMercurial:Russian], [:SpanishUnderstandingMercurial:Spanish] )'' [[TableOfContents]] |
|
| Line 3: | Line 21: |
| Mercurial repositories contain a working directory coupled with a store: | Mercurial [:Repository:repositories] contain a [:WorkingDirectory:working directory] coupled with a store: |
| Line 7: | Line 25: |
| rankdir = BT | rankdir = LR; compound=true; |
| Line 10: | Line 29: |
| label="working directory"; style=filled; color=lightgrey; node [style=filled,color=white]; edge [style=invis]; "main.c" -> "main.h" -> ".hgignore" -> ".hgtags"; } subgraph cluster_1 { label = "store"; labelloc = b; style=filled; color="#eeeeee"; node [shape=box, style=filled, color=lightgray]; "rev 0" -> "rev 1" -> "rev 2" -> "rev 3" [dir=back, label="parent"]; } "main.c" -> "rev 2" [ltail=cluster_0, label="parent", labeldistance=5, minlen=2]; } }}} The store contains the '''complete''' history of the project. Unlike traditional [:SCM:SCMs], where there's only one central copy of this history, every working directory is paired with a private copy of the history. This allows development to go on in parallel. The working directory contains a copy of the project's files at a given point in time (eg rev 2), ready for editing. Because [:Tag:tags] and ignored files are revision-controlled, they are also included. == Committing Changes == When you [:Commit:commit], the state of the working directory relative to its [:Parent:parents] is recorded as a new [:Revision:revision]: {{{#!dot digraph G { compound=true; rankdir = LR background="#999999"; subgraph cluster_0 { label="working directory"; |
|
| Line 15: | Line 69: |
| label="working directory"; | |
| Line 18: | Line 71: |
| label = "store"; labelloc = b; |
|
| Line 21: | Line 76: |
| "rev 0" -> "rev 1" -> "rev 2" -> "rev 3"; label = "store"; } } }}} The working directory contains a copy of the project's files at a given point in time, ready for editing. Because tags and ignored files are revision-controlled, they are also included. The store contains the '''complete''' history of the project. Unlike traditional SCMs, where there's only one central copy of this history, every working directory is paired with a private copy of the history. This allows development to go on in parallel. |
"rev 0" -> "rev 1" -> "rev 2" -> "rev 3" [dir=back]; "rev 2" -> "rev 4" [dir=back]; } "rev 2" -> ".hgtags" [dir=back, style=dotted, lhead=cluster_0, label="parent before commit"] "rev 4" -> ".hgtags" [dir=back, color=red, lhead=cluster_0, headlabel="commit", labelfontcolor=red ] } }}} Note here that revision 4 is a '''[:Branch:branch]''' of revision 2, which was the revision in the working directory. Now revision 4 is the working directory's '''parent'''. |
| Line 34: | Line 88: |
| Mercurial groups related changes to multiple files into single atomic '''changesets''', which are '''revisions''' of the whole project. These each get a sequential revision number. Because Mercurial allows distributed parallel development, these revision numbers may disagree between users. So Mercurial also assigns each revision a global '''changeset ID'''. Changeset IDs are 40-digit hexadecimal numbers, but they can be abbreviated to any unambiguous prefix, like "e38487". {{{#!dot digraph { rankdir = LR node [shape=box] "rev 0:838e" -> "rev 1:34ef" -> "rev 2:4563" "rev 1:34ef" -> "rev 3:fe56" "rev 2:4563" -> "rev 4:ac98" "rev 3:fe56" -> "rev 4:ac98" "rev 4:ac98" -> "rev 5:0345" "rev 4:ac98" -> "rev 6:19e3 (tip)" |
Mercurial groups related changes to multiple files into single atomic [:ChangeSet:changesets], which are revisions of the whole project. These each get a sequential [:RevisionNumber:revision number]. Because Mercurial allows distributed parallel development, these revision numbers may disagree between users. So Mercurial also assigns each revision a global [:ChangeSetID:changeset ID]. Changeset IDs are 40-digit hexadecimal numbers, but they can be abbreviated to any unambiguous prefix, like "e38487". {{{#!dot digraph { rankdir = LR node [shape=record] struct0 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 0:838e}"]; struct1 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 1:34ef}"]; struct2 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 2:4563}"]; struct3 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 3:fe56}"]; struct4 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 4:ac98}"]; struct5 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 5:0345}"]; struct6 [shape=record, label="{{<p0> p0 | <p1> p1} | rev 6:19e3 (tip)}"]; struct0 -> struct1:p0 [dir=back] struct1 -> struct2:p0 [dir=back] struct1 -> struct3:p0 [dir=back] struct2 -> struct4:p0 [dir=back] struct3 -> struct4:p1 [dir=back] struct4 -> struct5:p0 [dir=back] struct4 -> struct6:p0 [dir=back] |
| Line 50: | Line 112: |
Branches and merges in the revision history can occur at any point. Each unmerged branch creates a new '''head''' of the revision history. Here, revisions 5 and 6 are heads. Mercurial considers revision 6 to be the '''tip''' of the repository, the head with the highest revision number. == Cloning, Making Changes, and Pulling == |
Branches and [:Merge:merges] in the revision history can occur at any point. Each unmerged branch creates a new [:Head:head] of the revision history. Here, revisions 5 and 6 are heads. Mercurial considers revision 6 to be the [:Tip:tip] of the repository, the head with the highest revision number. Revision 4 is a merge changeset, as it has ''two'' parent changesets (revisions 2 and 3). == Cloning, Making Changes, Merging, and Pulling == |
| Line 63: | Line 125: |
| a->b->c->d } }}} Bob '''clones''' this repo, and ends up with a complete copy: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d } }}} Bob then '''commits''' a couple changes: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d->e->f |
a->b->c->d [dir=back] } }}} Bob [:Clone:clones] this repo, and ends up with a complete copy of Alice's store (though his working directory is independent!): {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d [dir=back] } }}} Bob then [:Commit:commits] a couple changes: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d->e->f [dir=back] |
| Line 98: | Line 160: |
| a->b->c->d->g | a->b->c->d->g [dir=back] |
| Line 103: | Line 165: |
| Bob then '''pulls''' Alice's repo to synchronize. This copies all of Alice's changes into Bob's repo: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d->e->f e [color=blue] f [color=blue] d->g |
Bob then [:Pull:pulls] Alice's repo to synchronize. This copies all of Alice's changes into Bob's repo: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d->e->f [dir=back] e [color=blue] f [color=blue] d->g [dir=back] |
| Line 118: | Line 180: |
| Because Alice's '''g''' is the newest head in Bob's repository, it's now the '''tip'''. Bob then does a merge which combines the last change he was working on ('''f''') with the tip, commits the result, and ends up with: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d->e->f e [color=blue] f [color=blue] d->g |
Because Alice's '''g''' is the newest head in Bob's repository, it's now the '''tip'''. Bob then does a [:Merge:merge] which combines the last change he was working on ('''f''') with the tip, commits the result, and ends up with: {{{#!dot digraph { label="Bob's Repo" rankdir = LR node [shape=box] a->b->c->d->e->f [dir=back] e [color=blue] f [color=blue] d->g [dir=back] |
| Line 130: | Line 192: |
| f->h g->h |
f->h [dir=back, weight=3.0] g->h [dir=back, weight=3.0] |
| Line 143: | Line 205: |
| a->b->c->d->g d->e->f e [color=blue] f [color=blue] |
a->b->c->d->e->f [dir=back] e [color=blue] f [color=blue] d->g [dir=back] |
| Line 148: | Line 210: |
| f->h g->h |
f->h [dir=back, weight=3.0] g->h [dir=back, weight=3.0] |
| Line 156: | Line 218: |
| Mercurial is a completely decentralized system, and thus has no internal notion of a central repository. Thus users are free to define their own topologies for sharing changes: | Mercurial is a completely decentralized system, and thus has no internal notion of a central repository. Thus users are free to define their own topologies for sharing changes (see CommunicatingChanges): |
| Line 175: | Line 237: |
== What Mercurial can't do == Many SVN/CVS users expect to host related projects together in one repository. This is really not what hg was made for, so you should try a different way of working. This especially means, that you cannot check out only one directory of a repository. If you absolutely need to host multiple projects in a kind of meta-repository though, you could try the ForestExtension. For a hands-on introduction to using Mercurial, see the ["Tutorial"]. |
Mercurial's decentralized development model can be confusing to new users. This page attempts to illustrate some of the basic concepts. See the ["Tutorial"] for step-by-step instructions.
(Translations: [:BrazilianPortugueseUnderstandingMercurial:Brazilian Portuguese], [:ChineseUnderstandingMercurial:Chinese], [:FrenchUnderstandingMercurial:French], [:GermanUnderstandingMercurial:German], [:ItalianUnderstandingMercurial:Italian], [:JapaneseUnderstandingMercurial:Japanese], [:KoreanUnderstandingMercurial:Korean], [:RussianUnderstandingMercurial:Russian], [:SpanishUnderstandingMercurial:Spanish] )
What's in a Repository
Mercurial [:Repository:repositories] contain a [:WorkingDirectory:working directory] coupled with a store:
The store contains the complete history of the project. Unlike traditional [:SCM:SCMs], where there's only one central copy of this history, every working directory is paired with a private copy of the history. This allows development to go on in parallel.
The working directory contains a copy of the project's files at a given point in time (eg rev 2), ready for editing. Because [:Tag:tags] and ignored files are revision-controlled, they are also included.
Committing Changes
When you [:Commit:commit], the state of the working directory relative to its [:Parent:parents] is recorded as a new [:Revision:revision]:
Note here that revision 4 is a [:Branch:branch] of revision 2, which was the revision in the working directory. Now revision 4 is the working directory's parent.
Revisions, Changesets, Heads, and Tip
Mercurial groups related changes to multiple files into single atomic [:ChangeSet:changesets], which are revisions of the whole project. These each get a sequential [:RevisionNumber:revision number]. Because Mercurial allows distributed parallel development, these revision numbers may disagree between users. So Mercurial also assigns each revision a global [:ChangeSetID:changeset ID]. Changeset IDs are 40-digit hexadecimal numbers, but they can be abbreviated to any unambiguous prefix, like "e38487".
Branches and [:Merge:merges] in the revision history can occur at any point. Each unmerged branch creates a new [:Head:head] of the revision history. Here, revisions 5 and 6 are heads. Mercurial considers revision 6 to be the [:Tip:tip] of the repository, the head with the highest revision number. Revision 4 is a merge changeset, as it has two parent changesets (revisions 2 and 3).
Cloning, Making Changes, Merging, and Pulling
Let's start with a user Alice, who has a store that looks like:
Bob [:Clone:clones] this repo, and ends up with a complete copy of Alice's store (though his working directory is independent!):
Bob then [:Commit:commits] a couple changes:
Alice then makes her own change in parallel:
Bob then [:Pull:pulls] Alice's repo to synchronize. This copies all of Alice's changes into Bob's repo:
Because Alice's g is the newest head in Bob's repository, it's now the tip. Bob then does a [:Merge:merge] which combines the last change he was working on (f) with the tip, commits the result, and ends up with:
Now if Alice pulls from Bob, she will get Bob's changes e, f, and h, and they will be fully synchronized:
A Decentralized System
Mercurial is a completely decentralized system, and thus has no internal notion of a central repository. Thus users are free to define their own topologies for sharing changes (see CommunicatingChanges):
What Mercurial can't do
Many SVN/CVS users expect to host related projects together in one repository. This is really not what hg was made for, so you should try a different way of working. This especially means, that you cannot check out only one directory of a repository. If you absolutely need to host multiple projects in a kind of meta-repository though, you could try the ForestExtension.
For a hands-on introduction to using Mercurial, see the ["Tutorial"].