Differences between revisions 5 and 59 (spanning 54 versions)
⇤ ← Revision 5 as of 2006-12-19 05:30:27 →
Size: 4817
Editor: mpm
Comment:
← Revision 59 as of 2013-08-31 15:11:03 → ⇥
Size: 10233
Editor: KevinBot
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 illustate some of the basic concepts.
See the ["Tutorial"] for step-by-step instructions.

[[TableOfContents]]

== What's in a Repository ==

Mercurial repositories contain a working directory coupled with a store:		 #pragma section-numbers 2
= Understanding Mercurial =
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.

<<TableOfContents>>

== What's in a repository ==
Mercurial [[Repository|repositories]] contain a [[WorkingDirectory|working directory]] coupled with a store:
Line 12: Line 12:
 rankdir = BT  rankdir = LR;
 compound=true;
Line 15: Line 16:
  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 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 [[.hgignore|ignored files]] are revision-controlled, they are also included.

== Committing changes ==
When you [[Cmd:commit|commit]], the state of the working directory relative to its parents is recorded as a new [[ChangeSet|changeset]] (also called a new "[[Revision|revision]]"):

{{{#!dot
digraph G {
 compound=true;
 rankdir = LR
 background="#999999";
 subgraph cluster_0 {
  label="working directory";
Line 20: Line 53:
  label="working directory";
Line 23: Line 55:
  label = "store";
  labelloc = b;
Line 26: Line 60:
  "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.

== Revisions, Changesets, Heads, and Tip ==

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)"
   label="example history"
}
}}}

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, Merging, and Pulling ==

Let's start with a user Alice, who has a store that looks like:

{{{#!dot
digraph {
   label="Alice's Repo"
   rankdir = LR
   node [shape=box]
   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
   e [color=blue]
   f [color=blue]
}
}}}

Alice then makes her own change in parallel:

{{{#!dot
digraph {
   label="Alice's Repo"
   rankdir = LR
   node [shape=box]
   a->b->c->d->g
   g [color=red]
}
}}}

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
   g [color=red;label="g (tip)"]
}
}}}

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
   g [color=red]
   f->h
   g->h		   "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'''.

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

{{{#!dot
digraph {
   rankdir = LR
   node [shape=record]
   rev0 [label="{{<p1> p1 | <p2> p2} | rev 0:838e}"];
   rev1 [label="{{<p1> p1 | <p2> p2} | rev 1:34ef}"];
   rev2 [label="{{<p1> p1 | <p2> p2} | rev 2:4563}"];
   rev3 [label="{{<p1> p1 | <p2> p2} | rev 3:fe56}"];
   rev4 [label="{{<p1> p1 | <p2> p2} | rev 4:ac98}"];
   rev5 [label="{{<p1> p1 | <p2> p2} | rev 5:0345}"];
   rev6 [label="{{<p1> p1 | <p2> p2} | rev 6:19e3 (tip)}"];
   workingdir [label="{{<p1> p1 | <p2> p2} | working directory}"];
   rev0 -> rev1:p1 [dir=back]
   rev1 -> rev2:p1 [dir=back]
   rev1 -> rev3:p1 [dir=back]
   rev2 -> rev4:p1 [dir=back]
   rev3 -> rev4:p2 [dir=back]
   rev4 -> rev5:p1 [dir=back]
   rev4 -> rev6:p1 [dir=back]
   rev6 -> workingdir:p1 [dir=back]
   label="example repository"
}
}}}
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 [[MergeChangeset|merge changeset]], as it has ''two'' parent changesets (revisions 2 and 3).

== Cloning, making changes, merging, pulling and updating ==
Let's start with a user Alice, who has a repository that looks like:

{{{#!dot
digraph {
   label="Alice's repo"
   rankdir = LR
   node [shape=box]
   a -> b -> c -> d -> "working dir" [dir=back]
}
}}}
Bob clones this repo, and ends up with a complete, independent, local copy of Alice's store and a clean checkout of the tipmost revision d in his working directory:

{{{#!dot
digraph {
   label="Bob's repo"
   rankdir = LR
   node [shape=box]
   a -> b -> c -> d -> "working dir" [dir=back]
}
}}}
Bob can now work independently of Alice. He then commits two changes e and f:

{{{#!dot
digraph {
   label="Bob's repo"
   rankdir = LR
   node [shape=box]
   a -> b -> c -> d -> e -> f -> "working dir" [dir=back]
   e [color=blue]
   f [color=blue]
}
}}}
Alice then makes her own change g in parallel, which causes her repository store to diverge from Bob's, thus creating a [[Branch|branch]]:

{{{#!dot
digraph {
   label="Alice's repo"
   rankdir = LR
   node [shape=box]
   a -> b -> c -> d -> g -> "working dir" [dir=back]
   g [color=red]
}
}}}
Bob then pulls Alice's repo to synchronize. This copies all of Alice's changes into Bob's repository store (here, it's just a single change g). Note that Bob's working directory is '''not''' changed by the pull:

{{{#!dot
digraph {
   label="Bob's repo"
   rankdir = LR
   node [shape=box]
   a -> b -> c -> d -> e -> f -> "working dir" [dir=back]
   e [color=blue]
   f [color=blue]
   d -> g [dir=back]
   g [color=red, label="g (tip)"]
}
}}}
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 in his repository. Now, his working directory has two parent revisions (f and g):

{{{#!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]
   g [color=red]
   f -> "working dir" [dir=back, weight=3.0]
   g -> "working dir" [dir=back, weight=3.0]
}
}}}
After examining the result of the merge in his working directory and making sure the merge is perfect, Bob commits the result and ends up with a new [[MergeChangeset|merge changeset]] h in his store:

{{{#!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]
   g [color=red]
   f -> h [dir=back, weight=3.0]
   g -> h [dir=back, weight=3.0]
   h -> "working dir" [dir=back]
   h [color=green, label="h (tip)"]
}
}}}
Now if Alice '''pulls''' from Bob, she will get Bob's changes e, f, and h into her store:

{{{#!dot
digraph {
   label="Alice'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]
   g [color=red]
   f -> h [dir=back, weight=3.0]
   g -> h [dir=back, weight=3.0]
   g -> "working dir" [dir=back]
Line 140: Line 209:

Now if Alice '''pulls''' from Bob, she will get Bob's changes e, f, and h, and they will be fully synchronized:

{{{#!dot
digraph {
   label="Alice's Repo"
   rankdir = LR
   node [shape=box]
   a->b->c->d->g
   d->e->f
   e [color=blue]
   f [color=blue]
   g [color=red]
   f->h
   g->h
   h [color=green;label="h (tip)"]
}
}}}

== 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:		 Note that Alice's working directory was not changed by the pull. She has to do an [[Update|update]] to synchronize her working directory to the merge changset h. This changes the parent changeset of her working directory to changeset h and updates the files in her working directory to revision h.

{{{#!dot
digraph {
   label="Alice'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]
   g [color=red]
   f -> h [dir=back, weight=3.0]
   g -> h [dir=back, weight=3.0]
   h -> "working dir" [dir=back]
   h [color=green, label="h (tip)"]
}
}}}
Now Alice and Bob are fully synchronized again.

== 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):
Line 180: Line 249:
Unlike a centralized version control system in which experimentation can be disastrous, with a DVCS like Mercurial, you just clone and experiment. If you like the results, push them back, otherwise wipe the cloned repository and try something else.

== What Mercurial can't do ==
Many SVN/CVS users expect to host related projects together in one repository. This is really not what Mercurial was made for, so you should try a different way of working. In particular, this 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 [[Subrepository|Subrepositories]] feature that was introduced with Mercurial 1.3 or the older ForestExtension.

For a hands-on introduction to using Mercurial, see the [[Tutorial]].

----
[[BrazilianPortugueseUnderstandingMercurial|Brazilian Portuguese]], [[CzechUnderstandingMercurial|Czech]], [[GermanUnderstandingMercurial|Deutsch]], [[FrenchUnderstandingMercurial|Français]], [[ItalianUnderstandingMercurial|Italiano]], [[RussianUnderstandingMercurial|Russian]], [[SpanishUnderstandingMercurial|Spanish]], [[ThaiUnderstandingMercurial|Thai]], [[ChineseUnderstandingMercurial|中文]], [[JapaneseUnderstandingMercurial|日本語]], [[KoreanUnderstandingMercurial|한국어]]

Understanding Mercurial

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.

Contents

  1. What's in a repository
  2. Committing changes
  3. Revisions, changesets, heads, and tip
  4. Cloning, making changes, merging, pulling and updating
  5. A decentralized system
  6. What Mercurial can't do

1. What's in a repository

Mercurial repositories contain a working directory coupled with a store:

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.

The working directory contains a copy of the project's files at a given point in time (eg rev 2), ready for editing. Because tags and ignored files are revision-controlled, they are also included.

2. Committing changes

When you commit, the state of the working directory relative to its parents is recorded as a new changeset (also called a new "revision"):

Note here that revision 4 is a branch of revision 2, which was the revision in the working directory. Now revision 4 is the working directory's parent.

3. Revisions, changesets, heads, and tip

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

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. Revision 4 is a merge changeset, as it has two parent changesets (revisions 2 and 3).

4. Cloning, making changes, merging, pulling and updating

Let's start with a user Alice, who has a repository that looks like:

Bob clones this repo, and ends up with a complete, independent, local copy of Alice's store and a clean checkout of the tipmost revision d in his working directory:

Bob can now work independently of Alice. He then commits two changes e and f:

Alice then makes her own change g in parallel, which causes her repository store to diverge from Bob's, thus creating a branch:

Bob then pulls Alice's repo to synchronize. This copies all of Alice's changes into Bob's repository store (here, it's just a single change g). Note that Bob's working directory is not changed by the pull:

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 in his repository. Now, his working directory has two parent revisions (f and g):

After examining the result of the merge in his working directory and making sure the merge is perfect, Bob commits the result and ends up with a new merge changeset h in his store:

Now if Alice pulls from Bob, she will get Bob's changes e, f, and h into her store:

Note that Alice's working directory was not changed by the pull. She has to do an update to synchronize her working directory to the merge changset h. This changes the parent changeset of her working directory to changeset h and updates the files in her working directory to revision h.

Now Alice and Bob are fully synchronized again.

5. 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):

Unlike a centralized version control system in which experimentation can be disastrous, with a DVCS like Mercurial, you just clone and experiment. If you like the results, push them back, otherwise wipe the cloned repository and try something else.

6. What Mercurial can't do

Many SVN/CVS users expect to host related projects together in one repository. This is really not what Mercurial was made for, so you should try a different way of working. In particular, this 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 Subrepositories feature that was introduced with Mercurial 1.3 or the older ForestExtension.

For a hands-on introduction to using Mercurial, see the Tutorial.

Brazilian Portuguese, Czech, Deutsch, Français, Italiano, Russian, Spanish, Thai, 中文, 日本語, 한국어

UnderstandingMercurial (last edited 2013-09-02 20:00:50 by WagnerBruna)