hgbook
view en/tour-merge.tex @ 102:ff9dc8bc2a8b
More. Merge. Stuff.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Wed Oct 18 15:47:04 2006 -0700 (2006-10-18) |
| parents | 321732566ac1 |
| children | 5b80c922ebdd |
line source
1 \chapter{A tour of Mercurial: merging work}
2 \label{chap:tour-merge}
4 We've now covered cloning a repository, making changes in a
5 repository, and pulling or pushing changes from one repository into
6 another. Our next step is \emph{merging} changes from separate
7 repositories.
9 \section{Merging streams of work}
11 Merging is a fundamental part of working with a distributed revision
12 control tool.
13 \begin{itemize}
14 \item Alice and Bob each have a personal copy of a repository for a
15 project they're collaborating on. Alice fixes a bug in her
16 repository; Bob adds a new feature in his. They want the shared
17 repository to contain both the bug fix and the new feature.
18 \item I frequently work on several different tasks for a single
19 project at once, each safely isolated in its own repository.
20 Working this way means that I often need to merge one piece of my
21 own work with another.
22 \end{itemize}
24 Because merging is such a common thing to need to do, Mercurial makes
25 it easy. Let's walk through the process. We'll begin by cloning yet
26 another repository (see how often they spring up?) and making a change
27 in it.
28 \interaction{tour.merge.clone}
29 We should now have two copies of \filename{hello.c} with different
30 contents. The histories of the two repositories have also diverged,
31 as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
32 \interaction{tour.merge.cat}
34 \begin{figure}[ht]
35 \centering
36 \grafix{tour-merge-sep-repos}
37 \caption{Divergent recent histories of the \dirname{my-hello} and
38 \dirname{my-new-hello} repositories}
39 \label{fig:tour-merge:sep-repos}
40 \end{figure}
42 We already know that pulling changes from our \dirname{my-hello}
43 repository will have no effect on the working directory.
44 \interaction{tour.merge.pull}
45 However, the \hgcmd{pull} command says something about ``heads''.
47 \subsection{Head changesets}
49 A head is a change that has no descendants, or children, as they're
50 also known. The tip revision is thus a head, because the newest
51 revision in a repository doesn't have any children, but a repository
52 can contain more than one head.
54 \begin{figure}[ht]
55 \centering
56 \grafix{tour-merge-pull}
57 \caption{Repository contents after pulling from \dirname{my-hello} into
58 \dirname{my-new-hello}}
59 \label{fig:tour-merge:pull}
60 \end{figure}
62 In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
63 pull from \dirname{my-hello} into \dirname{my-new-hello}. The history
64 that was already present in \dirname{my-new-hello} is untouched, but a
65 new revision has been added. By referring to
66 figure~\ref{fig:tour-merge:sep-repos}, we can see that the
67 \emph{changeset ID} remains the same in the new repository, but the
68 \emph{revision number} has changed. (This, incidentally, is a fine
69 example of why it's not safe to use revision numbers when discussing
70 changesets.) We can view the heads in a repository using the
71 \hgcmd{heads} command.
72 \interaction{tour.merge.heads}
74 \subsection{Performing the merge}
76 What happens if we try to use the normal \hgcmd{update} command to
77 update to the new tip?
78 \interaction{tour.merge.update}
79 Mercurial is telling us that the \hgcmd{update} command won't do a
80 merge; it won't update the working directory when it thinks we might
81 be wanting to do a merge, unless we force it to do so. Instead, we
82 use the \hgcmd{merge} command to merge the two heads.
83 \interaction{tour.merge.merge}
85 \begin{figure}[ht]
86 \centering
87 \grafix{tour-merge-merge}
88 \caption{Working directory and repository during merge, and
89 following commit}
90 \label{fig:tour-merge:merge}
91 \end{figure}
93 This updates the working directory so that it contains changes from
94 \emph{both} heads, which is reflected in both the output of
95 \hgcmd{parents} and the contents of \filename{hello.c}.
96 \interaction{tour.merge.parents}
98 \subsection{Committing the results of the merge}
100 Whenever we've done a merge, \hgcmd{parents} will display two parents
101 until we \hgcmd{commit} the results of the merge.
102 \interaction{tour.merge.commit}
103 We now have a new tip revision; notice that it has \emph{both} of
104 our former heads as its parents. These are the same revisions that
105 were previously displayed by \hgcmd{parents}.
106 \interaction{tour.merge.tip}
107 In figure~\ref{fig:tour-merge:merge}, you can see a representation of
108 what happens to the working directory during the merge, and how this
109 affects the repository when the commit happens. During the merge, the
110 working directory has two parent changesets, and these become the
111 parents of the new changeset.
113 \section{Merging conflicting changes}
115 Most merges are simple affairs, but sometimes you'll find yourself
116 merging a change that you made with another, where both modify the
117 same portions of the same files. Unless both modifications are
118 identical, this results in a \emph{conflict}, where you have to decide
119 how to reconcile the different changes into something coherent.
121 \section{Using an extension to simplify merging}
123 The process of merging changes as outlined above is straightforward,
124 but requires running three commands in sequence.
125 \begin{codesample2}
126 hg pull
127 hg merge
128 hg commit -m 'Merged remote changes'
129 \end{codesample2}
130 In the case of the final commit, you also need to come up with a
131 commit message, which is almost always going to be a piece of
132 uninteresting ``boilerplate'' text.
134 It would be nice to reduce the number of steps needed, if this were
135 possible. Indeed, Mercurial is distributed with an extension called
136 \hgext{fetch} that does just this.
138 Mercurial provides a flexible extension mechanism that lets people
139 extend its functionality, while keeping the core of Mercurial small
140 and easy to deal with. Some extensions add new commands that you can
141 use from the command line, while others work ``behind the scenes,''
142 for example adding capabilities to the server.
144 The \hgext{fetch} extension adds a new command called, not
145 surprisingly, \hgcmd{fetch}. This extension acts as a combination of
146 \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling
147 changes from another repository into the current repository. If it
148 finds that the changes added a new head to the repository, it begins a
149 merge, then commits the result of the merge with an
150 automatically-generated commit message. If no new heads were added,
151 it updates the working directory to the new tip changeset.
153 Enabling the \hgext{fetch} extension is easy. Edit your
154 \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
155 or create an \rcsection{extensions} section. Then add a line that
156 simply reads ``\Verb+fetch +''.
157 \begin{codesample2}
158 [extensions]
159 fetch =
160 \end{codesample2}
161 (Normally, on the right-hand side of the ``\texttt{=}'' would appear
162 the location of the extension, but since the \hgext{fetch} extension
163 is in the standard distribution, Mercurial knows where to search for
164 it.)
166 %%% Local Variables:
167 %%% mode: latex
168 %%% TeX-master: "00book"
169 %%% End: