hgbook

annotate es/tour-merge.tex @ 388:9fdb45b994d4

find changesets by author, revision, files, or words in the commit message
Finished backing out section
author Igor TAmara <igor@tamarapatino.org>
date Sun Nov 02 21:00:40 2008 -0500 (2008-11-02)
parents 7f1572c365d2
children c3a867bba34a
rev   line source
jerojasro@381 1 \chapter{Una gira de Mercurial: fusionar trabajo}
jerojasro@336 2 \label{chap:tour-merge}
jerojasro@336 3
jerojasro@383 4 Hasta ahora hemos cubierto cómo clonar un repositorio, hacer cambios,
jerojasro@383 5 y jalar o empujar dichos cambios de un repositorio a otro. Nuestro
jerojasro@383 6 siguiente paso es \emph{fusionar} cambios de repositorios separados.
jerojasro@383 7
jerojasro@383 8 % TODO cambié streams por líneas. check please
jerojasro@383 9 \section{Fusionar líneas de trabajo}
jerojasro@383 10
jerojasro@383 11 Fusionar es una parte fundamental de trabajar con una herramienta
jerojasro@383 12 de control distribuido de versiones.
jerojasro@336 13 \begin{itemize}
jerojasro@383 14 \item Alicia y Roberto tienen cada uno una copia personal del
jerojasro@383 15 repositorio de un proyecto en el que están trabajando. Alicia
jerojasro@383 16 arregla un fallo en su repositorio; Roberto añade una nueva
jerojasro@383 17 característica en el suyo. Ambos desean que el repositorio
jerojasro@383 18 compartido contenga el arreglo del fallo y la nueva
jerojasro@383 19 característica.
jerojasro@383 20 \item Frecuentemente trabajo en varias tareas diferentes en un mismo
jerojasro@383 21 proyecto al mismo tiempo, cada una aislada convenientemente de las
jerojasro@383 22 otras en su propio repositorio. Trabajar de esta manera significa
jerojasro@383 23 que a menudo debo fusionar una parte de mi propio trabajo con
jerojasro@383 24 otra.
jerojasro@336 25 \end{itemize}
jerojasro@336 26
jerojasro@383 27 Como fusionar es una operación tan necesaria y común, Mercurial la
jerojasro@383 28 facilita. Revisemos el proceso. Empezaremos clonando (otro)
jerojasro@383 29 % TODO poner interrogante de apertura
jerojasro@383 30 repositorio (ve lo seguido que aparecen?) y haciendo un cambio en él.
jerojasro@336 31 \interaction{tour.merge.clone}
jerojasro@383 32 Ahora deberíamos tener dos copias de \filename{hello.c} con contenidos
jerojasro@383 33 diferentes. El historial de los dos repositorios diverge ahora, como
jerojasro@383 34 se ilustra en la figura~\ref{fig:tour-merge:sep-repos}.
jerojasro@336 35 \interaction{tour.merge.cat}
jerojasro@336 36
jerojasro@336 37 \begin{figure}[ht]
jerojasro@336 38 \centering
jerojasro@336 39 \grafix{tour-merge-sep-repos}
jerojasro@383 40 \caption{Historial reciente divergente de los repositorios
jerojasro@383 41 \dirname{my-hello} y \dirname{my-new-hello}}
jerojasro@336 42 \label{fig:tour-merge:sep-repos}
jerojasro@336 43 \end{figure}
jerojasro@336 44
jerojasro@383 45 Ya sabemos que jalar los cambios desde nuestro repositorio
jerojasro@383 46 \dirname{my-hello} no tendrá efecto en el directorio de trabajo.
jerojasro@336 47 \interaction{tour.merge.pull}
jerojasro@384 48 Sin embargo, el comando \hgcmd{pull} dice algo acerca de
jerojasro@384 49 ``frentes''\ndt{El autor se refiere a \emph{heads} aquí.}.
jerojasro@384 50
jerojasro@384 51 \subsection{Conjuntos de cambios de frentes}
jerojasro@384 52
jerojasro@384 53 Un frente es un cambio que no tiene descendientes, o hijos, como
jerojasro@384 54 también se les conoce. La revisión de punta es, por tanto, un frente,
jerojasro@384 55 porque la revisión más reciente en un repositorio no tiene ningún
jerojasro@384 56 % TODO cambio en la redacción de la frase, pero espero que conserve el
jerojasro@384 57 % sentido. Querido human@, apruebe o corrija :D
jerojasro@384 58 hijo. Sin embargo, un repositorio puede contener más de un frente.
jerojasro@336 59
jerojasro@336 60 \begin{figure}[ht]
jerojasro@336 61 \centering
jerojasro@336 62 \grafix{tour-merge-pull}
jerojasro@384 63 \caption{Contenidos del repositorio después de jalar
jerojasro@384 64 \dirname{my-hello} a \dirname{my-new-hello}}
jerojasro@336 65 \label{fig:tour-merge:pull}
jerojasro@336 66 \end{figure}
jerojasro@336 67
jerojasro@384 68 En la figura~\ref{fig:tour-merge:pull} usted puede ver el efecto que
jerojasro@384 69 tiene jalar los cambios de \dirname{my-hello} a \dirname{my-new-hello}.
jerojasro@384 70 El historial que ya existía en \dirname{my-new-hello} se mantiene
jerojasro@384 71 intacto, pero fue añadida una nueva revisión. Refiriéndonos a la
jerojasro@384 72 figura~\ref{fig:tour-merge:sep-repos}, podemos ver que el \emph{ID del
jerojasro@384 73 conjunto de cambios} se mantiene igual en el nuevo repositorio, pero
jerojasro@384 74 el \emph{número de revisión} ha cambiado. (Incidentalmente, éste es un
jerojasro@384 75 buen ejemplo de porqué no es seguro usar números de revisión cuando se
jerojasro@384 76 habla de conjuntos de cambios). Podemos ver los frentes en un
jerojasro@384 77 repositorio usando el comando \hgcmd{heads}\ndt{Frentes.}.
jerojasro@336 78 \interaction{tour.merge.heads}
jerojasro@336 79
jerojasro@385 80 \subsection{Hacer la fusión}
jerojasro@385 81
jerojasro@385 82 % TODO poner interrogante de apertura
jerojasro@385 83 Qué pasa si tratamos de usar el comando usual, \hgcmd{update}, para
jerojasro@385 84 actualizar el nuevo frente?
jerojasro@336 85 \interaction{tour.merge.update}
jerojasro@385 86 Mercurial nos indica que el comando \hgcmd{update} no hará la fusión;
jerojasro@385 87 no actualizará el directorio de trabajo cuando considera que lo que
jerojasro@385 88 deseamos hacer es una fusión, a menos que lo obliguemos a hacerlo.
jerojasro@385 89 En vez de \hgcmd{update}, usamos el comando \hgcmd{merge} para hacer
jerojasro@385 90 la fusión entre los dos frentes.
jerojasro@336 91 \interaction{tour.merge.merge}
jerojasro@336 92
jerojasro@336 93 \begin{figure}[ht]
jerojasro@336 94 \centering
jerojasro@336 95 \grafix{tour-merge-merge}
jerojasro@385 96 \caption{Directorio de trabajo y repositorio durante la fusión, y
jerojasro@385 97 consignación consecuente}
jerojasro@336 98 \label{fig:tour-merge:merge}
jerojasro@336 99 \end{figure}
jerojasro@336 100
jerojasro@385 101 Esto actualiza el directorio de trabajo, de tal forma que contenga los
jerojasro@385 102 cambios de \emph{ambos} frentes, lo que se ve reflejado tanto en la
jerojasro@385 103 salida de \hgcmd{parents} como en los contenidos de \filename{hello.c}.
jerojasro@336 104 \interaction{tour.merge.parents}
jerojasro@336 105
jerojasro@385 106 \subsection{Consignar los resultados de la fusión}
jerojasro@336 107
jerojasro@336 108 Whenever we've done a merge, \hgcmd{parents} will display two parents
jerojasro@336 109 until we \hgcmd{commit} the results of the merge.
jerojasro@336 110 \interaction{tour.merge.commit}
jerojasro@336 111 We now have a new tip revision; notice that it has \emph{both} of
jerojasro@336 112 our former heads as its parents. These are the same revisions that
jerojasro@336 113 were previously displayed by \hgcmd{parents}.
jerojasro@336 114 \interaction{tour.merge.tip}
jerojasro@336 115 In figure~\ref{fig:tour-merge:merge}, you can see a representation of
jerojasro@336 116 what happens to the working directory during the merge, and how this
jerojasro@336 117 affects the repository when the commit happens. During the merge, the
jerojasro@336 118 working directory has two parent changesets, and these become the
jerojasro@336 119 parents of the new changeset.
jerojasro@336 120
jerojasro@336 121 \section{Merging conflicting changes}
jerojasro@336 122
jerojasro@336 123 Most merges are simple affairs, but sometimes you'll find yourself
jerojasro@336 124 merging changes where each modifies the same portions of the same
jerojasro@336 125 files. Unless both modifications are identical, this results in a
jerojasro@336 126 \emph{conflict}, where you have to decide how to reconcile the
jerojasro@336 127 different changes into something coherent.
jerojasro@336 128
jerojasro@336 129 \begin{figure}[ht]
jerojasro@336 130 \centering
jerojasro@336 131 \grafix{tour-merge-conflict}
jerojasro@336 132 \caption{Conflicting changes to a document}
jerojasro@336 133 \label{fig:tour-merge:conflict}
jerojasro@336 134 \end{figure}
jerojasro@336 135
jerojasro@336 136 Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two
jerojasro@336 137 conflicting changes to a document. We started with a single version
jerojasro@336 138 of the file; then we made some changes; while someone else made
jerojasro@336 139 different changes to the same text. Our task in resolving the
jerojasro@336 140 conflicting changes is to decide what the file should look like.
jerojasro@336 141
jerojasro@336 142 Mercurial doesn't have a built-in facility for handling conflicts.
jerojasro@336 143 Instead, it runs an external program called \command{hgmerge}. This
jerojasro@336 144 is a shell script that is bundled with Mercurial; you can change it to
jerojasro@336 145 behave however you please. What it does by default is try to find one
jerojasro@336 146 of several different merging tools that are likely to be installed on
jerojasro@336 147 your system. It first tries a few fully automatic merging tools; if
jerojasro@336 148 these don't succeed (because the resolution process requires human
jerojasro@336 149 guidance) or aren't present, the script tries a few different
jerojasro@336 150 graphical merging tools.
jerojasro@336 151
jerojasro@336 152 It's also possible to get Mercurial to run another program or script
jerojasro@336 153 instead of \command{hgmerge}, by setting the \envar{HGMERGE}
jerojasro@336 154 environment variable to the name of your preferred program.
jerojasro@336 155
jerojasro@336 156 \subsection{Using a graphical merge tool}
jerojasro@336 157
jerojasro@336 158 My preferred graphical merge tool is \command{kdiff3}, which I'll use
jerojasro@336 159 to describe the features that are common to graphical file merging
jerojasro@336 160 tools. You can see a screenshot of \command{kdiff3} in action in
jerojasro@336 161 figure~\ref{fig:tour-merge:kdiff3}. The kind of merge it is
jerojasro@336 162 performing is called a \emph{three-way merge}, because there are three
jerojasro@336 163 different versions of the file of interest to us. The tool thus
jerojasro@336 164 splits the upper portion of the window into three panes:
jerojasro@336 165 \begin{itemize}
jerojasro@336 166 \item At the left is the \emph{base} version of the file, i.e.~the
jerojasro@336 167 most recent version from which the two versions we're trying to
jerojasro@336 168 merge are descended.
jerojasro@336 169 \item In the middle is ``our'' version of the file, with the contents
jerojasro@336 170 that we modified.
jerojasro@336 171 \item On the right is ``their'' version of the file, the one that
jerojasro@336 172 from the changeset that we're trying to merge with.
jerojasro@336 173 \end{itemize}
jerojasro@336 174 In the pane below these is the current \emph{result} of the merge.
jerojasro@336 175 Our task is to replace all of the red text, which indicates unresolved
jerojasro@336 176 conflicts, with some sensible merger of the ``ours'' and ``theirs''
jerojasro@336 177 versions of the file.
jerojasro@336 178
jerojasro@336 179 All four of these panes are \emph{locked together}; if we scroll
jerojasro@336 180 vertically or horizontally in any of them, the others are updated to
jerojasro@336 181 display the corresponding sections of their respective files.
jerojasro@336 182
jerojasro@336 183 \begin{figure}[ht]
jerojasro@336 184 \centering
jerojasro@336 185 \grafix{kdiff3}
jerojasro@336 186 \caption{Using \command{kdiff3} to merge versions of a file}
jerojasro@336 187 \label{fig:tour-merge:kdiff3}
jerojasro@336 188 \end{figure}
jerojasro@336 189
jerojasro@336 190 For each conflicting portion of the file, we can choose to resolve
jerojasro@336 191 the conflict using some combination of text from the base version,
jerojasro@336 192 ours, or theirs. We can also manually edit the merged file at any
jerojasro@336 193 time, in case we need to make further modifications.
jerojasro@336 194
jerojasro@336 195 There are \emph{many} file merging tools available, too many to cover
jerojasro@336 196 here. They vary in which platforms they are available for, and in
jerojasro@336 197 their particular strengths and weaknesses. Most are tuned for merging
jerojasro@336 198 files containing plain text, while a few are aimed at specialised file
jerojasro@336 199 formats (generally XML).
jerojasro@336 200
jerojasro@336 201 \subsection{A worked example}
jerojasro@336 202
jerojasro@336 203 In this example, we will reproduce the file modification history of
jerojasro@336 204 figure~\ref{fig:tour-merge:conflict} above. Let's begin by creating a
jerojasro@336 205 repository with a base version of our document.
jerojasro@336 206 \interaction{tour-merge-conflict.wife}
jerojasro@336 207 We'll clone the repository and make a change to the file.
jerojasro@336 208 \interaction{tour-merge-conflict.cousin}
jerojasro@336 209 And another clone, to simulate someone else making a change to the
jerojasro@336 210 file. (This hints at the idea that it's not all that unusual to merge
jerojasro@336 211 with yourself when you isolate tasks in separate repositories, and
jerojasro@336 212 indeed to find and resolve conflicts while doing so.)
jerojasro@336 213 \interaction{tour-merge-conflict.son}
jerojasro@336 214 Having created two different versions of the file, we'll set up an
jerojasro@336 215 environment suitable for running our merge.
jerojasro@336 216 \interaction{tour-merge-conflict.pull}
jerojasro@336 217
jerojasro@336 218 In this example, I won't use Mercurial's normal \command{hgmerge}
jerojasro@336 219 program to do the merge, because it would drop my nice automated
jerojasro@336 220 example-running tool into a graphical user interface. Instead, I'll
jerojasro@336 221 set \envar{HGMERGE} to tell Mercurial to use the non-interactive
jerojasro@336 222 \command{merge} command. This is bundled with many Unix-like systems.
jerojasro@336 223 If you're following this example on your computer, don't bother
jerojasro@336 224 setting \envar{HGMERGE}.
jerojasro@336 225 \interaction{tour-merge-conflict.merge}
jerojasro@336 226 Because \command{merge} can't resolve the conflicting changes, it
jerojasro@336 227 leaves \emph{merge markers} inside the file that has conflicts,
jerojasro@336 228 indicating which lines have conflicts, and whether they came from our
jerojasro@336 229 version of the file or theirs.
jerojasro@336 230
jerojasro@336 231 Mercurial can tell from the way \command{merge} exits that it wasn't
jerojasro@336 232 able to merge successfully, so it tells us what commands we'll need to
jerojasro@336 233 run if we want to redo the merging operation. This could be useful
jerojasro@336 234 if, for example, we were running a graphical merge tool and quit
jerojasro@336 235 because we were confused or realised we had made a mistake.
jerojasro@336 236
jerojasro@336 237 If automatic or manual merges fail, there's nothing to prevent us from
jerojasro@336 238 ``fixing up'' the affected files ourselves, and committing the results
jerojasro@336 239 of our merge:
jerojasro@336 240 \interaction{tour-merge-conflict.commit}
jerojasro@336 241
jerojasro@336 242 \section{Simplifying the pull-merge-commit sequence}
jerojasro@336 243 \label{sec:tour-merge:fetch}
jerojasro@336 244
jerojasro@336 245 The process of merging changes as outlined above is straightforward,
jerojasro@336 246 but requires running three commands in sequence.
jerojasro@336 247 \begin{codesample2}
jerojasro@336 248 hg pull
jerojasro@336 249 hg merge
jerojasro@336 250 hg commit -m 'Merged remote changes'
jerojasro@336 251 \end{codesample2}
jerojasro@336 252 In the case of the final commit, you also need to enter a commit
jerojasro@336 253 message, which is almost always going to be a piece of uninteresting
jerojasro@336 254 ``boilerplate'' text.
jerojasro@336 255
jerojasro@336 256 It would be nice to reduce the number of steps needed, if this were
jerojasro@336 257 possible. Indeed, Mercurial is distributed with an extension called
jerojasro@336 258 \hgext{fetch} that does just this.
jerojasro@336 259
jerojasro@336 260 Mercurial provides a flexible extension mechanism that lets people
jerojasro@336 261 extend its functionality, while keeping the core of Mercurial small
jerojasro@336 262 and easy to deal with. Some extensions add new commands that you can
jerojasro@336 263 use from the command line, while others work ``behind the scenes,''
jerojasro@336 264 for example adding capabilities to the server.
jerojasro@336 265
jerojasro@336 266 The \hgext{fetch} extension adds a new command called, not
jerojasro@336 267 surprisingly, \hgcmd{fetch}. This extension acts as a combination of
jerojasro@336 268 \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling
jerojasro@336 269 changes from another repository into the current repository. If it
jerojasro@336 270 finds that the changes added a new head to the repository, it begins a
jerojasro@336 271 merge, then commits the result of the merge with an
jerojasro@336 272 automatically-generated commit message. If no new heads were added,
jerojasro@336 273 it updates the working directory to the new tip changeset.
jerojasro@336 274
jerojasro@336 275 Enabling the \hgext{fetch} extension is easy. Edit your
jerojasro@336 276 \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
jerojasro@336 277 or create an \rcsection{extensions} section. Then add a line that
jerojasro@336 278 simply reads ``\Verb+fetch +''.
jerojasro@336 279 \begin{codesample2}
jerojasro@336 280 [extensions]
jerojasro@336 281 fetch =
jerojasro@336 282 \end{codesample2}
jerojasro@336 283 (Normally, on the right-hand side of the ``\texttt{=}'' would appear
jerojasro@336 284 the location of the extension, but since the \hgext{fetch} extension
jerojasro@336 285 is in the standard distribution, Mercurial knows where to search for
jerojasro@336 286 it.)
jerojasro@336 287
jerojasro@336 288 %%% Local Variables:
jerojasro@336 289 %%% mode: latex
jerojasro@336 290 %%% TeX-master: "00book"
jerojasro@336 291 %%% End: