hgbook
annotate es/branch.tex @ 339:adb677612c39
copied the english version of this file to use it as basis for the translation.
There are a couple of paragraphs already translated
There are a couple of paragraphs already translated
author | jerojasro@localhost |
---|---|
date | Sat Oct 18 22:55:12 2008 -0500 (2008-10-18) |
parents | 3502b859cfe4 |
children | 6e427210bfe0 |
rev | line source |
---|---|
igor@324 | 1 \chapter{Administración de Versiones y desarrollo ramificado} |
igor@324 | 2 \label{chap:branch} |
igor@324 | 3 |
igor@324 | 4 Mercurial ofrece varios mecanismos que le permitirán administrar un |
igor@324 | 5 proyecto que avanza en múltiples frentes simultáneamente. Para |
igor@324 | 6 entender estos mecanismos, demos un vistazo a la estructura usual de |
igor@324 | 7 un proyecto de software. |
igor@324 | 8 |
igor@324 | 9 Muchos proyectos de software liberan una versión``mayor'' que contiene |
igor@324 | 10 nuevas características substanciales. En paralelo, pueden liberar |
igor@324 | 11 versiones ``menores''. Estas usualmente son idénticas a las |
igor@324 | 12 versiones mayores en las cuales están basadas, pero con arreglo de |
igor@324 | 13 algunos fallos. |
igor@324 | 14 |
igor@324 | 15 En este capítulo, comenzaremos hablando de cómo mantener registro de |
igor@324 | 16 las etapas del proyecto como las liberaciones de una |
igor@324 | 17 versión. Continuaremos hablando del flujo de trabajo entre las |
igor@324 | 18 diferentes fases de un proyecto, y como puede ayudar Mercurial a |
igor@324 | 19 independizar y administrar tal trabajo. |
igor@324 | 20 |
igor@324 | 21 \section{Dar un nombre persistente a una revisión} |
igor@324 | 22 |
igor@324 | 23 Cuando se decide a otorgar a una revisión el nombre particular de una |
igor@324 | 24 ``versión'', es buena idea grabar la identidad para tal revisión. |
igor@324 | 25 Lo cual permitirá reproducir tal versión en una fecha posterior, o el |
igor@324 | 26 propósito que se considere en ese momento (reproducir un fallo, portar |
igor@324 | 27 a una nueva plataforma, etc). |
igor@324 | 28 \interaction{tag.init} |
igor@324 | 29 |
igor@324 | 30 Mercurial le permite dar un nombre permanente a cualquier revisión |
igor@324 | 31 usando la orden \hgcmd{tag}. Sin causa de sorpresa, esos nombres se llaman |
igor@324 | 32 ``tags''(etiquetas). |
igor@324 | 33 \interaction{tag.tag} |
igor@324 | 34 |
igor@324 | 35 Un tag no es más que un ``nombre simbólico'' para una revisión. Los |
igor@324 | 36 tags existen únicamente para su conveniencia, dotándolo de una forma |
igor@324 | 37 permanente y sencilla para referirse a una revisión; Mercurial no |
igor@324 | 38 interpreta de ninguna manera los nombres de los tags que usted use. |
igor@324 | 39 Mercurial tampoco impone restricción alguna al nombre de un tag, más |
igor@324 | 40 allá de lo necesario para asegurar que un tag puede parsearse sin |
igor@324 | 41 ambigüedades. El nombre de un tag no puede tener ninguno de los |
igor@324 | 42 caracteres siguientes: |
igor@324 | 43 \begin{itemize} |
igor@324 | 44 \item Dos puntos (ASCII 58, ``\texttt{:}'') |
igor@324 | 45 \item Retroceso (return) (ASCII 13, ``\Verb+\r+'') |
igor@324 | 46 \item Nueva línea (ASCII 10, ``\Verb+\n+'') |
igor@324 | 47 \end{itemize} |
igor@324 | 48 |
igor@324 | 49 Puede usar la orden \hgcmd{tags} para observar los tags presentes en |
igor@324 | 50 su repositorio. Al desplegarse, cada revisión marcada se identifica |
igor@324 | 51 primero con su nombre, después el número de revisión y finalmente con |
igor@324 | 52 un hash único de la revisión. |
igor@324 | 53 \interaction{tag.tags} |
igor@324 | 54 Note que \texttt{tip} aparece en la lista de \hgcmd{tags}. El tag |
igor@324 | 55 \texttt{tip} es un tag ``flotante'' especial, que identifica siempre |
igor@324 | 56 la revisión más nueva en el repositorio. |
igor@324 | 57 |
igor@324 | 58 Al desplegar la orden \hgcmd{tags}, los tags se listan en orden |
igor@324 | 59 inverso, por número de revisión. Lo que significa usualmente que los |
igor@324 | 60 tags más recientes se listan antes que los más antiguos. También |
igor@324 | 61 significa que el tag \texttt{tip} siempre aparecerá como primer tag |
igor@324 | 62 listado al desplegar la orden \hgcmd{tags}. |
igor@324 | 63 |
igor@324 | 64 Cuando ejecuta \hgcmd{log}, se desplegará la revisión que tenga los |
igor@324 | 65 tags asociados a ella, se imprimirán tales tags. |
igor@324 | 66 \interaction{tag.log} |
igor@324 | 67 |
igor@324 | 68 Siempre que requiera indicar un ~ID de revisión a una Orden de |
igor@324 | 69 Mercurial, aceptará un nombre de tag en su lugar. Internamente, |
igor@324 | 70 Mercurial traducirá su nombre de tag en el ~ID de revisión |
igor@324 | 71 correspondiente, y lo usará. |
igor@324 | 72 \interaction{tag.log.v1.0} |
igor@324 | 73 |
igor@330 | 74 No hay límites en la cantidad de tags por reposirorio, o la cantidad |
igor@330 | 75 de tags que una misma revisión pueda tener. Siendo prácticos, no es |
igor@330 | 76 muy buena idea tener ``demasiados'' (la cantidad variará de un |
igor@330 | 77 proyecto a otro), debido a que la intención es ayudarle a encontrar |
igor@330 | 78 revisiones. Si tiene demasiados tags, la facilidad para identificar |
igor@330 | 79 revisiones disminuirá rápidamente. |
igor@330 | 80 |
igor@330 | 81 Por ejemplo, si su proyecto tiene etapas(milestones) frecuentes en pocos |
igor@330 | 82 días, es perfectamente razonable asignarle un tag a cada una de |
igor@330 | 83 ellas. Pero si tiene un sistema de construcción automática de binarios |
igor@330 | 84 que asegura que cada revisión puede generarse limpiamente, estaría |
igor@330 | 85 introduciendo mucho ruido si se usara un tag para cada generación |
igor@330 | 86 exitosa. Más bien, podría usar tags para generaciones fallidas (en |
igor@330 | 87 caso de que estas sean raras!), o simplemente evitar los tags para |
igor@330 | 88 llevar cuenta de la posibilidad de generación de binarios. |
igor@330 | 89 |
igor@324 | 90 |
igor@331 | 91 Si desea eliminar un tag que no desea, use |
igor@324 | 92 \hgcmdargs{tag}{--remove}. |
igor@324 | 93 \interaction{tag.remove} |
igor@331 | 94 También puede modificar un tag en cualquier momento para que |
igor@331 | 95 identifique una revisión distinta, basta con aplicar una nueva orden |
igor@331 | 96 \hgcmd{tag}. Deberá usar la opción \hgopt{tag}{-f} para indicarle a |
igor@331 | 97 Mercurial que desea actualizar el tag \emph{en serio}. |
igor@324 | 98 \interaction{tag.replace} |
igor@331 | 99 De todas maneras habrá un registro permanente de la antigua identidad |
igor@331 | 100 del tag, pero Mercurial no la usará. Por lo tanto no hay castigo al |
igor@331 | 101 marcar con un tag una revisión incorrecta; lo único que debe hacer es |
igor@331 | 102 mover el tag hacia la revisión correcta tan pronto como localice el |
igor@331 | 103 error. |
igor@331 | 104 |
igor@331 | 105 Mercurial almacena los tags en un archivo controlado por revisiones en |
igor@331 | 106 su repositorio. Si ha creado tags, los encontrará en un archivo |
igor@331 | 107 llamado \sfilename{.hgtags}. Cuando invoca la orden \hgcmd{tag}, |
igor@331 | 108 Mercurial modifica este archivo, y automáticamente hace commit del |
igor@331 | 109 cambio al mismo. Esto significa que cada vez que ejecuta \hgcmd{tag}, |
igor@331 | 110 verá el conjunto de cambios correspondiente en la salida de \hgcmd{log}. |
igor@324 | 111 \interaction{tag.tip} |
igor@324 | 112 |
igor@331 | 113 \subsection{Manejo de conflictos entre tags durante una fusión} |
igor@331 | 114 |
igor@331 | 115 Es usual no tener que preocuparse por el archivo \sfilename{.hgtags}, |
igor@331 | 116 pero aveces hace su aparición durante una fusión. El formato del |
igor@331 | 117 archivo es sencillo: Consiste de una serie de líneas. Cada línea |
igor@331 | 118 comienza con un hash de Conjunto de Cambios, seguido por un espacio, |
igor@331 | 119 seguido por el nombre de un tag. |
igor@331 | 120 |
igor@331 | 121 Si está resolviendo un conflicto en el archivo \sfilename{.hgtags} |
igor@331 | 122 durante una fusión, hay un detalle para tener en cuenta al modificar |
igor@331 | 123 el archivo \sfilename{.hgtags}: |
igor@331 | 124 cuando Mercurial parsea los tags en el repositorio \emph{nunca} |
igor@331 | 125 lee la copia de trabajo del archivo \sfilename{.hgtags}. En cambio, |
igor@331 | 126 lee la versión \emph{consignada más reciente} del archivo. |
igor@331 | 127 |
igor@331 | 128 Una consecuencia desafortunada de este diseño es que usted no puede |
igor@331 | 129 verificar que su archivo \sfilename{.hgtags} fusionado es correcto hasta |
igor@331 | 130 \emph{después} de haber consignado(hecho commit). Así que si se |
igor@331 | 131 encuentra resolviendo un conflicto en \sfilename{.hgtags} durante una |
igor@331 | 132 fusión, asegúrese de ejecutar la orden \hgcmd{tags} después de |
igor@331 | 133 consignar. Si encuentra un error en el archivo \sfilename{.hgtags}, |
igor@331 | 134 reportará el lugar del error, que podrá arreglar y después |
igor@331 | 135 consignar. Posteriormente ejecute de nuevo la orden \hgcmd{tags} para |
igor@331 | 136 asegurar que su arreglo fue correctamente aplicado. |
igor@331 | 137 |
igor@331 | 138 \subsection{Tags y clonado} |
igor@331 | 139 |
igor@331 | 140 Puede haber notado que la orden \hgcmd{clone} tiene la opción |
igor@331 | 141 \hgopt{clone}{-r} que le permite clonar una copia exacta del |
igor@331 | 142 repositorio hasta un conjunto de cambios específico. El nuevo clon no |
igor@331 | 143 tendrá historia posterior a la revisión que usted haya |
igor@331 | 144 especificado. Esta forma de interactuar puede sorprender a los |
igor@331 | 145 desprevenidos. |
igor@331 | 146 |
igor@331 | 147 Recuerde que un tag se almacena como una revisión al archivo |
igor@331 | 148 \sfilename{.hgtags}, consecuente con esto, cuando crea un tag, el |
igor@331 | 149 conjunto de cambios en el cual este se almacena necesariamente se |
igor@331 | 150 refiere a un conjunto de cambios anterior. Cuando ejecuta |
igor@331 | 151 \hgcmdargs{clone}{-r foo} para clonar un repositorio hasta el tag |
igor@331 | 152 \texttt{foo}, el nuevo clon \emph{no contendrá la historia que creo |
igor@331 | 153 el tag} que usó para clonar el repositorio. El resultado es que tendrá |
igor@331 | 154 exactamente el subconjunto correcto de la historia del proyecto en el |
igor@331 | 155 nuevo repositorio, pero, \emph{no} el tag que podría haber esperado. |
igor@331 | 156 |
igor@331 | 157 \subsection{Cuando los tags permanentes son demasiado} |
igor@331 | 158 |
igor@331 | 159 Dado que los tags de Mercurial están controlados por revisiones y se |
igor@331 | 160 llevan en la historia del proyecto, todas las personas involucradas |
igor@331 | 161 verán los tags que usted haya creado. El hecho de dar nombres a las |
igor@331 | 162 revisiones tiene usos más allá que simplemente hacer notar que la |
igor@331 | 163 revisión \texttt{4237e45506ee} es realmente \texttt{v2.0.2}. Si está |
igor@331 | 164 tratando de encontrar un bug sutil, posiblemente desearía colocar un |
igor@331 | 165 tag recordándole algo como ``Ana vió los síntomas con esta revisión''. |
igor@331 | 166 |
igor@331 | 167 Para estos casos, lo que posiblemente desearía serían tags |
igor@331 | 168 \emph{locales}. Puede crear un tag local con la opción \hgopt{tag}{-l} |
igor@331 | 169 de la orden \hgcmd{tag}. Esto guardará el tag en un archivo llamado |
igor@331 | 170 \sfilename{.hg/localtags}. A diferencia de \sfilename{.hgtags}, |
igor@331 | 171 \sfilename{.hg/localtags} no está controlado por revisiones. |
igor@331 | 172 Cualquier tag que usted cree usando \hgopt{tag}{-l} se mantendrá |
igor@331 | 173 localmente en el repositorio en el que esté trabajando en ese momento. |
igor@331 | 174 |
igor@331 | 175 \section{El flujo de cambios---El gran cuadro vs. el pequeño} |
igor@331 | 176 |
igor@331 | 177 Retomando lo mencionado en el comienzo de un capítulo, pensemos en el |
igor@331 | 178 hecho de que un proyecto tiene muchas piezas concurrentes de trabajo |
igor@331 | 179 en desarrollo al mismo tiempo. |
igor@331 | 180 |
igor@331 | 181 Puede haber prisa por una nueva versión ``principal''; Un nueva |
igor@331 | 182 versión con un rreglo de fallo a la última versión; y una versión de |
igor@331 | 183 ``mantenimiento correctivo'' a una versión antigua que ha entrado en |
igor@331 | 184 modo de mantenimiento. |
igor@331 | 185 |
igor@331 | 186 Usualmente la gente se refiere a esas direcciones |
igor@331 | 187 concurrentes de desarrollo es como ``ramas''. Aunque hemos visto que |
igor@331 | 188 en variadas ocasiones Mercurial trata a \emph{toda la historia} como |
igor@331 | 189 una serie de ramas y fusiones. Realmente lo que tenemos aquí es dos |
igor@331 | 190 ideas que se relacionan periféricamente, pero que en esencia comparten |
igor@331 | 191 un nombre. |
igor@324 | 192 \begin{itemize} |
igor@331 | 193 \item ``El gran cuadro'' Las ramas representan un barrido de la |
igor@331 | 194 evolución del proyecto; la gente les da nombres y hablan acerca de |
igor@331 | 195 ellas en sus conversaciones. |
igor@331 | 196 \item ``El cuadro pequeño'' Las ramas son artefactos de las |
igor@331 | 197 actividades diarias de al desarrollar y fusionar cambios. Exponen la |
igor@331 | 198 narrativa de cómo se desarrolló el código. |
igor@324 | 199 \end{itemize} |
igor@324 | 200 |
igor@337 | 201 \section{Administrar ramas en repositorios estilo gran cuadro} |
igor@337 | 202 |
igor@337 | 203 En Mercurial la forma más sencilla de aislar una rama del ``gran |
igor@337 | 204 cuadro'' es a través de un repositorio dedicado. Si cuenta con un |
igor@337 | 205 repositorio compartido existente ---llamémoslo |
igor@337 | 206 \texttt{myproject}---que alcanzó la etapa ``1.0'', puede comenzar a |
igor@337 | 207 prepararse para versiones de mantenimiento futuras a partir de la |
igor@337 | 208 versión~1.0 marcando con un tag en la revisión con la cual preparó la versión~1.0. |
igor@324 | 209 \interaction{branch-repo.tag} |
igor@337 | 210 Ahora puede clonar un repositorio compartido nuevo |
igor@337 | 211 \texttt{myproject-1.0.1} con tal tag. |
igor@324 | 212 \interaction{branch-repo.clone} |
igor@324 | 213 |
igor@337 | 214 Posteriormente, si alguien necesita trabajar en la reparación de un |
igor@337 | 215 fallo debería dirigirse a la liberación de versión~1.0.1 que viene en |
igor@337 | 216 camino, ellos clonarían el repositorio \texttt{myproject-1.0.1}, |
igor@337 | 217 harían sus cambios y los publicarían(con push). |
igor@324 | 218 \interaction{branch-repo.bugfix} |
igor@337 | 219 Mientras tanto, el desarrollo para la siguiente versión mayor puede |
igor@337 | 220 continuar asilada e incólume, en el repositorio \texttt{myproject}. |
igor@324 | 221 \interaction{branch-repo.new} |
igor@324 | 222 |
igor@324 | 223 \section{Don't repeat yourself: merging across branches} |
igor@324 | 224 |
igor@324 | 225 In many cases, if you have a bug to fix on a maintenance branch, the |
igor@324 | 226 chances are good that the bug exists on your project's main branch |
igor@324 | 227 (and possibly other maintenance branches, too). It's a rare developer |
igor@324 | 228 who wants to fix the same bug multiple times, so let's look at a few |
igor@324 | 229 ways that Mercurial can help you to manage these bugfixes without |
igor@324 | 230 duplicating your work. |
igor@324 | 231 |
igor@324 | 232 In the simplest instance, all you need to do is pull changes from your |
igor@324 | 233 maintenance branch into your local clone of the target branch. |
igor@324 | 234 \interaction{branch-repo.pull} |
igor@324 | 235 You'll then need to merge the heads of the two branches, and push back |
igor@324 | 236 to the main branch. |
igor@324 | 237 \interaction{branch-repo.merge} |
igor@324 | 238 |
igor@331 | 239 \section{Naming branches within one repositorio} |
igor@331 | 240 |
igor@331 | 241 In most instances, isolating branches in repositorios is the right |
igor@324 | 242 approach. Its simplicity makes it easy to understand; and so it's |
igor@324 | 243 hard to make mistakes. There's a one-to-one relationship between |
igor@324 | 244 branches you're working in and directories on your system. This lets |
igor@324 | 245 you use normal (non-Mercurial-aware) tools to work on files within a |
igor@331 | 246 branch/repositorio. |
igor@324 | 247 |
igor@324 | 248 If you're more in the ``power user'' category (\emph{and} your |
igor@324 | 249 collaborators are too), there is an alternative way of handling |
igor@324 | 250 branches that you can consider. I've already mentioned the |
igor@324 | 251 human-level distinction between ``small picture'' and ``big picture'' |
igor@324 | 252 branches. While Mercurial works with multiple ``small picture'' |
igor@331 | 253 branches in a repositorio all the time (for example after you pull |
igor@324 | 254 changes in, but before you merge them), it can \emph{also} work with |
igor@324 | 255 multiple ``big picture'' branches. |
igor@324 | 256 |
igor@324 | 257 The key to working this way is that Mercurial lets you assign a |
igor@324 | 258 persistent \emph{name} to a branch. There always exists a branch |
igor@324 | 259 named \texttt{default}. Even before you start naming branches |
igor@324 | 260 yourself, you can find traces of the \texttt{default} branch if you |
igor@324 | 261 look for them. |
igor@324 | 262 |
igor@324 | 263 As an example, when you run the \hgcmd{commit} command, and it pops up |
igor@324 | 264 your editor so that you can enter a commit message, look for a line |
igor@324 | 265 that contains the text ``\texttt{HG: branch default}'' at the bottom. |
igor@324 | 266 This is telling you that your commit will occur on the branch named |
igor@324 | 267 \texttt{default}. |
igor@324 | 268 |
igor@324 | 269 To start working with named branches, use the \hgcmd{branches} |
igor@324 | 270 command. This command lists the named branches already present in |
igor@331 | 271 your repositorio, telling you which changeset is the tip of each. |
igor@324 | 272 \interaction{branch-named.branches} |
igor@324 | 273 Since you haven't created any named branches yet, the only one that |
igor@324 | 274 exists is \texttt{default}. |
igor@324 | 275 |
igor@324 | 276 To find out what the ``current'' branch is, run the \hgcmd{branch} |
igor@324 | 277 command, giving it no arguments. This tells you what branch the |
igor@324 | 278 parent of the current changeset is on. |
igor@324 | 279 \interaction{branch-named.branch} |
igor@324 | 280 |
igor@324 | 281 To create a new branch, run the \hgcmd{branch} command again. This |
igor@324 | 282 time, give it one argument: the name of the branch you want to create. |
igor@324 | 283 \interaction{branch-named.create} |
igor@324 | 284 |
igor@324 | 285 After you've created a branch, you might wonder what effect the |
igor@324 | 286 \hgcmd{branch} command has had. What do the \hgcmd{status} and |
igor@324 | 287 \hgcmd{tip} commands report? |
igor@324 | 288 \interaction{branch-named.status} |
igor@324 | 289 Nothing has changed in the working directory, and there's been no new |
igor@324 | 290 history created. As this suggests, running the \hgcmd{branch} command |
igor@324 | 291 has no permanent effect; it only tells Mercurial what branch name to |
igor@324 | 292 use the \emph{next} time you commit a changeset. |
igor@324 | 293 |
igor@324 | 294 When you commit a change, Mercurial records the name of the branch on |
igor@324 | 295 which you committed. Once you've switched from the \texttt{default} |
igor@324 | 296 branch to another and committed, you'll see the name of the new branch |
igor@324 | 297 show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands |
igor@324 | 298 that display the same kind of output. |
igor@324 | 299 \interaction{branch-named.commit} |
igor@324 | 300 The \hgcmd{log}-like commands will print the branch name of every |
igor@324 | 301 changeset that's not on the \texttt{default} branch. As a result, if |
igor@324 | 302 you never use named branches, you'll never see this information. |
igor@324 | 303 |
igor@324 | 304 Once you've named a branch and committed a change with that name, |
igor@324 | 305 every subsequent commit that descends from that change will inherit |
igor@324 | 306 the same branch name. You can change the name of a branch at any |
igor@324 | 307 time, using the \hgcmd{branch} command. |
igor@324 | 308 \interaction{branch-named.rebranch} |
igor@324 | 309 In practice, this is something you won't do very often, as branch |
igor@324 | 310 names tend to have fairly long lifetimes. (This isn't a rule, just an |
igor@324 | 311 observation.) |
igor@324 | 312 |
igor@331 | 313 \section{Dealing with multiple named branches in a repositorio} |
igor@331 | 314 |
igor@331 | 315 If you have more than one named branch in a repositorio, Mercurial will |
igor@324 | 316 remember the branch that your working directory on when you start a |
igor@324 | 317 command like \hgcmd{update} or \hgcmdargs{pull}{-u}. It will update |
igor@324 | 318 the working directory to the tip of this branch, no matter what the |
igor@324 | 319 ``repo-wide'' tip is. To update to a revision that's on a different |
igor@324 | 320 named branch, you may need to use the \hgopt{update}{-C} option to |
igor@324 | 321 \hgcmd{update}. |
igor@324 | 322 |
igor@324 | 323 This behaviour is a little subtle, so let's see it in action. First, |
igor@324 | 324 let's remind ourselves what branch we're currently on, and what |
igor@331 | 325 branches are in our repositorio. |
igor@324 | 326 \interaction{branch-named.parents} |
igor@324 | 327 We're on the \texttt{bar} branch, but there also exists an older |
igor@324 | 328 \hgcmd{foo} branch. |
igor@324 | 329 |
igor@324 | 330 We can \hgcmd{update} back and forth between the tips of the |
igor@324 | 331 \texttt{foo} and \texttt{bar} branches without needing to use the |
igor@324 | 332 \hgopt{update}{-C} option, because this only involves going backwards |
igor@324 | 333 and forwards linearly through our change history. |
igor@324 | 334 \interaction{branch-named.update-switchy} |
igor@324 | 335 |
igor@324 | 336 If we go back to the \texttt{foo} branch and then run \hgcmd{update}, |
igor@324 | 337 it will keep us on \texttt{foo}, not move us to the tip of |
igor@324 | 338 \texttt{bar}. |
igor@324 | 339 \interaction{branch-named.update-nothing} |
igor@324 | 340 |
igor@324 | 341 Committing a new change on the \texttt{foo} branch introduces a new |
igor@324 | 342 head. |
igor@324 | 343 \interaction{branch-named.foo-commit} |
igor@324 | 344 |
igor@324 | 345 \section{Branch names and merging} |
igor@324 | 346 |
igor@324 | 347 As you've probably noticed, merges in Mercurial are not symmetrical. |
igor@331 | 348 Let's say our repositorio has two heads, 17 and 23. If I |
igor@324 | 349 \hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records |
igor@324 | 350 17 as the first parent of the merge, and 23 as the second. Whereas if |
igor@324 | 351 I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23 |
igor@324 | 352 as the first parent, and 17 as the second. |
igor@324 | 353 |
igor@324 | 354 This affects Mercurial's choice of branch name when you merge. After |
igor@324 | 355 a merge, Mercurial will retain the branch name of the first parent |
igor@324 | 356 when you commit the result of the merge. If your first parent's |
igor@324 | 357 branch name is \texttt{foo}, and you merge with \texttt{bar}, the |
igor@324 | 358 branch name will still be \texttt{foo} after you merge. |
igor@324 | 359 |
igor@331 | 360 It's not unusual for a repositorio to contain multiple heads, each with |
igor@324 | 361 the same branch name. Let's say I'm working on the \texttt{foo} |
igor@324 | 362 branch, and so are you. We commit different changes; I pull your |
igor@324 | 363 changes; I now have two heads, each claiming to be on the \texttt{foo} |
igor@324 | 364 branch. The result of a merge will be a single head on the |
igor@324 | 365 \texttt{foo} branch, as you might hope. |
igor@324 | 366 |
igor@324 | 367 But if I'm working on the \texttt{bar} branch, and I merge work from |
igor@324 | 368 the \texttt{foo} branch, the result will remain on the \texttt{bar} |
igor@324 | 369 branch. |
igor@324 | 370 \interaction{branch-named.merge} |
igor@324 | 371 |
igor@324 | 372 To give a more concrete example, if I'm working on the |
igor@324 | 373 \texttt{bleeding-edge} branch, and I want to bring in the latest fixes |
igor@324 | 374 from the \texttt{stable} branch, Mercurial will choose the ``right'' |
igor@324 | 375 (\texttt{bleeding-edge}) branch name when I pull and merge from |
igor@324 | 376 \texttt{stable}. |
igor@324 | 377 |
igor@324 | 378 \section{Branch naming is generally useful} |
igor@324 | 379 |
igor@324 | 380 You shouldn't think of named branches as applicable only to situations |
igor@324 | 381 where you have multiple long-lived branches cohabiting in a single |
igor@331 | 382 repositorio. They're very useful even in the one-branch-per-repositorio |
igor@324 | 383 case. |
igor@324 | 384 |
igor@324 | 385 In the simplest case, giving a name to each branch gives you a |
igor@324 | 386 permanent record of which branch a changeset originated on. This |
igor@324 | 387 gives you more context when you're trying to follow the history of a |
igor@324 | 388 long-lived branchy project. |
igor@324 | 389 |
igor@331 | 390 If you're working with shared repositorios, you can set up a |
igor@324 | 391 \hook{pretxnchangegroup} hook on each that will block incoming changes |
igor@324 | 392 that have the ``wrong'' branch name. This provides a simple, but |
igor@324 | 393 effective, defence against people accidentally pushing changes from a |
igor@324 | 394 ``bleeding edge'' branch to a ``stable'' branch. Such a hook might |
igor@324 | 395 look like this inside the shared repo's \hgrc. |
igor@324 | 396 \begin{codesample2} |
igor@324 | 397 [hooks] |
igor@324 | 398 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch |
igor@324 | 399 \end{codesample2} |
igor@324 | 400 |
igor@324 | 401 %%% Local Variables: |
igor@324 | 402 %%% mode: latex |
igor@324 | 403 %%% TeX-master: "00book" |
igor@324 | 404 %%% End: |