| rev |
line source |
|
bos@95
|
1 \chapter{A tour of Mercurial: merging work}
|
|
bos@95
|
2 \label{chap:tour-merge}
|
|
bos@94
|
3
|
|
bos@94
|
4 We've now covered cloning a repository, making changes in a
|
|
bos@94
|
5 repository, and pulling or pushing changes from one repository into
|
|
bos@94
|
6 another. Our next step is \emph{merging} changes from separate
|
|
bos@94
|
7 repositories.
|
|
bos@94
|
8
|
|
bos@95
|
9 \section{Merging streams of work}
|
|
bos@95
|
10
|
|
bos@94
|
11 Merging is a fundamental part of working with a distributed revision
|
|
bos@94
|
12 control tool.
|
|
bos@94
|
13 \begin{itemize}
|
|
bos@94
|
14 \item Alice and Bob each have a personal copy of a repository for a
|
|
bos@94
|
15 project they're collaborating on. Alice fixes a bug in her
|
|
bos@94
|
16 repository; Bob adds a new feature in his. They want the shared
|
|
bos@94
|
17 repository to contain both the bug fix and the new feature.
|
|
bos@94
|
18 \item I frequently work on several different tasks for a single
|
|
bos@94
|
19 project at once, each safely isolated in its own repository.
|
|
bos@94
|
20 Working this way means that I often need to merge one piece of my
|
|
bos@94
|
21 own work with another.
|
|
bos@94
|
22 \end{itemize}
|
|
bos@94
|
23
|
|
bos@94
|
24 Because merging is such a common thing to need to do, Mercurial makes
|
|
bos@94
|
25 it easy. Let's walk through the process. We'll begin by cloning yet
|
|
bos@94
|
26 another repository (see how often they spring up?) and making a change
|
|
bos@94
|
27 in it.
|
|
bos@94
|
28 \interaction{tour.merge.clone}
|
|
bos@94
|
29 We should now have two copies of \filename{hello.c} with different
|
|
bos@99
|
30 contents. The histories of the two repositories have also diverged,
|
|
bos@99
|
31 as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
|
|
bos@94
|
32 \interaction{tour.merge.cat}
|
|
bos@94
|
33
|
|
bos@99
|
34 \begin{figure}[ht]
|
|
bos@99
|
35 \centering
|
|
bos@99
|
36 \grafix{tour-merge-sep-repos}
|
|
bos@99
|
37 \caption{Divergent recent histories of the \dirname{my-hello} and
|
|
bos@99
|
38 \dirname{my-new-hello} repositories}
|
|
bos@99
|
39 \label{fig:tour-merge:sep-repos}
|
|
bos@99
|
40 \end{figure}
|
|
bos@99
|
41
|
|
bos@94
|
42 We already know that pulling changes from our \dirname{my-hello}
|
|
bos@94
|
43 repository will have no effect on the working directory.
|
|
bos@94
|
44 \interaction{tour.merge.pull}
|
|
bos@94
|
45 However, the \hgcmd{pull} command says something about ``heads''.
|
|
bos@94
|
46
|
|
bos@99
|
47 A head is a change that has no descendants, or children, as they're
|
|
bos@99
|
48 also known. The tip revision is thus a head, because the newest
|
|
bos@99
|
49 revision in a repository doesn't have any children, but a repository
|
|
bos@99
|
50 can contain more than one head.
|
|
bos@99
|
51
|
|
bos@99
|
52 \begin{figure}[ht]
|
|
bos@99
|
53 \centering
|
|
bos@99
|
54 \grafix{tour-merge-pull}
|
|
bos@99
|
55 \caption{Repository contents after pulling from \dirname{my-hello} into
|
|
bos@99
|
56 \dirname{my-new-hello}}
|
|
bos@99
|
57 \label{fig:tour-merge:pull}
|
|
bos@99
|
58 \end{figure}
|
|
bos@99
|
59
|
|
bos@99
|
60 In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
|
|
bos@99
|
61 pull from \dirname{my-hello} into \dirname{my-new-hello}. The history
|
|
bos@99
|
62 that was already present in \dirname{my-new-hello} is untouched, but a
|
|
bos@99
|
63 new revision has been added. By referring to
|
|
bos@99
|
64 figure~\ref{fig:tour-merge:sep-repos}, we can see that the
|
|
bos@99
|
65 \emph{changeset ID} remains the same in the new repository, but the
|
|
bos@99
|
66 \emph{revision number} has changed. (This, incidentally, is a fine
|
|
bos@99
|
67 example of why it's not safe to use revision numbers when discussing
|
|
bos@99
|
68 changesets.) We can view the heads in a repository using the
|
|
bos@99
|
69 \hgcmd{heads} command.
|
|
bos@94
|
70 \interaction{tour.merge.heads}
|
|
bos@94
|
71 What happens if we try to use the normal \hgcmd{update} command to
|
|
bos@94
|
72 update to the new tip?
|
|
bos@94
|
73 \interaction{tour.merge.update}
|
|
bos@94
|
74 Mercurial is telling us that the \hgcmd{update} command won't do a
|
|
bos@100
|
75 merge; it won't update the working directory when it thinks we might
|
|
bos@100
|
76 be wanting to do a merge, unless we force it to do so. Instead, we
|
|
bos@100
|
77 use the \hgcmd{merge} command to merge the two heads.
|
|
bos@94
|
78 \interaction{tour.merge.merge}
|
|
bos@100
|
79
|
|
bos@100
|
80 \begin{figure}[ht]
|
|
bos@100
|
81 \centering
|
|
bos@100
|
82 \grafix{tour-merge-merge}
|
|
bos@100
|
83 \caption{Working directory and repository during merge, and
|
|
bos@100
|
84 following commit}
|
|
bos@100
|
85 \label{fig:tour-merge:merge}
|
|
bos@100
|
86 \end{figure}
|
|
bos@100
|
87
|
|
bos@94
|
88 This updates the working directory so that it contains changes from
|
|
bos@100
|
89 \emph{both} heads, which is reflected in both the output of
|
|
bos@100
|
90 \hgcmd{parents} and the contents of \filename{hello.c}.
|
|
bos@94
|
91 \interaction{tour.merge.parents}
|
|
bos@94
|
92 Whenever we've done a merge, \hgcmd{parents} will display two parents
|
|
bos@94
|
93 until we \hgcmd{commit} the results of the merge.
|
|
bos@94
|
94 \interaction{tour.merge.commit}
|
|
bos@94
|
95 We now have a new tip revision; notice that it has \emph{both} of
|
|
bos@94
|
96 our former heads as its parents. These are the same revisions that
|
|
bos@94
|
97 were previously displayed by \hgcmd{parents}.
|
|
bos@94
|
98 \interaction{tour.merge.tip}
|
|
bos@94
|
99
|
|
bos@84
|
100 %%% Local Variables:
|
|
bos@84
|
101 %%% mode: latex
|
|
bos@84
|
102 %%% TeX-master: "00book"
|
|
bos@84
|
103 %%% End:
|
