Mercurial > hgbook
annotate ja/branch.tex @ 296:89db0aaf6a29
translated chapter & section name within branch.tex.
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Fri, 08 Feb 2008 01:56:29 +0900 |
parents | 3b1291f24c0d |
children | 828f5606faf0 |
rev | line source |
---|---|
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1 %\chapter{Managing releases and branchy development} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
2 \chapter{$B%j%j!<%9$H%V%i%s%A3+H/$N4IM}(B} |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 \label{chap:branch} |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
197 | 5 Mercurial provides several mechanisms for you to manage a project that |
6 is making progress on multiple fronts at once. To understand these | |
7 mechanisms, let's first take a brief look at a fairly normal software | |
8 project structure. | |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
9 |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
10 Many software projects issue periodic ``major'' releases that contain |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
11 substantial new features. In parallel, they may issue ``minor'' |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
12 releases. These are usually identical to the major releases off which |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
13 they're based, but with a few bugs fixed. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
14 |
197 | 15 In this chapter, we'll start by talking about how to keep records of |
16 project milestones such as releases. We'll then continue on to talk | |
17 about the flow of work between different phases of a project, and how | |
18 Mercurial can help you to isolate and manage this work. | |
19 | |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
20 %\section{Giving a persistent name to a revision} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
21 \section{$B%j%S%8%g%s$K1JB3E*$JL>A0$rIU$1$k(B} |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
22 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
23 Once you decide that you'd like to call a particular revision a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
24 ``release'', it's a good idea to record the identity of that revision. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
25 This will let you reproduce that release at a later date, for whatever |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
26 purpose you might need at the time (reproducing a bug, porting to a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
27 new platform, etc). |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
28 \interaction{tag.init} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
29 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
30 Mercurial lets you give a permanent name to any revision using the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
31 \hgcmd{tag} command. Not surprisingly, these names are called |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
32 ``tags''. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
33 \interaction{tag.tag} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
34 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
35 A tag is nothing more than a ``symbolic name'' for a revision. Tags |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
36 exist purely for your convenience, so that you have a handy permanent |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
37 way to refer to a revision; Mercurial doesn't interpret the tag names |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
38 you use in any way. Neither does Mercurial place any restrictions on |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
39 the name of a tag, beyond a few that are necessary to ensure that a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
40 tag can be parsed unambiguously. A tag name cannot contain any of the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
41 following characters: |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
42 \begin{itemize} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
43 \item Colon (ASCII 58, ``\texttt{:}'') |
261 | 44 \item Carriage return (ASCII 13, ``\Verb+\r+'') |
45 \item Newline (ASCII 10, ``\Verb+\n+'') | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
46 \end{itemize} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
47 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
48 You can use the \hgcmd{tags} command to display the tags present in |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
49 your repository. In the output, each tagged revision is identified |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
50 first by its name, then by revision number, and finally by the unique |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
51 hash of the revision. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
52 \interaction{tag.tags} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
53 Notice that \texttt{tip} is listed in the output of \hgcmd{tags}. The |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
54 \texttt{tip} tag is a special ``floating'' tag, which always |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
55 identifies the newest revision in the repository. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
56 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
57 In the output of the \hgcmd{tags} command, tags are listed in reverse |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
58 order, by revision number. This usually means that recent tags are |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
59 listed before older tags. It also means that \texttt{tip} is always |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
60 going to be the first tag listed in the output of \hgcmd{tags}. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
61 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
62 When you run \hgcmd{log}, if it displays a revision that has tags |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
63 associated with it, it will print those tags. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
64 \interaction{tag.log} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
65 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
66 Any time you need to provide a revision~ID to a Mercurial command, the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
67 command will accept a tag name in its place. Internally, Mercurial |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
68 will translate your tag name into the corresponding revision~ID, then |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
69 use that. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
70 \interaction{tag.log.v1.0} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
71 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
72 There's no limit on the number of tags you can have in a repository, |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
73 or on the number of tags that a single revision can have. As a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
74 practical matter, it's not a great idea to have ``too many'' (a number |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
75 which will vary from project to project), simply because tags are |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
76 supposed to help you to find revisions. If you have lots of tags, the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
77 ease of using them to identify revisions diminishes rapidly. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
78 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
79 For example, if your project has milestones as frequent as every few |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
80 days, it's perfectly reasonable to tag each one of those. But if you |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
81 have a continuous build system that makes sure every revision can be |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
82 built cleanly, you'd be introducing a lot of noise if you were to tag |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
83 every clean build. Instead, you could tag failed builds (on the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
84 assumption that they're rare!), or simply not use tags to track |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
85 buildability. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
86 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
87 If you want to remove a tag that you no longer want, use |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
88 \hgcmdargs{tag}{--remove}. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
89 \interaction{tag.remove} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
90 You can also modify a tag at any time, so that it identifies a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
91 different revision, by simply issuing a new \hgcmd{tag} command. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
92 You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
93 you \emph{really} want to update the tag. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
94 \interaction{tag.replace} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
95 There will still be a permanent record of the previous identity of the |
197 | 96 tag, but Mercurial will no longer use it. There's thus no penalty to |
97 tagging the wrong revision; all you have to do is turn around and tag | |
98 the correct revision once you discover your error. | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
99 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
100 Mercurial stores tags in a normal revision-controlled file in your |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
101 repository. If you've created any tags, you'll find them in a file |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
102 named \sfilename{.hgtags}. When you run the \hgcmd{tag} command, |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
103 Mercurial modifies this file, then automatically commits the change to |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
104 it. This means that every time you run \hgcmd{tag}, you'll see a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
105 corresponding changeset in the output of \hgcmd{log}. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
106 \interaction{tag.tip} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
107 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
108 %\subsection{Handling tag conflicts during a merge} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
109 \subsection{$B%^!<%8$N:]$K%?%0$N%3%s%U%j%/%H$r2r7h$9$k(B} |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
110 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
111 You won't often need to care about the \sfilename{.hgtags} file, but |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
112 it sometimes makes its presence known during a merge. The format of |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
113 the file is simple: it consists of a series of lines. Each line |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
114 starts with a changeset hash, followed by a space, followed by the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
115 name of a tag. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
116 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
117 If you're resolving a conflict in the \sfilename{.hgtags} file during |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
118 a merge, there's one twist to modifying the \sfilename{.hgtags} file: |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
119 when Mercurial is parsing the tags in a repository, it \emph{never} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
120 reads the working copy of the \sfilename{.hgtags} file. Instead, it |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
121 reads the \emph{most recently committed} revision of the file. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
122 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
123 An unfortunate consequence of this design is that you can't actually |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
124 verify that your merged \sfilename{.hgtags} file is correct until |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
125 \emph{after} you've committed a change. So if you find yourself |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
126 resolving a conflict on \sfilename{.hgtags} during a merge, be sure to |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
127 run \hgcmd{tags} after you commit. If it finds an error in the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
128 \sfilename{.hgtags} file, it will report the location of the error, |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
129 which you can then fix and commit. You should then run \hgcmd{tags} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
130 again, just to be sure that your fix is correct. |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
131 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
132 %\subsection{Tags and cloning} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
133 \subsection{$B%?%0$H%/%m!<%s(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
134 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
135 You may have noticed that the \hgcmd{clone} command has a |
259 | 136 \hgopt{clone}{-r} option that lets you clone an exact copy of the |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
137 repository as of a particular changeset. The new clone will not |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
138 contain any project history that comes after the revision you |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
139 specified. This has an interaction with tags that can surprise the |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
140 unwary. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
141 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
142 Recall that a tag is stored as a revision to the \sfilename{.hgtags} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
143 file, so that when you create a tag, the changeset in which it's |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
144 recorded necessarily refers to an older changeset. When you run |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
145 \hgcmdargs{clone}{-r foo} to clone a repository as of tag |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
146 \texttt{foo}, the new clone \emph{will not contain the history that |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
147 created the tag} that you used to clone the repository. The result |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
148 is that you'll get exactly the right subset of the project's history |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
149 in the new repository, but \emph{not} the tag you might have expected. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
150 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
151 %\subsection{When permanent tags are too much} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
152 \subsection{$B1J5W%?%0$,I,MW$G$J$$>l9g(B} |
197 | 153 |
154 Since Mercurial's tags are revision controlled and carried around with | |
155 a project's history, everyone you work with will see the tags you | |
156 create. But giving names to revisions has uses beyond simply noting | |
157 that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}. If | |
158 you're trying to track down a subtle bug, you might want a tag to | |
159 remind you of something like ``Anne saw the symptoms with this | |
160 revision''. | |
161 | |
162 For cases like this, what you might want to use are \emph{local} tags. | |
163 You can create a local tag with the \hgopt{tag}{-l} option to the | |
164 \hgcmd{tag} command. This will store the tag in a file called | |
165 \sfilename{.hg/localtags}. Unlike \sfilename{.hgtags}, | |
166 \sfilename{.hg/localtags} is not revision controlled. Any tags you | |
167 create using \hgopt{tag}{-l} remain strictly local to the repository | |
168 you're currently working in. | |
169 | |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
170 %\section{The flow of changes---big picture vs. little} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
171 \section{$B99?7$NN.$l(B---$BBg6IE*(B vs.$B6I=jE*(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
172 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
173 To return to the outline I sketched at the beginning of a chapter, |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
174 let's think about a project that has multiple concurrent pieces of |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
175 work under development at once. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
176 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
177 There might be a push for a new ``main'' release; a new minor bugfix |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
178 release to the last main release; and an unexpected ``hot fix'' to an |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
179 old release that is now in maintenance mode. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
180 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
181 The usual way people refer to these different concurrent directions of |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
182 development is as ``branches''. However, we've already seen numerous |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
183 times that Mercurial treats \emph{all of history} as a series of |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
184 branches and merges. Really, what we have here is two ideas that are |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
185 peripherally related, but which happen to share a name. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
186 \begin{itemize} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
187 \item ``Big picture'' branches represent the sweep of a project's |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
188 evolution; people give them names, and talk about them in |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
189 conversation. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
190 \item ``Little picture'' branches are artefacts of the day-to-day |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
191 activity of developing and merging changes. They expose the |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
192 narrative of how the code was developed. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
193 \end{itemize} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
194 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
195 %\section{Managing big-picture branches in repositories} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
196 \section{$B%j%]%8%H%j4V$G$NBg6IE*%V%i%s%A$N4IM}(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
197 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
198 The easiest way to isolate a ``big picture'' branch in Mercurial is in |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
199 a dedicated repository. If you have an existing shared |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
200 repository---let's call it \texttt{myproject}---that reaches a ``1.0'' |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
201 milestone, you can start to prepare for future maintenance releases on |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
202 top of version~1.0 by tagging the revision from which you prepared |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
203 the~1.0 release. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
204 \interaction{branch-repo.tag} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
205 You can then clone a new shared \texttt{myproject-1.0.1} repository as |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
206 of that tag. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
207 \interaction{branch-repo.clone} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
208 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
209 Afterwards, if someone needs to work on a bug fix that ought to go |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
210 into an upcoming~1.0.1 minor release, they clone the |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
211 \texttt{myproject-1.0.1} repository, make their changes, and push them |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
212 back. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
213 \interaction{branch-repo.bugfix} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
214 Meanwhile, development for the next major release can continue, |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
215 isolated and unabated, in the \texttt{myproject} repository. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
216 \interaction{branch-repo.new} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
217 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
218 %\section{Don't repeat yourself: merging across branches} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
219 \section{$B<+F02=$5$l$?%V%i%s%A4V$G$N%^!<%8(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
220 |
199
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
221 In many cases, if you have a bug to fix on a maintenance branch, the |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
222 chances are good that the bug exists on your project's main branch |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
223 (and possibly other maintenance branches, too). It's a rare developer |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
224 who wants to fix the same bug multiple times, so let's look at a few |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
225 ways that Mercurial can help you to manage these bugfixes without |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
226 duplicating your work. |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
227 |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
228 In the simplest instance, all you need to do is pull changes from your |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
229 maintenance branch into your local clone of the target branch. |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
230 \interaction{branch-repo.pull} |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
231 You'll then need to merge the heads of the two branches, and push back |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
232 to the main branch. |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
233 \interaction{branch-repo.merge} |
197 | 234 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
235 %\section{Naming branches within one repository} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
236 \section{1$B$D$N%j%]%8%H%jFb$G$N%V%i%s%A$NL?L>(B} |
202
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
237 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
238 In most instances, isolating branches in repositories is the right |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
239 approach. Its simplicity makes it easy to understand; and so it's |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
240 hard to make mistakes. There's a one-to-one relationship between |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
241 branches you're working in and directories on your system. This lets |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
242 you use normal (non-Mercurial-aware) tools to work on files within a |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
243 branch/repository. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
244 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
245 If you're more in the ``power user'' category (\emph{and} your |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
246 collaborators are too), there is an alternative way of handling |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
247 branches that you can consider. I've already mentioned the |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
248 human-level distinction between ``small picture'' and ``big picture'' |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
249 branches. While Mercurial works with multiple ``small picture'' |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
250 branches in a repository all the time (for example after you pull |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
251 changes in, but before you merge them), it can \emph{also} work with |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
252 multiple ``big picture'' branches. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
253 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
254 The key to working this way is that Mercurial lets you assign a |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
255 persistent \emph{name} to a branch. There always exists a branch |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
256 named \texttt{default}. Even before you start naming branches |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
257 yourself, you can find traces of the \texttt{default} branch if you |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
258 look for them. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
259 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
260 As an example, when you run the \hgcmd{commit} command, and it pops up |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
261 your editor so that you can enter a commit message, look for a line |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
262 that contains the text ``\texttt{HG: branch default}'' at the bottom. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
263 This is telling you that your commit will occur on the branch named |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
264 \texttt{default}. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
265 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
266 To start working with named branches, use the \hgcmd{branches} |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
267 command. This command lists the named branches already present in |
203
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
268 your repository, telling you which changeset is the tip of each. |
202
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
269 \interaction{branch-named.branches} |
203
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
270 Since you haven't created any named branches yet, the only one that |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
271 exists is \texttt{default}. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
272 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
273 To find out what the ``current'' branch is, run the \hgcmd{branch} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
274 command, giving it no arguments. This tells you what branch the |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
275 parent of the current changeset is on. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
276 \interaction{branch-named.branch} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
277 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
278 To create a new branch, run the \hgcmd{branch} command again. This |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
279 time, give it one argument: the name of the branch you want to create. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
280 \interaction{branch-named.create} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
281 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
282 After you've created a branch, you might wonder what effect the |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
283 \hgcmd{branch} command has had. What do the \hgcmd{status} and |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
284 \hgcmd{tip} commands report? |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
285 \interaction{branch-named.status} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
286 Nothing has changed in the working directory, and there's been no new |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
287 history created. As this suggests, running the \hgcmd{branch} command |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
288 has no permanent effect; it only tells Mercurial what branch name to |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
289 use the \emph{next} time you commit a changeset. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
290 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
291 When you commit a change, Mercurial records the name of the branch on |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
292 which you committed. Once you've switched from the \texttt{default} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
293 branch to another and committed, you'll see the name of the new branch |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
294 show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
295 that display the same kind of output. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
296 \interaction{branch-named.commit} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
297 The \hgcmd{log}-like commands will print the branch name of every |
205 | 298 changeset that's not on the \texttt{default} branch. As a result, if |
299 you never use named branches, you'll never see this information. | |
300 | |
301 Once you've named a branch and committed a change with that name, | |
302 every subsequent commit that descends from that change will inherit | |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
303 the same branch name. You can change the name of a branch at any |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
304 time, using the \hgcmd{branch} command. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
305 \interaction{branch-named.rebranch} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
306 In practice, this is something you won't do very often, as branch |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
307 names tend to have fairly long lifetimes. (This isn't a rule, just an |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
308 observation.) |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
309 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
310 %\section{Dealing with multiple named branches in a repository} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
311 \section{$B%j%]%8%H%jFb$GJ#?t$NL>A0$NIU$$$?%V%i%s%A$N<h$j07$$(B} |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
312 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
313 If you have more than one named branch in a repository, Mercurial will |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
314 remember the branch that your working directory on when you start a |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
315 command like \hgcmd{update} or \hgcmdargs{pull}{-u}. It will update |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
316 the working directory to the tip of this branch, no matter what the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
317 ``repo-wide'' tip is. To update to a revision that's on a different |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
318 named branch, you may need to use the \hgopt{update}{-C} option to |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
319 \hgcmd{update}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
320 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
321 This behaviour is a little subtle, so let's see it in action. First, |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
322 let's remind ourselves what branch we're currently on, and what |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
323 branches are in our repository. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
324 \interaction{branch-named.parents} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
325 We're on the \texttt{bar} branch, but there also exists an older |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
326 \hgcmd{foo} branch. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
327 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
328 We can \hgcmd{update} back and forth between the tips of the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
329 \texttt{foo} and \texttt{bar} branches without needing to use the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
330 \hgopt{update}{-C} option, because this only involves going backwards |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
331 and forwards linearly through our change history. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
332 \interaction{branch-named.update-switchy} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
333 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
334 If we go back to the \texttt{foo} branch and then run \hgcmd{update}, |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
335 it will keep us on \texttt{foo}, not move us to the tip of |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
336 \texttt{bar}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
337 \interaction{branch-named.update-nothing} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
338 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
339 Committing a new change on the \texttt{foo} branch introduces a new |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
340 head. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
341 \interaction{branch-named.foo-commit} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
342 We can no longer update from \texttt{foo} to \texttt{bar} without |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
343 going ``sideways'' in history, so Mercurial forces us to provide the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
344 \hgopt{update}{-C} option to \hgcmd{update}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
345 \interaction{branch-named.update-bar} |
205 | 346 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
347 %\section{Branch names and merging} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
348 \section{$B%V%i%s%AL>$H%^!<%8(B} |
205 | 349 |
350 As you've probably noticed, merges in Mercurial are not symmetrical. | |
351 Let's say our repository has two heads, 17 and 23. If I | |
352 \hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records | |
353 17 as the first parent of the merge, and 23 as the second. Whereas if | |
354 I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23 | |
355 as the first parent, and 17 as the second. | |
356 | |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
357 This affects Mercurial's choice of branch name when you merge. After |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
358 a merge, Mercurial will retain the branch name of the first parent |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
359 when you commit the result of the merge. If your first parent's |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
360 branch name is \texttt{foo}, and you merge with \texttt{bar}, the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
361 branch name will still be \texttt{foo} after you merge. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
362 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
363 It's not unusual for a repository to contain multiple heads, each with |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
364 the same branch name. Let's say I'm working on the \texttt{foo} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
365 branch, and so are you. We commit different changes; I pull your |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
366 changes; I now have two heads, each claiming to be on the \texttt{foo} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
367 branch. The result of a merge will be a single head on the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
368 \texttt{foo} branch, as you might hope. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
369 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
370 But if I'm working on the \texttt{bar} branch, and I merge work from |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
371 the \texttt{foo} branch, the result will remain on the \texttt{bar} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
372 branch. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
373 \interaction{branch-named.merge} |
205 | 374 |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
375 To give a more concrete example, if I'm working on the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
376 \texttt{bleeding-edge} branch, and I want to bring in the latest fixes |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
377 from the \texttt{stable} branch, Mercurial will choose the ``right'' |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
378 (\texttt{bleeding-edge}) branch name when I pull and merge from |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
379 \texttt{stable}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
380 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
381 %\section{Branch naming is generally useful} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
382 \section{$B%V%i%s%A$KL>A0$rIU$1$k$3$H$OLr$KN)$D(B} |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
383 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
384 You shouldn't think of named branches as applicable only to situations |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
385 where you have multiple long-lived branches cohabiting in a single |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
386 repository. They're very useful even in the one-branch-per-repository |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
387 case. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
388 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
389 In the simplest case, giving a name to each branch gives you a |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
390 permanent record of which branch a changeset originated on. This |
266 | 391 gives you more context when you're trying to follow the history of a |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
392 long-lived branchy project. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
393 |
207
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
394 If you're working with shared repositories, you can set up a |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
395 \hook{pretxnchangegroup} hook on each that will block incoming changes |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
396 that have the ``wrong'' branch name. This provides a simple, but |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
397 effective, defence against people accidentally pushing changes from a |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
398 ``bleeding edge'' branch to a ``stable'' branch. Such a hook might |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
399 look like this inside the shared repo's \hgrc. |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
400 \begin{codesample2} |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
401 [hooks] |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
402 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
403 \end{codesample2} |
202
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
404 |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
405 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
406 %%% mode: yatex |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
407 %%% TeX-master: "00book" |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
408 %%% End: |