hgbook
view es/branch.tex @ 330:8bedea2b8d60
continuing translating branches
| author | Igor TAmara <igor@tamarapatino.org> |
|---|---|
| date | Fri Oct 17 13:58:54 2008 -0500 (2008-10-17) |
| parents | 1afa6cce993d |
| children | 3502b859cfe4 |
line source
1 \chapter{Administración de Versiones y desarrollo ramificado}
2 \label{chap:branch}
4 Mercurial ofrece varios mecanismos que le permitirán administrar un
5 proyecto que avanza en múltiples frentes simultáneamente. Para
6 entender estos mecanismos, demos un vistazo a la estructura usual de
7 un proyecto de software.
9 Muchos proyectos de software liberan una versión``mayor'' que contiene
10 nuevas características substanciales. En paralelo, pueden liberar
11 versiones ``menores''. Estas usualmente son idénticas a las
12 versiones mayores en las cuales están basadas, pero con arreglo de
13 algunos fallos.
15 En este capítulo, comenzaremos hablando de cómo mantener registro de
16 las etapas del proyecto como las liberaciones de una
17 versión. Continuaremos hablando del flujo de trabajo entre las
18 diferentes fases de un proyecto, y como puede ayudar Mercurial a
19 independizar y administrar tal trabajo.
21 \section{Dar un nombre persistente a una revisión}
23 Cuando se decide a otorgar a una revisión el nombre particular de una
24 ``versión'', es buena idea grabar la identidad para tal revisión.
25 Lo cual permitirá reproducir tal versión en una fecha posterior, o el
26 propósito que se considere en ese momento (reproducir un fallo, portar
27 a una nueva plataforma, etc).
28 \interaction{tag.init}
30 Mercurial le permite dar un nombre permanente a cualquier revisión
31 usando la orden \hgcmd{tag}. Sin causa de sorpresa, esos nombres se llaman
32 ``tags''(etiquetas).
33 \interaction{tag.tag}
35 Un tag no es más que un ``nombre simbólico'' para una revisión. Los
36 tags existen únicamente para su conveniencia, dotándolo de una forma
37 permanente y sencilla para referirse a una revisión; Mercurial no
38 interpreta de ninguna manera los nombres de los tags que usted use.
39 Mercurial tampoco impone restricción alguna al nombre de un tag, más
40 allá de lo necesario para asegurar que un tag puede parsearse sin
41 ambigüedades. El nombre de un tag no puede tener ninguno de los
42 caracteres siguientes:
43 \begin{itemize}
44 \item Dos puntos (ASCII 58, ``\texttt{:}'')
45 \item Retroceso (return) (ASCII 13, ``\Verb+\r+'')
46 \item Nueva línea (ASCII 10, ``\Verb+\n+'')
47 \end{itemize}
49 Puede usar la orden \hgcmd{tags} para observar los tags presentes en
50 su repositorio. Al desplegarse, cada revisión marcada se identifica
51 primero con su nombre, después el número de revisión y finalmente con
52 un hash único de la revisión.
53 \interaction{tag.tags}
54 Note que \texttt{tip} aparece en la lista de \hgcmd{tags}. El tag
55 \texttt{tip} es un tag ``flotante'' especial, que identifica siempre
56 la revisión más nueva en el repositorio.
58 Al desplegar la orden \hgcmd{tags}, los tags se listan en orden
59 inverso, por número de revisión. Lo que significa usualmente que los
60 tags más recientes se listan antes que los más antiguos. También
61 significa que el tag \texttt{tip} siempre aparecerá como primer tag
62 listado al desplegar la orden \hgcmd{tags}.
64 Cuando ejecuta \hgcmd{log}, se desplegará la revisión que tenga los
65 tags asociados a ella, se imprimirán tales tags.
66 \interaction{tag.log}
68 Siempre que requiera indicar un ~ID de revisión a una Orden de
69 Mercurial, aceptará un nombre de tag en su lugar. Internamente,
70 Mercurial traducirá su nombre de tag en el ~ID de revisión
71 correspondiente, y lo usará.
72 \interaction{tag.log.v1.0}
74 No hay límites en la cantidad de tags por reposirorio, o la cantidad
75 de tags que una misma revisión pueda tener. Siendo prácticos, no es
76 muy buena idea tener ``demasiados'' (la cantidad variará de un
77 proyecto a otro), debido a que la intención es ayudarle a encontrar
78 revisiones. Si tiene demasiados tags, la facilidad para identificar
79 revisiones disminuirá rápidamente.
81 Por ejemplo, si su proyecto tiene etapas(milestones) frecuentes en pocos
82 días, es perfectamente razonable asignarle un tag a cada una de
83 ellas. Pero si tiene un sistema de construcción automática de binarios
84 que asegura que cada revisión puede generarse limpiamente, estaría
85 introduciendo mucho ruido si se usara un tag para cada generación
86 exitosa. Más bien, podría usar tags para generaciones fallidas (en
87 caso de que estas sean raras!), o simplemente evitar los tags para
88 llevar cuenta de la posibilidad de generación de binarios.
91 If you want to remove a tag that you no longer want, use
92 \hgcmdargs{tag}{--remove}.
93 \interaction{tag.remove}
94 You can also modify a tag at any time, so that it identifies a
95 different revision, by simply issuing a new \hgcmd{tag} command.
96 You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that
97 you \emph{really} want to update the tag.
98 \interaction{tag.replace}
99 There will still be a permanent record of the previous identity of the
100 tag, but Mercurial will no longer use it. There's thus no penalty to
101 tagging the wrong revision; all you have to do is turn around and tag
102 the correct revision once you discover your error.
104 Mercurial stores tags in a normal revision-controlled file in your
105 repository. If you've created any tags, you'll find them in a file
106 named \sfilename{.hgtags}. When you run the \hgcmd{tag} command,
107 Mercurial modifies this file, then automatically commits the change to
108 it. This means that every time you run \hgcmd{tag}, you'll see a
109 corresponding changeset in the output of \hgcmd{log}.
110 \interaction{tag.tip}
112 \subsection{Handling tag conflicts during a merge}
114 You won't often need to care about the \sfilename{.hgtags} file, but
115 it sometimes makes its presence known during a merge. The format of
116 the file is simple: it consists of a series of lines. Each line
117 starts with a changeset hash, followed by a space, followed by the
118 name of a tag.
120 If you're resolving a conflict in the \sfilename{.hgtags} file during
121 a merge, there's one twist to modifying the \sfilename{.hgtags} file:
122 when Mercurial is parsing the tags in a repository, it \emph{never}
123 reads the working copy of the \sfilename{.hgtags} file. Instead, it
124 reads the \emph{most recently committed} revision of the file.
126 An unfortunate consequence of this design is that you can't actually
127 verify that your merged \sfilename{.hgtags} file is correct until
128 \emph{after} you've committed a change. So if you find yourself
129 resolving a conflict on \sfilename{.hgtags} during a merge, be sure to
130 run \hgcmd{tags} after you commit. If it finds an error in the
131 \sfilename{.hgtags} file, it will report the location of the error,
132 which you can then fix and commit. You should then run \hgcmd{tags}
133 again, just to be sure that your fix is correct.
135 \subsection{Tags and cloning}
137 You may have noticed that the \hgcmd{clone} command has a
138 \hgopt{clone}{-r} option that lets you clone an exact copy of the
139 repository as of a particular changeset. The new clone will not
140 contain any project history that comes after the revision you
141 specified. This has an interaction with tags that can surprise the
142 unwary.
144 Recall that a tag is stored as a revision to the \sfilename{.hgtags}
145 file, so that when you create a tag, the changeset in which it's
146 recorded necessarily refers to an older changeset. When you run
147 \hgcmdargs{clone}{-r foo} to clone a repository as of tag
148 \texttt{foo}, the new clone \emph{will not contain the history that
149 created the tag} that you used to clone the repository. The result
150 is that you'll get exactly the right subset of the project's history
151 in the new repository, but \emph{not} the tag you might have expected.
153 \subsection{When permanent tags are too much}
155 Since Mercurial's tags are revision controlled and carried around with
156 a project's history, everyone you work with will see the tags you
157 create. But giving names to revisions has uses beyond simply noting
158 that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}. If
159 you're trying to track down a subtle bug, you might want a tag to
160 remind you of something like ``Anne saw the symptoms with this
161 revision''.
163 For cases like this, what you might want to use are \emph{local} tags.
164 You can create a local tag with the \hgopt{tag}{-l} option to the
165 \hgcmd{tag} command. This will store the tag in a file called
166 \sfilename{.hg/localtags}. Unlike \sfilename{.hgtags},
167 \sfilename{.hg/localtags} is not revision controlled. Any tags you
168 create using \hgopt{tag}{-l} remain strictly local to the repository
169 you're currently working in.
171 \section{The flow of changes---big picture vs. little}
173 To return to the outline I sketched at the beginning of a chapter,
174 let's think about a project that has multiple concurrent pieces of
175 work under development at once.
177 There might be a push for a new ``main'' release; a new minor bugfix
178 release to the last main release; and an unexpected ``hot fix'' to an
179 old release that is now in maintenance mode.
181 The usual way people refer to these different concurrent directions of
182 development is as ``branches''. However, we've already seen numerous
183 times that Mercurial treats \emph{all of history} as a series of
184 branches and merges. Really, what we have here is two ideas that are
185 peripherally related, but which happen to share a name.
186 \begin{itemize}
187 \item ``Big picture'' branches represent the sweep of a project's
188 evolution; people give them names, and talk about them in
189 conversation.
190 \item ``Little picture'' branches are artefacts of the day-to-day
191 activity of developing and merging changes. They expose the
192 narrative of how the code was developed.
193 \end{itemize}
195 \section{Managing big-picture branches in repositories}
197 The easiest way to isolate a ``big picture'' branch in Mercurial is in
198 a dedicated repository. If you have an existing shared
199 repository---let's call it \texttt{myproject}---that reaches a ``1.0''
200 milestone, you can start to prepare for future maintenance releases on
201 top of version~1.0 by tagging the revision from which you prepared
202 the~1.0 release.
203 \interaction{branch-repo.tag}
204 You can then clone a new shared \texttt{myproject-1.0.1} repository as
205 of that tag.
206 \interaction{branch-repo.clone}
208 Afterwards, if someone needs to work on a bug fix that ought to go
209 into an upcoming~1.0.1 minor release, they clone the
210 \texttt{myproject-1.0.1} repository, make their changes, and push them
211 back.
212 \interaction{branch-repo.bugfix}
213 Meanwhile, development for the next major release can continue,
214 isolated and unabated, in the \texttt{myproject} repository.
215 \interaction{branch-repo.new}
217 \section{Don't repeat yourself: merging across branches}
219 In many cases, if you have a bug to fix on a maintenance branch, the
220 chances are good that the bug exists on your project's main branch
221 (and possibly other maintenance branches, too). It's a rare developer
222 who wants to fix the same bug multiple times, so let's look at a few
223 ways that Mercurial can help you to manage these bugfixes without
224 duplicating your work.
226 In the simplest instance, all you need to do is pull changes from your
227 maintenance branch into your local clone of the target branch.
228 \interaction{branch-repo.pull}
229 You'll then need to merge the heads of the two branches, and push back
230 to the main branch.
231 \interaction{branch-repo.merge}
233 \section{Naming branches within one repository}
235 In most instances, isolating branches in repositories is the right
236 approach. Its simplicity makes it easy to understand; and so it's
237 hard to make mistakes. There's a one-to-one relationship between
238 branches you're working in and directories on your system. This lets
239 you use normal (non-Mercurial-aware) tools to work on files within a
240 branch/repository.
242 If you're more in the ``power user'' category (\emph{and} your
243 collaborators are too), there is an alternative way of handling
244 branches that you can consider. I've already mentioned the
245 human-level distinction between ``small picture'' and ``big picture''
246 branches. While Mercurial works with multiple ``small picture''
247 branches in a repository all the time (for example after you pull
248 changes in, but before you merge them), it can \emph{also} work with
249 multiple ``big picture'' branches.
251 The key to working this way is that Mercurial lets you assign a
252 persistent \emph{name} to a branch. There always exists a branch
253 named \texttt{default}. Even before you start naming branches
254 yourself, you can find traces of the \texttt{default} branch if you
255 look for them.
257 As an example, when you run the \hgcmd{commit} command, and it pops up
258 your editor so that you can enter a commit message, look for a line
259 that contains the text ``\texttt{HG: branch default}'' at the bottom.
260 This is telling you that your commit will occur on the branch named
261 \texttt{default}.
263 To start working with named branches, use the \hgcmd{branches}
264 command. This command lists the named branches already present in
265 your repository, telling you which changeset is the tip of each.
266 \interaction{branch-named.branches}
267 Since you haven't created any named branches yet, the only one that
268 exists is \texttt{default}.
270 To find out what the ``current'' branch is, run the \hgcmd{branch}
271 command, giving it no arguments. This tells you what branch the
272 parent of the current changeset is on.
273 \interaction{branch-named.branch}
275 To create a new branch, run the \hgcmd{branch} command again. This
276 time, give it one argument: the name of the branch you want to create.
277 \interaction{branch-named.create}
279 After you've created a branch, you might wonder what effect the
280 \hgcmd{branch} command has had. What do the \hgcmd{status} and
281 \hgcmd{tip} commands report?
282 \interaction{branch-named.status}
283 Nothing has changed in the working directory, and there's been no new
284 history created. As this suggests, running the \hgcmd{branch} command
285 has no permanent effect; it only tells Mercurial what branch name to
286 use the \emph{next} time you commit a changeset.
288 When you commit a change, Mercurial records the name of the branch on
289 which you committed. Once you've switched from the \texttt{default}
290 branch to another and committed, you'll see the name of the new branch
291 show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands
292 that display the same kind of output.
293 \interaction{branch-named.commit}
294 The \hgcmd{log}-like commands will print the branch name of every
295 changeset that's not on the \texttt{default} branch. As a result, if
296 you never use named branches, you'll never see this information.
298 Once you've named a branch and committed a change with that name,
299 every subsequent commit that descends from that change will inherit
300 the same branch name. You can change the name of a branch at any
301 time, using the \hgcmd{branch} command.
302 \interaction{branch-named.rebranch}
303 In practice, this is something you won't do very often, as branch
304 names tend to have fairly long lifetimes. (This isn't a rule, just an
305 observation.)
307 \section{Dealing with multiple named branches in a repository}
309 If you have more than one named branch in a repository, Mercurial will
310 remember the branch that your working directory on when you start a
311 command like \hgcmd{update} or \hgcmdargs{pull}{-u}. It will update
312 the working directory to the tip of this branch, no matter what the
313 ``repo-wide'' tip is. To update to a revision that's on a different
314 named branch, you may need to use the \hgopt{update}{-C} option to
315 \hgcmd{update}.
317 This behaviour is a little subtle, so let's see it in action. First,
318 let's remind ourselves what branch we're currently on, and what
319 branches are in our repository.
320 \interaction{branch-named.parents}
321 We're on the \texttt{bar} branch, but there also exists an older
322 \hgcmd{foo} branch.
324 We can \hgcmd{update} back and forth between the tips of the
325 \texttt{foo} and \texttt{bar} branches without needing to use the
326 \hgopt{update}{-C} option, because this only involves going backwards
327 and forwards linearly through our change history.
328 \interaction{branch-named.update-switchy}
330 If we go back to the \texttt{foo} branch and then run \hgcmd{update},
331 it will keep us on \texttt{foo}, not move us to the tip of
332 \texttt{bar}.
333 \interaction{branch-named.update-nothing}
335 Committing a new change on the \texttt{foo} branch introduces a new
336 head.
337 \interaction{branch-named.foo-commit}
339 \section{Branch names and merging}
341 As you've probably noticed, merges in Mercurial are not symmetrical.
342 Let's say our repository has two heads, 17 and 23. If I
343 \hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records
344 17 as the first parent of the merge, and 23 as the second. Whereas if
345 I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23
346 as the first parent, and 17 as the second.
348 This affects Mercurial's choice of branch name when you merge. After
349 a merge, Mercurial will retain the branch name of the first parent
350 when you commit the result of the merge. If your first parent's
351 branch name is \texttt{foo}, and you merge with \texttt{bar}, the
352 branch name will still be \texttt{foo} after you merge.
354 It's not unusual for a repository to contain multiple heads, each with
355 the same branch name. Let's say I'm working on the \texttt{foo}
356 branch, and so are you. We commit different changes; I pull your
357 changes; I now have two heads, each claiming to be on the \texttt{foo}
358 branch. The result of a merge will be a single head on the
359 \texttt{foo} branch, as you might hope.
361 But if I'm working on the \texttt{bar} branch, and I merge work from
362 the \texttt{foo} branch, the result will remain on the \texttt{bar}
363 branch.
364 \interaction{branch-named.merge}
366 To give a more concrete example, if I'm working on the
367 \texttt{bleeding-edge} branch, and I want to bring in the latest fixes
368 from the \texttt{stable} branch, Mercurial will choose the ``right''
369 (\texttt{bleeding-edge}) branch name when I pull and merge from
370 \texttt{stable}.
372 \section{Branch naming is generally useful}
374 You shouldn't think of named branches as applicable only to situations
375 where you have multiple long-lived branches cohabiting in a single
376 repository. They're very useful even in the one-branch-per-repository
377 case.
379 In the simplest case, giving a name to each branch gives you a
380 permanent record of which branch a changeset originated on. This
381 gives you more context when you're trying to follow the history of a
382 long-lived branchy project.
384 If you're working with shared repositories, you can set up a
385 \hook{pretxnchangegroup} hook on each that will block incoming changes
386 that have the ``wrong'' branch name. This provides a simple, but
387 effective, defence against people accidentally pushing changes from a
388 ``bleeding edge'' branch to a ``stable'' branch. Such a hook might
389 look like this inside the shared repo's \hgrc.
390 \begin{codesample2}
391 [hooks]
392 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
393 \end{codesample2}
395 %%% Local Variables:
396 %%% mode: latex
397 %%% TeX-master: "00book"
398 %%% End: