hgbook
view es/branch.tex @ 331:3502b859cfe4
Minor advance on branches chapter
| author | Igor TAmara <igor@tamarapatino.org> |
|---|---|
| date | Sat Oct 18 03:27:44 2008 -0500 (2008-10-18) |
| parents | 8bedea2b8d60 |
| children | 0aa96b0ffb65 |
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 Si desea eliminar un tag que no desea, use
92 \hgcmdargs{tag}{--remove}.
93 \interaction{tag.remove}
94 También puede modificar un tag en cualquier momento para que
95 identifique una revisión distinta, basta con aplicar una nueva orden
96 \hgcmd{tag}. Deberá usar la opción \hgopt{tag}{-f} para indicarle a
97 Mercurial que desea actualizar el tag \emph{en serio}.
98 \interaction{tag.replace}
99 De todas maneras habrá un registro permanente de la antigua identidad
100 del tag, pero Mercurial no la usará. Por lo tanto no hay castigo al
101 marcar con un tag una revisión incorrecta; lo único que debe hacer es
102 mover el tag hacia la revisión correcta tan pronto como localice el
103 error.
105 Mercurial almacena los tags en un archivo controlado por revisiones en
106 su repositorio. Si ha creado tags, los encontrará en un archivo
107 llamado \sfilename{.hgtags}. Cuando invoca la orden \hgcmd{tag},
108 Mercurial modifica este archivo, y automáticamente hace commit del
109 cambio al mismo. Esto significa que cada vez que ejecuta \hgcmd{tag},
110 verá el conjunto de cambios correspondiente en la salida de \hgcmd{log}.
111 \interaction{tag.tip}
113 \subsection{Manejo de conflictos entre tags durante una fusión}
115 Es usual no tener que preocuparse por el archivo \sfilename{.hgtags},
116 pero aveces hace su aparición durante una fusión. El formato del
117 archivo es sencillo: Consiste de una serie de líneas. Cada línea
118 comienza con un hash de Conjunto de Cambios, seguido por un espacio,
119 seguido por el nombre de un tag.
121 Si está resolviendo un conflicto en el archivo \sfilename{.hgtags}
122 durante una fusión, hay un detalle para tener en cuenta al modificar
123 el archivo \sfilename{.hgtags}:
124 cuando Mercurial parsea los tags en el repositorio \emph{nunca}
125 lee la copia de trabajo del archivo \sfilename{.hgtags}. En cambio,
126 lee la versión \emph{consignada más reciente} del archivo.
128 Una consecuencia desafortunada de este diseño es que usted no puede
129 verificar que su archivo \sfilename{.hgtags} fusionado es correcto hasta
130 \emph{después} de haber consignado(hecho commit). Así que si se
131 encuentra resolviendo un conflicto en \sfilename{.hgtags} durante una
132 fusión, asegúrese de ejecutar la orden \hgcmd{tags} después de
133 consignar. Si encuentra un error en el archivo \sfilename{.hgtags},
134 reportará el lugar del error, que podrá arreglar y después
135 consignar. Posteriormente ejecute de nuevo la orden \hgcmd{tags} para
136 asegurar que su arreglo fue correctamente aplicado.
138 \subsection{Tags y clonado}
140 Puede haber notado que la orden \hgcmd{clone} tiene la opción
141 \hgopt{clone}{-r} que le permite clonar una copia exacta del
142 repositorio hasta un conjunto de cambios específico. El nuevo clon no
143 tendrá historia posterior a la revisión que usted haya
144 especificado. Esta forma de interactuar puede sorprender a los
145 desprevenidos.
147 Recuerde que un tag se almacena como una revisión al archivo
148 \sfilename{.hgtags}, consecuente con esto, cuando crea un tag, el
149 conjunto de cambios en el cual este se almacena necesariamente se
150 refiere a un conjunto de cambios anterior. Cuando ejecuta
151 \hgcmdargs{clone}{-r foo} para clonar un repositorio hasta el tag
152 \texttt{foo}, el nuevo clon \emph{no contendrá la historia que creo
153 el tag} que usó para clonar el repositorio. El resultado es que tendrá
154 exactamente el subconjunto correcto de la historia del proyecto en el
155 nuevo repositorio, pero, \emph{no} el tag que podría haber esperado.
157 \subsection{Cuando los tags permanentes son demasiado}
159 Dado que los tags de Mercurial están controlados por revisiones y se
160 llevan en la historia del proyecto, todas las personas involucradas
161 verán los tags que usted haya creado. El hecho de dar nombres a las
162 revisiones tiene usos más allá que simplemente hacer notar que la
163 revisión \texttt{4237e45506ee} es realmente \texttt{v2.0.2}. Si está
164 tratando de encontrar un bug sutil, posiblemente desearía colocar un
165 tag recordándole algo como ``Ana vió los síntomas con esta revisión''.
167 Para estos casos, lo que posiblemente desearía serían tags
168 \emph{locales}. Puede crear un tag local con la opción \hgopt{tag}{-l}
169 de la orden \hgcmd{tag}. Esto guardará el tag en un archivo llamado
170 \sfilename{.hg/localtags}. A diferencia de \sfilename{.hgtags},
171 \sfilename{.hg/localtags} no está controlado por revisiones.
172 Cualquier tag que usted cree usando \hgopt{tag}{-l} se mantendrá
173 localmente en el repositorio en el que esté trabajando en ese momento.
175 \section{El flujo de cambios---El gran cuadro vs. el pequeño}
177 Retomando lo mencionado en el comienzo de un capítulo, pensemos en el
178 hecho de que un proyecto tiene muchas piezas concurrentes de trabajo
179 en desarrollo al mismo tiempo.
181 Puede haber prisa por una nueva versión ``principal''; Un nueva
182 versión con un rreglo de fallo a la última versión; y una versión de
183 ``mantenimiento correctivo'' a una versión antigua que ha entrado en
184 modo de mantenimiento.
186 Usualmente la gente se refiere a esas direcciones
187 concurrentes de desarrollo es como ``ramas''. Aunque hemos visto que
188 en variadas ocasiones Mercurial trata a \emph{toda la historia} como
189 una serie de ramas y fusiones. Realmente lo que tenemos aquí es dos
190 ideas que se relacionan periféricamente, pero que en esencia comparten
191 un nombre.
192 \begin{itemize}
193 \item ``El gran cuadro'' Las ramas representan un barrido de la
194 evolución del proyecto; la gente les da nombres y hablan acerca de
195 ellas en sus conversaciones.
196 \item ``El cuadro pequeño'' Las ramas son artefactos de las
197 actividades diarias de al desarrollar y fusionar cambios. Exponen la
198 narrativa de cómo se desarrolló el código.
199 \end{itemize}
201 \section{Administrar ramas en el gran cuadro en los repositorios}
203 The easiest way to isolate a ``big picture'' branch in Mercurial is in
204 a dedicated repositorio. If you have an existing shared
205 repositorio---let's call it \texttt{myproject}---that reaches a ``1.0''
206 milestone, you can start to prepare for future maintenance releases on
207 top of version~1.0 by tagging the revision from which you prepared
208 the~1.0 release.
209 \interaction{branch-repo.tag}
210 You can then clone a new shared \texttt{myproject-1.0.1} repositorio as
211 of that tag.
212 \interaction{branch-repo.clone}
214 Afterwards, if someone needs to work on a bug fix that ought to go
215 into an upcoming~1.0.1 minor release, they clone the
216 \texttt{myproject-1.0.1} repositorio, make their changes, and push them
217 back.
218 \interaction{branch-repo.bugfix}
219 Meanwhile, development for the next major release can continue,
220 isolated and unabated, in the \texttt{myproject} repositorio.
221 \interaction{branch-repo.new}
223 \section{Don't repeat yourself: merging across branches}
225 In many cases, if you have a bug to fix on a maintenance branch, the
226 chances are good that the bug exists on your project's main branch
227 (and possibly other maintenance branches, too). It's a rare developer
228 who wants to fix the same bug multiple times, so let's look at a few
229 ways that Mercurial can help you to manage these bugfixes without
230 duplicating your work.
232 In the simplest instance, all you need to do is pull changes from your
233 maintenance branch into your local clone of the target branch.
234 \interaction{branch-repo.pull}
235 You'll then need to merge the heads of the two branches, and push back
236 to the main branch.
237 \interaction{branch-repo.merge}
239 \section{Naming branches within one repositorio}
241 In most instances, isolating branches in repositorios is the right
242 approach. Its simplicity makes it easy to understand; and so it's
243 hard to make mistakes. There's a one-to-one relationship between
244 branches you're working in and directories on your system. This lets
245 you use normal (non-Mercurial-aware) tools to work on files within a
246 branch/repositorio.
248 If you're more in the ``power user'' category (\emph{and} your
249 collaborators are too), there is an alternative way of handling
250 branches that you can consider. I've already mentioned the
251 human-level distinction between ``small picture'' and ``big picture''
252 branches. While Mercurial works with multiple ``small picture''
253 branches in a repositorio all the time (for example after you pull
254 changes in, but before you merge them), it can \emph{also} work with
255 multiple ``big picture'' branches.
257 The key to working this way is that Mercurial lets you assign a
258 persistent \emph{name} to a branch. There always exists a branch
259 named \texttt{default}. Even before you start naming branches
260 yourself, you can find traces of the \texttt{default} branch if you
261 look for them.
263 As an example, when you run the \hgcmd{commit} command, and it pops up
264 your editor so that you can enter a commit message, look for a line
265 that contains the text ``\texttt{HG: branch default}'' at the bottom.
266 This is telling you that your commit will occur on the branch named
267 \texttt{default}.
269 To start working with named branches, use the \hgcmd{branches}
270 command. This command lists the named branches already present in
271 your repositorio, telling you which changeset is the tip of each.
272 \interaction{branch-named.branches}
273 Since you haven't created any named branches yet, the only one that
274 exists is \texttt{default}.
276 To find out what the ``current'' branch is, run the \hgcmd{branch}
277 command, giving it no arguments. This tells you what branch the
278 parent of the current changeset is on.
279 \interaction{branch-named.branch}
281 To create a new branch, run the \hgcmd{branch} command again. This
282 time, give it one argument: the name of the branch you want to create.
283 \interaction{branch-named.create}
285 After you've created a branch, you might wonder what effect the
286 \hgcmd{branch} command has had. What do the \hgcmd{status} and
287 \hgcmd{tip} commands report?
288 \interaction{branch-named.status}
289 Nothing has changed in the working directory, and there's been no new
290 history created. As this suggests, running the \hgcmd{branch} command
291 has no permanent effect; it only tells Mercurial what branch name to
292 use the \emph{next} time you commit a changeset.
294 When you commit a change, Mercurial records the name of the branch on
295 which you committed. Once you've switched from the \texttt{default}
296 branch to another and committed, you'll see the name of the new branch
297 show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands
298 that display the same kind of output.
299 \interaction{branch-named.commit}
300 The \hgcmd{log}-like commands will print the branch name of every
301 changeset that's not on the \texttt{default} branch. As a result, if
302 you never use named branches, you'll never see this information.
304 Once you've named a branch and committed a change with that name,
305 every subsequent commit that descends from that change will inherit
306 the same branch name. You can change the name of a branch at any
307 time, using the \hgcmd{branch} command.
308 \interaction{branch-named.rebranch}
309 In practice, this is something you won't do very often, as branch
310 names tend to have fairly long lifetimes. (This isn't a rule, just an
311 observation.)
313 \section{Dealing with multiple named branches in a repositorio}
315 If you have more than one named branch in a repositorio, Mercurial will
316 remember the branch that your working directory on when you start a
317 command like \hgcmd{update} or \hgcmdargs{pull}{-u}. It will update
318 the working directory to the tip of this branch, no matter what the
319 ``repo-wide'' tip is. To update to a revision that's on a different
320 named branch, you may need to use the \hgopt{update}{-C} option to
321 \hgcmd{update}.
323 This behaviour is a little subtle, so let's see it in action. First,
324 let's remind ourselves what branch we're currently on, and what
325 branches are in our repositorio.
326 \interaction{branch-named.parents}
327 We're on the \texttt{bar} branch, but there also exists an older
328 \hgcmd{foo} branch.
330 We can \hgcmd{update} back and forth between the tips of the
331 \texttt{foo} and \texttt{bar} branches without needing to use the
332 \hgopt{update}{-C} option, because this only involves going backwards
333 and forwards linearly through our change history.
334 \interaction{branch-named.update-switchy}
336 If we go back to the \texttt{foo} branch and then run \hgcmd{update},
337 it will keep us on \texttt{foo}, not move us to the tip of
338 \texttt{bar}.
339 \interaction{branch-named.update-nothing}
341 Committing a new change on the \texttt{foo} branch introduces a new
342 head.
343 \interaction{branch-named.foo-commit}
345 \section{Branch names and merging}
347 As you've probably noticed, merges in Mercurial are not symmetrical.
348 Let's say our repositorio has two heads, 17 and 23. If I
349 \hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records
350 17 as the first parent of the merge, and 23 as the second. Whereas if
351 I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23
352 as the first parent, and 17 as the second.
354 This affects Mercurial's choice of branch name when you merge. After
355 a merge, Mercurial will retain the branch name of the first parent
356 when you commit the result of the merge. If your first parent's
357 branch name is \texttt{foo}, and you merge with \texttt{bar}, the
358 branch name will still be \texttt{foo} after you merge.
360 It's not unusual for a repositorio to contain multiple heads, each with
361 the same branch name. Let's say I'm working on the \texttt{foo}
362 branch, and so are you. We commit different changes; I pull your
363 changes; I now have two heads, each claiming to be on the \texttt{foo}
364 branch. The result of a merge will be a single head on the
365 \texttt{foo} branch, as you might hope.
367 But if I'm working on the \texttt{bar} branch, and I merge work from
368 the \texttt{foo} branch, the result will remain on the \texttt{bar}
369 branch.
370 \interaction{branch-named.merge}
372 To give a more concrete example, if I'm working on the
373 \texttt{bleeding-edge} branch, and I want to bring in the latest fixes
374 from the \texttt{stable} branch, Mercurial will choose the ``right''
375 (\texttt{bleeding-edge}) branch name when I pull and merge from
376 \texttt{stable}.
378 \section{Branch naming is generally useful}
380 You shouldn't think of named branches as applicable only to situations
381 where you have multiple long-lived branches cohabiting in a single
382 repositorio. They're very useful even in the one-branch-per-repositorio
383 case.
385 In the simplest case, giving a name to each branch gives you a
386 permanent record of which branch a changeset originated on. This
387 gives you more context when you're trying to follow the history of a
388 long-lived branchy project.
390 If you're working with shared repositorios, you can set up a
391 \hook{pretxnchangegroup} hook on each that will block incoming changes
392 that have the ``wrong'' branch name. This provides a simple, but
393 effective, defence against people accidentally pushing changes from a
394 ``bleeding edge'' branch to a ``stable'' branch. Such a hook might
395 look like this inside the shared repo's \hgrc.
396 \begin{codesample2}
397 [hooks]
398 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
399 \end{codesample2}
401 %%% Local Variables:
402 %%% mode: latex
403 %%% TeX-master: "00book"
404 %%% End: