| 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@102
|
47 \subsection{Head changesets}
|
|
bos@102
|
48
|
|
bos@99
|
49 A head is a change that has no descendants, or children, as they're
|
|
bos@99
|
50 also known. The tip revision is thus a head, because the newest
|
|
bos@99
|
51 revision in a repository doesn't have any children, but a repository
|
|
bos@99
|
52 can contain more than one head.
|
|
bos@99
|
53
|
|
bos@99
|
54 \begin{figure}[ht]
|
|
bos@99
|
55 \centering
|
|
bos@99
|
56 \grafix{tour-merge-pull}
|
|
bos@99
|
57 \caption{Repository contents after pulling from \dirname{my-hello} into
|
|
bos@99
|
58 \dirname{my-new-hello}}
|
|
bos@99
|
59 \label{fig:tour-merge:pull}
|
|
bos@99
|
60 \end{figure}
|
|
bos@99
|
61
|
|
bos@99
|
62 In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
|
|
bos@99
|
63 pull from \dirname{my-hello} into \dirname{my-new-hello}. The history
|
|
bos@99
|
64 that was already present in \dirname{my-new-hello} is untouched, but a
|
|
bos@99
|
65 new revision has been added. By referring to
|
|
bos@99
|
66 figure~\ref{fig:tour-merge:sep-repos}, we can see that the
|
|
bos@99
|
67 \emph{changeset ID} remains the same in the new repository, but the
|
|
bos@99
|
68 \emph{revision number} has changed. (This, incidentally, is a fine
|
|
bos@99
|
69 example of why it's not safe to use revision numbers when discussing
|
|
bos@99
|
70 changesets.) We can view the heads in a repository using the
|
|
bos@99
|
71 \hgcmd{heads} command.
|
|
bos@94
|
72 \interaction{tour.merge.heads}
|
|
bos@102
|
73
|
|
bos@102
|
74 \subsection{Performing the merge}
|
|
bos@102
|
75
|
|
bos@94
|
76 What happens if we try to use the normal \hgcmd{update} command to
|
|
bos@94
|
77 update to the new tip?
|
|
bos@94
|
78 \interaction{tour.merge.update}
|
|
bos@94
|
79 Mercurial is telling us that the \hgcmd{update} command won't do a
|
|
bos@100
|
80 merge; it won't update the working directory when it thinks we might
|
|
bos@100
|
81 be wanting to do a merge, unless we force it to do so. Instead, we
|
|
bos@100
|
82 use the \hgcmd{merge} command to merge the two heads.
|
|
bos@94
|
83 \interaction{tour.merge.merge}
|
|
bos@100
|
84
|
|
bos@100
|
85 \begin{figure}[ht]
|
|
bos@100
|
86 \centering
|
|
bos@100
|
87 \grafix{tour-merge-merge}
|
|
bos@100
|
88 \caption{Working directory and repository during merge, and
|
|
bos@100
|
89 following commit}
|
|
bos@100
|
90 \label{fig:tour-merge:merge}
|
|
bos@100
|
91 \end{figure}
|
|
bos@100
|
92
|
|
bos@94
|
93 This updates the working directory so that it contains changes from
|
|
bos@100
|
94 \emph{both} heads, which is reflected in both the output of
|
|
bos@100
|
95 \hgcmd{parents} and the contents of \filename{hello.c}.
|
|
bos@94
|
96 \interaction{tour.merge.parents}
|
|
bos@102
|
97
|
|
bos@102
|
98 \subsection{Committing the results of the merge}
|
|
bos@102
|
99
|
|
bos@94
|
100 Whenever we've done a merge, \hgcmd{parents} will display two parents
|
|
bos@94
|
101 until we \hgcmd{commit} the results of the merge.
|
|
bos@94
|
102 \interaction{tour.merge.commit}
|
|
bos@94
|
103 We now have a new tip revision; notice that it has \emph{both} of
|
|
bos@94
|
104 our former heads as its parents. These are the same revisions that
|
|
bos@94
|
105 were previously displayed by \hgcmd{parents}.
|
|
bos@94
|
106 \interaction{tour.merge.tip}
|
|
bos@101
|
107 In figure~\ref{fig:tour-merge:merge}, you can see a representation of
|
|
bos@101
|
108 what happens to the working directory during the merge, and how this
|
|
bos@101
|
109 affects the repository when the commit happens. During the merge, the
|
|
bos@101
|
110 working directory has two parent changesets, and these become the
|
|
bos@101
|
111 parents of the new changeset.
|
|
bos@94
|
112
|
|
bos@102
|
113 \section{Merging conflicting changes}
|
|
bos@102
|
114
|
|
bos@102
|
115 Most merges are simple affairs, but sometimes you'll find yourself
|
|
bos@102
|
116 merging a change that you made with another, where both modify the
|
|
bos@102
|
117 same portions of the same files. Unless both modifications are
|
|
bos@102
|
118 identical, this results in a \emph{conflict}, where you have to decide
|
|
bos@102
|
119 how to reconcile the different changes into something coherent.
|
|
bos@102
|
120
|
|
bos@102
|
121 \section{Using an extension to simplify merging}
|
|
bos@102
|
122
|
|
bos@102
|
123 The process of merging changes as outlined above is straightforward,
|
|
bos@102
|
124 but requires running three commands in sequence.
|
|
bos@102
|
125 \begin{codesample2}
|
|
bos@102
|
126 hg pull
|
|
bos@102
|
127 hg merge
|
|
bos@102
|
128 hg commit -m 'Merged remote changes'
|
|
bos@102
|
129 \end{codesample2}
|
|
bos@102
|
130 In the case of the final commit, you also need to come up with a
|
|
bos@102
|
131 commit message, which is almost always going to be a piece of
|
|
bos@102
|
132 uninteresting ``boilerplate'' text.
|
|
bos@102
|
133
|
|
bos@102
|
134 It would be nice to reduce the number of steps needed, if this were
|
|
bos@102
|
135 possible. Indeed, Mercurial is distributed with an extension called
|
|
bos@102
|
136 \hgext{fetch} that does just this.
|
|
bos@102
|
137
|
|
bos@102
|
138 Mercurial provides a flexible extension mechanism that lets people
|
|
bos@102
|
139 extend its functionality, while keeping the core of Mercurial small
|
|
bos@102
|
140 and easy to deal with. Some extensions add new commands that you can
|
|
bos@102
|
141 use from the command line, while others work ``behind the scenes,''
|
|
bos@102
|
142 for example adding capabilities to the server.
|
|
bos@102
|
143
|
|
bos@102
|
144 The \hgext{fetch} extension adds a new command called, not
|
|
bos@102
|
145 surprisingly, \hgcmd{fetch}. This extension acts as a combination of
|
|
bos@102
|
146 \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling
|
|
bos@102
|
147 changes from another repository into the current repository. If it
|
|
bos@102
|
148 finds that the changes added a new head to the repository, it begins a
|
|
bos@102
|
149 merge, then commits the result of the merge with an
|
|
bos@102
|
150 automatically-generated commit message. If no new heads were added,
|
|
bos@102
|
151 it updates the working directory to the new tip changeset.
|
|
bos@102
|
152
|
|
bos@102
|
153 Enabling the \hgext{fetch} extension is easy. Edit your
|
|
bos@102
|
154 \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
|
|
bos@102
|
155 or create an \rcsection{extensions} section. Then add a line that
|
|
bos@102
|
156 simply reads ``\Verb+fetch +''.
|
|
bos@102
|
157 \begin{codesample2}
|
|
bos@102
|
158 [extensions]
|
|
bos@102
|
159 fetch =
|
|
bos@102
|
160 \end{codesample2}
|
|
bos@102
|
161 (Normally, on the right-hand side of the ``\texttt{=}'' would appear
|
|
bos@102
|
162 the location of the extension, but since the \hgext{fetch} extension
|
|
bos@102
|
163 is in the standard distribution, Mercurial knows where to search for
|
|
bos@102
|
164 it.)
|
|
bos@102
|
165
|
|
bos@84
|
166 %%% Local Variables:
|
|
bos@84
|
167 %%% mode: latex
|
|
bos@84
|
168 %%% TeX-master: "00book"
|
|
bos@84
|
169 %%% End:
|
