hgbook
view en/tour-merge.tex @ 100:272146fab009
Add yet another illustration of the merge process.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Wed Oct 18 12:06:56 2006 -0700 (2006-10-18) |
| parents | 06383f9e46e4 |
| children | 321732566ac1 |
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 A head is a change that has no descendants, or children, as they're
48 also known. The tip revision is thus a head, because the newest
49 revision in a repository doesn't have any children, but a repository
50 can contain more than one head.
52 \begin{figure}[ht]
53 \centering
54 \grafix{tour-merge-pull}
55 \caption{Repository contents after pulling from \dirname{my-hello} into
56 \dirname{my-new-hello}}
57 \label{fig:tour-merge:pull}
58 \end{figure}
60 In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
61 pull from \dirname{my-hello} into \dirname{my-new-hello}. The history
62 that was already present in \dirname{my-new-hello} is untouched, but a
63 new revision has been added. By referring to
64 figure~\ref{fig:tour-merge:sep-repos}, we can see that the
65 \emph{changeset ID} remains the same in the new repository, but the
66 \emph{revision number} has changed. (This, incidentally, is a fine
67 example of why it's not safe to use revision numbers when discussing
68 changesets.) We can view the heads in a repository using the
69 \hgcmd{heads} command.
70 \interaction{tour.merge.heads}
71 What happens if we try to use the normal \hgcmd{update} command to
72 update to the new tip?
73 \interaction{tour.merge.update}
74 Mercurial is telling us that the \hgcmd{update} command won't do a
75 merge; it won't update the working directory when it thinks we might
76 be wanting to do a merge, unless we force it to do so. Instead, we
77 use the \hgcmd{merge} command to merge the two heads.
78 \interaction{tour.merge.merge}
80 \begin{figure}[ht]
81 \centering
82 \grafix{tour-merge-merge}
83 \caption{Working directory and repository during merge, and
84 following commit}
85 \label{fig:tour-merge:merge}
86 \end{figure}
88 This updates the working directory so that it contains changes from
89 \emph{both} heads, which is reflected in both the output of
90 \hgcmd{parents} and the contents of \filename{hello.c}.
91 \interaction{tour.merge.parents}
92 Whenever we've done a merge, \hgcmd{parents} will display two parents
93 until we \hgcmd{commit} the results of the merge.
94 \interaction{tour.merge.commit}
95 We now have a new tip revision; notice that it has \emph{both} of
96 our former heads as its parents. These are the same revisions that
97 were previously displayed by \hgcmd{parents}.
98 \interaction{tour.merge.tip}
100 %%% Local Variables:
101 %%% mode: latex
102 %%% TeX-master: "00book"
103 %%% End: