hgbook / es / branch.tex

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
%% vim: tw=70 encoding=utf8
\chapter{Administración de versiones y desarrollo ramificado}
\label{chap:branch}

Mercurial ofrece varios mecanismos que le permiten administrar un
proyecto que avanza en múltiples frentes simultáneamente. Para
entender estos mecanismos, demos un vistazo a la estructura usual de
un proyecto de software.

Muchos proyectos de software liberan una versión ``mayor'' que contiene
nuevas características substanciales.  En paralelo, pueden liberar
versiones ``menores''.   Usualmente éstas son idénticas a las
versiones mayores en las cuales están basadas, pero con arreglos para
algunos fallos.

En este capítulo, comenzaremos hablando de cómo mantener registro de
etapas del proyecto como las liberaciones de una
versión. Continuaremos hablando del flujo de trabajo entre las
diferentes fases de un proyecto, y cómo puede ayudar Mercurial a
aislar y administrar tal trabajo.

\section{Dar un nombre persistente a una revisión}

Cuando usted decide otorgar a una revisión el nombre particular de una
``versión'', es buena idea grabar la identidad de tal revisión.
Esto le permitirá reproducir dicha versión en una fecha posterior,
para cualquiera que sea el 
propósito que se tenga en ese momento (reproducir un fallo, portar
a una nueva plataforma, etc).
\interaction{tag.init}

Mercurial le permite dar un nombre permanente a cualquier revisión
usando la orden \hgcmd{tag}.  Sin causa de sorpresa, esos nombres se llaman
``tags'' (etiquetas).
\interaction{tag.tag}

Una etiqueta no es más que un ``nombre simbólico'' para una revisión.  Las
etiquetas existen únicamente para su conveniencia, brindándole una forma
permanente y sencilla de referirse a una revisión; Mercurial no
interpreta de ninguna manera los nombres de las etiquetas que usted use.
Mercurial tampoco impone restricción alguna al nombre de una etiqueta, más
allá de lo necesario para asegurar que una etiqueta pueda procesarse sin
ambigüedades. El nombre de una etiqueta no puede tener ninguno de los
siguientes caracteres:
\begin{itemize}
\item Dos puntos (ASCII 58, ``\texttt{:}'')
\item Retorno de carro (return) (ASCII 13, ``\Verb+\r+'')
\item Nueva línea (ASCII 10, ``\Verb+\n+'')
\end{itemize}

Puede usar la orden \hgcmd{tags} para ver las etiquetas presentes en
su repositorio. Al desplegarse, cada revisión marcada se identifica
primero con su nombre, después con el número de revisión y finalmente con
un hash único de la revisión.
\interaction{tag.tags}
Note que \texttt{tip} aparece en en listado generado por \hgcmd{tags}. La etiqueta
\texttt{tip} es una etiqueta ``flotante'' especial, que identifica siempre
la revisión más reciente en el repositorio.

Al desplegar la orden \hgcmd{tags}, las etiquetas se listan en orden
inverso, por número de revisión. Lo que significa usualmente que las
etiquetas más recientes se listan antes que las más antiguas. También
significa que la etiqueta \texttt{tip} siempre aparecerá como primera
etiqueta listada al desplegar la orden \hgcmd{tags}.

Cuando usted ejecuta \hgcmd{log}, si se muestra una revisión que tenga 
etiquetas asociadas a ella, se imprimirán tales etiquetas.
\interaction{tag.log}

Siempre que requiera indicar un~ID de revisión a una orden de
Mercurial, aceptará un nombre de etiqueta en su lugar.  Internamente,
Mercurial traducirá su nombre de etiqueta en el~ID de revisión
correspondiente, y lo usará.
\interaction{tag.log.v1.0}

No hay límites en la cantidad de etiquetas por repositorio, o la cantidad
de etiquetas que una misma revisión pueda tener. Siendo prácticos, no es
muy buena idea tener ``demasiadas'' (la cantidad variará de un
proyecto a otro), debido a que la intención es ayudarle a encontrar
revisiones. Si tiene demasiadas etiquetas, la facilidad de usarlas
para identificar revisiones disminuirá rápidamente.

Por ejemplo, si su proyecto tiene etapas (milestones) frecuentes, de pocos
días, es perfectamente razonable asignarle una etiqueta a cada una de
ellas. Pero si tiene un sistema de construcción automática de binarios
que asegura que cada revisión puede generarse limpiamente, estaría
introduciendo mucho ruido si se usara una etiqueta para cada generación
exitosa. Más bien, podría usar tags para generaciones fallidas
(\textexclamdown en
caso de que estas sean raras!), o simplemente evitar las etiquetas para
llevar cuenta de la posibilidad de generación de binarios.


Si quiere eliminar una etiqueta que no desea, use
\hgcmdargs{tag}{--remove}.  
\interaction{tag.remove}
También puede modificar una etiqueta en cualquier momento, para que
identifique una revisión distinta, simplemente usando una nueva orden
\hgcmd{tag}. Deberá usar la opción \hgopt{tag}{-f} para indicarle a
Mercurial que \emph{realmente} desea actualizar la etiqueta.
\interaction{tag.replace}
De todas maneras habrá un registro permanente de la antigua identidad
de la etiqueta, pero Mercurial no la usará. Por lo tanto no hay
problema al marcar con una etiqueta una revisión incorrecta; lo único
que debe hacer es mover la etiqueta hacia la revisión correcta tan
pronto como localice el error.

Mercurial almacena las etiquetas en un fichero controlado por revisiones en
su repositorio. Si ha creado etiquetas, las encontrará en un fichero
llamado \sfilename{.hgtags}.  Cuando invoca la orden \hgcmd{tag},
Mercurial modifica este fichero, y hace la consignación del cambio al
mismo automáticamente.  Esto significa que cada vez que ejecuta
\hgcmd{tag}, verá un conjunto de cambios correspondiente en la salida
de \hgcmd{log}.
\interaction{tag.tip}

\subsection{Manejo de conflictos entre etiquetas durante una fusión}

Usualmente no tendrá que preocuparse por el fichero \sfilename{.hgtags},
pero a veces hace su aparición durante una fusión. El formato del
fichero es sencillo: Consiste de una serie de líneas. Cada línea
comienza con un hash de conjunto de cambios, seguido por un espacio,
seguido por el nombre de una etiqueta.

Si está resolviendo un conflicto en el fichero \sfilename{.hgtags}
durante una fusión, hay un detalle para tener en cuenta al modificar
el fichero \sfilename{.hgtags}:
cuando Mercurial procesa las etiquetas en el repositorio, \emph{nunca}
lee la copia de trabajo del fichero \sfilename{.hgtags}.  En cambio,
lee la versión \emph{consignada más reciente} del fichero.

Una consecuencia desafortunada de este diseño es que usted no puede
verificar que su fichero \sfilename{.hgtags} fusionado sea correcto hasta
\emph{después} de haber consignado un cambio. Así que si se
encuentra resolviendo un conflicto en \sfilename{.hgtags} durante una
fusión, asegúrese de ejecutar la orden \hgcmd{tags} después de
consignar. Si encuentra un error en el fichero \sfilename{.hgtags}, 
la orden reportará el lugar del error, que podrá arreglar y después
consignar. Posteriormente ejecute de nuevo la orden \hgcmd{tags} para
asegurarse de que su arreglo fue aplicado correctamente .

\subsection{Etiquetas y clonado}

Puede haber notado que la orden \hgcmd{clone} tiene la opción
\hgopt{clone}{-r} que le permite clonar una copia exacta del
repositorio hasta un conjunto de cambios específico. El nuevo clon no
tendrá historial posterior a la revisión que usted haya
especificado. Esto tiene una interacción con etiquetas que puede
sorprender a los desprevenidos.

Recuerde que una etiqueta se almacena como una revisión al fichero
\sfilename{.hgtags}, así que cuando usted crea una etiqueta, el
conjunto de cambios en el cual ésta se almacena necesariamente se
refiere a un conjunto de cambios anterior. Cuando ejecuta
\hgcmdargs{clone}{-r foo} para clonar un repositorio hasta la etiqueta
\texttt{foo}, el nuevo clon \emph{no contendrá el historial que creo
la etiqueta} que usó para clonar el repositorio. El resultado es que tendrá
exactamente el subconjunto correcto del historial del proyecto en el
nuevo repositorio, pero, \emph{no} la etiqueta que podría haber esperado.

\subsection{Cuando las etiquetas permanentes son demasiado}

Dado que las etiquetas de Mercurial están controladas por revisiones y se
llevan en el historial del proyecto, todas las personas involucradas
verán las etiquetas que usted haya creado. El hecho de dar nombres a las
revisiones tiene usos más allá que simplemente hacer notar que la
revisión \texttt{4237e45506ee} es realmente \texttt{v2.0.2}.  Si está
tratando de encontrar un fallo sutil, posiblemente desearía colocar una 
etiqueta recordándole algo como ``Ana vio los síntomas en esta revisión''.

Para estos casos, lo que usted posiblemente desearía serían etiquetas
\emph{locales}. Puede crear una etiqueta local con la opción~\hgopt{tag}{-l}
de la orden \hgcmd{tag}.  Esto guardará la etiqueta en un fichero llamado
\sfilename{.hg/localtags}.  A diferencia de \sfilename{.hgtags},
\sfilename{.hg/localtags} no está controlado por revisiones.
Cualquier etiqueta que usted cree usando \hgopt{tag}{-l} se mantendrá
local al repositorio en el que esté trabajando en ese momento.

\section{El flujo de cambios---El gran cuadro vs. el pequeño}

Retomando lo mencionado en el comienzo de un capítulo, pensemos en el
hecho de que un proyecto tiene muchas piezas concurrentes de trabajo
en desarrollo al mismo tiempo.

Puede haber prisa por una nueva versión ``principal''; una nueva
versión con un arreglo de fallo a la última versión; y una versión de
``mantenimiento correctivo'' a una versión antigua que ha entrado en
modo de mantenimiento.

Usualmente la gente se refiere a esas direcciones
concurrentes de desarrollo como ``ramas''.  Sin embargo, ya hemos visto que
en varias ocasiones Mercurial trata a \emph{todo el historial} como
una serie de ramas y fusiones.  Realmente lo que tenemos aquí es dos
ideas que se relacionan periféricamente, pero que en esencia comparten
un nombre.
\begin{itemize}
\item ``El gran cuadro'' Las ramas representan un barrido de la
  evolución del proyecto; la gente les da nombres y hablan acerca de
  ellas en sus conversaciones.
\item ``El cuadro pequeño'' Las ramas son artefactos de las
  actividades diarias de desarrollar y fusionar cambios. Exponen la
  narrativa de cómo se desarrolló el código.
\end{itemize}

\section{Administrar ramas en repositorios estilo gran cuadro}

En Mercurial la forma más sencilla de aislar una rama del ``gran
cuadro'' es a través de un repositorio dedicado.  Si cuenta con un
repositorio compartido existente ---llamémoslo
\texttt{myproject}---que alcanzó la etapa ``1.0'', puede comenzar a
prepararse para versiones de mantenimiento futuras a partir de la
versión~1.0 marcando con una etiqueta la revisión con la cual preparó la versión~1.0.
\interaction{branch-repo.tag}
Ahora puede clonar un repositorio compartido nuevo
\texttt{myproject-1.0.1} con tal etiqueta.
\interaction{branch-repo.clone}

Posteriormente, si alguien necesita trabajar en la reparación de un
fallo debería dirigirse a la liberación de versión~1.0.1 que viene en
camino, ellos clonarían el repositorio \texttt{myproject-1.0.1},
harían sus cambios y los empujarían de vuelta.
\interaction{branch-repo.bugfix}
Mientras tanto, el desarrollo para la siguiente versión mayor puede
continuar aislado e incólume, en el repositorio \texttt{myproject}.
\interaction{branch-repo.new}

\section{No repita trabajo: fusión entre ramas}

En muchos casos, cuando tiene un fallo para arreglar en una rama de
mantenimiento, es muy probable que el fallo también esté en la rama
principal (y posiblemente en otras ramas de mantenimiento
también). Solamente un desarrollador extraño desearía corregir el
mismo fallo muchas veces, por tanto, veremos varias alternativas con
las que Mercurial puede ayudarle a administrar tales arreglos de fallo
sin duplicar su trabajo.

En el caso más sencillo, basta con jalar los cambios de la rama de
mantenimiento a la rama objetivo en su clon local.
\interaction{branch-repo.pull}
A continuación deberá mezclar las cabezas de las dos ramas, y empujar
de nuevo a la rama principal.
\interaction{branch-repo.merge}

\section{Nombrar ramas dentro de un repositorio}

La aproximación correcta en casi todas las oportunidades es aislar las
ramas en los repositorios.  Es fácil de entender gracias a su
simplicidad; y es difícil cometer errores. Hay una relación uno a uno
entre las ramas y los directorios con los que está trabajando en su
sistema. Esto le permite usar emplear herramientas usuales (que no son
conscientes de Mercurial) para trabajar con los ficheros dentro de una
rama/repositorio.

Si se encuentra más en la categoría ``usuario diestro'' (\emph{y} sus
colaboradores también), puede considerar otra alternativa para
administrar las ramas. He mencionado con anterioridad la distinción a
nivel humano entre las ramas estilo ``cuadro pequeño'' y ``gran
cuadro''.  Mientras que Mercurial trabaja con muchas ramas del estilo
``cuadro pequeño'' en el repositorio todo el tiempo (por ejemplo cuando
usted jala cambios, pero antes de fusionarlos), \emph{también} puede
trabajar con varias ramas del ``cuadro grande''.

El truco para trabajar de esta forma en Mercurial se logra gracias a
que puede asignar un \emph{nombre} persistente a una rama.  Siempre
existe una rama llamada \texttt{default}.  Incluso antes de que
empiece a nombrar ramas por su cuenta, puede encontrar indicios de la
rama \texttt{default} si los busca.

Por ejemplo, cuando invoca la orden \hgcmd{commit}, y se lanza su
editor para introducir el mensaje de la consignación, busque la línea
que contiene el texto ``\texttt{HG: branch default}'' al final. Le
está indicando que su consignación ocurrirá en la rama llamada 
\texttt{default}.

Use la orden \hgcmd{branches} para empezar a trabajar con ramas
nombradas. Esta orden mostrará las ramas presentes en su repositorio,
indicándole qué conjunto de cambios es la punta de cada una.
\interaction{branch-named.branches}
Dado que todavía no ha creado ramas nombradas, la única que verá será
\texttt{default}.

Para hallar cuál es la rama ``actual'', invoque la orden
\hgcmd{branch}, sin argumento alguno. Le informará en qué rama se
encuentra el padre del conjunto de cambios actual.
\interaction{branch-named.branch}

Para crear una nueva rama, invoque la orden \hgcmd{branch} de
nuevo. En esta oportunidad, ofrezca un argumento: el nombre de la rama
que desea crear.
\interaction{branch-named.create}

Después de crear la rama, usted podría desear ver el efecto que tuvo
la orden \hgcmd{branch}.  ¿Qué reportan las ordenes \hgcmd{status} y
\hgcmd{tip}?
\interaction{branch-named.status}
Nada cambia en el directorio actual, y no se ha añadido nada al
historial. Esto sugiere que al ejecutar la orden \hgcmd{branch} no hay
un efecto permanente; solamente le indica a que nombre de rama usará
la \emph{próxima} vez que consigne un conjunto de cambios.

Cuando consigna un cambio, Mercurial almacena el nombre de la rama en
la cual consignó.  Una vez que haya cambiado de la rama \texttt{default}
y haya consignado, verá que el nombre de la nueva rama se mostrará
cuando use la orden \hgcmd{log}, \hgcmd{tip}, y otras órdenes que
desplieguen la misma clase de información.
\interaction{branch-named.commit}
Las órdenes del tipo \hgcmd{log} imprimirán el nombre de la rama de
cualquier conjunto de cambios que no esté en la rama
\texttt{default}. Como resultado, si nunca usa ramas nombradas, nunca
verá esta información.

Una vez que haya nombrado una rama y consignado un cambio con ese
nombre, todas las consignaciones subsecuentes que desciendan de ese
cambio heredarán el mismo nombre de rama. Puede cambiar el nombre de
una rama en cualquier momento con la orden \hgcmd{branch}.  
\interaction{branch-named.rebranch}
Esto es algo que no hará muy seguido en la práctica, debido que los
nombres de las ramas tienden a tener vidas largas.  (Esto no es una
regla, solamente una observación.)

\section{Tratamiento de varias ramas nombradas en un repositorio}

Si tiene más de una rama nombrada en un repositorio, Mercurial
recordará la rama en la cual está su directorio de trabajo cuando
invoque una orden como \hgcmd{update} o \hgcmdargs{pull}{-u}.  Se
actualizará su directorio de trabajo actual a la punta de esta rama, sin
importar cuál sea la punta ``a lo largo del repositorio''.  Para
actualizar a una revisión que está en una rama con distinto nombre,
puede necesitar la opción \hgopt{update}{-C} de \hgcmd{update}.

Este comportamiento puede ser sutil, así que veámoslo en acción.  Primero,
recordemos en qué rama estamos trabajando, y qué ramas están en
nuestro repositorio.
\interaction{branch-named.parents}
Estamos en la rama \texttt{bar}, pero existe otra rama más antigua
llamada \hgcmd{foo}.

Podemos hacer \hgcmd{update} entre los tipos de las ramas \texttt{foo}
y \texttt{bar} sin necesidad de usar la opción \hgopt{update}{-C},
puesto que esto solamente implica ir linealmente hacia adelante y
atrás en nuestro historial de cambios.
\interaction{branch-named.update-switchy}

Si volvemos a la rama \texttt{foo} e invocamos la orden \hgcmd{update},
nos mantendrá en \texttt{foo}, sin movernos a la punta de \texttt{bar}.
\interaction{branch-named.update-nothing}

Al consignar un cambio a la rama \texttt{foo} se introducirá una nueva
cabeza.
\interaction{branch-named.foo-commit}

\section{Nombres de ramas y fusiones}

Posiblemente ha notado que las fusiones en Mercurial no son simétricas.
Supongamos que su repositorio tiene dos cabezas, 17 y 23.  Si yo invoco
\hgcmd{update} a 17 y aplico \hgcmd{merge} a 23, Mercurial almacena 17
como el primer padre de la fusión, y 23 como el segundo. Mientras que
si hago \hgcmd{update} a 23 y después aplico \hgcmd{merge} con 17,
grabará a 23 como el primer padre, y 17 como el segundo.

Esto afecta el cómo elige Mercurial el nombre de la rama cuando usted
hace la fusión.  Después de una fusión, Mercurial mantendrá el nombre de la
rama del primer padre cuando consigne el resultado de la fusión.  Si
el primer nombre de su padre es \texttt{foo}, y fusiona con
\texttt{bar}, el nombre de la rama continuará siendo \texttt{foo}
después de fusionar.

No es inusual que un repositorio contenga varias cabezas, cada una con
el mismo nombre de rama.  Digamos que estoy trabajando en la rama
\texttt{foo}, y usted también.  Consignamos cambios distintos; yo jalo
sus cambios; Ahora tengo dos cabezas, cada una afirmando estar en la
rama \texttt{foo}.  El resultado de una fusión será una única cabeza
en la rama \texttt{foo} como usted esperaría.

Pero si estoy trabajando en la rama \texttt{bar}, y fusiono el trabajo
de la rama \texttt{foo}, el resultado permanecerá en la rama
\texttt{bar}.
\interaction{branch-named.merge}

En un ejemplo más concreto, si yo estoy trabajando en la rama
\texttt{bleeding-edge}, y deseo traer los arreglos más recientes de la
rama \texttt{estable}, Mercurial elegirá el nombre de rama ``correcto''
(\texttt{bleeding-edge}) cuando yo jale una fusión desde \texttt{estable}.

\section{Normalmente es útil nombrar ramas}

No debería considerar que las ramas nombradas son aplicables
únicamente en situaciones con muchas ramas de larga vida cohabitando
en un mismo repositorio.  Son muy útiles incluso en los casos de
una rama por repositorio.

En el caso más sencillo, dar un nombre a cada rama ofrece un registro
permanente acerca de en qué conjunto de cambios se generó la rama.
Esto le ofrece más contexto cuando esté tratando de seguir el
historial de un proyecto ramificado de larga vida.

Si está trabajando con repositorios compartidos, puede configurar el gancho
\hook{pretxnchangegroup} para que cada uno bloquee los cambios con
nombres de rama ``incorrectos'' que están por adicionarse.  Este
provee una defensa sencilla, pero efectiva, para evitar que la gente
publique accidentalmente cambios de una rama ``super nueva'' a la rama
``estable''.  Tal gancho podría verse de la siguiente forma dentro de
un repositorio compartido de \hgrc.
\begin{codesample2}
  [hooks]
  pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
\end{codesample2}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.