hgbook

view es/tour-merge.tex @ 390:c3a867bba34a

find changesets by author, revision, files, or words in the commit message
modified definitions to allow optional arguments for the inclusion of images.
This needs to be tested for html generation.

translated up to section 2.2.1 ot tour-merge
author Javier Rojas <jerojasro@devnull.li>
date Sun Nov 02 20:08:45 2008 -0500 (2008-11-02)
parents 0abd3d78172e
children 53b4a0d0052e
line source
1 \chapter{Una gira de Mercurial: fusionar trabajo}
2 \label{chap:tour-merge}
3
4 Hasta ahora hemos cubierto cómo clonar un repositorio, hacer cambios,
5 y jalar o empujar dichos cambios de un repositorio a otro. Nuestro
6 siguiente paso es \emph{fusionar} cambios de repositorios separados.
7
8 % TODO cambié streams por líneas. check please
9 \section{Fusionar líneas de trabajo}
10
11 Fusionar es una parte fundamental de trabajar con una herramienta
12 de control distribuido de versiones.
13 \begin{itemize}
14 \item Alicia y Roberto tienen cada uno una copia personal del
15 repositorio de un proyecto en el que están trabajando. Alicia
16 arregla un fallo en su repositorio; Roberto añade una nueva
17 característica en el suyo. Ambos desean que el repositorio
18 compartido contenga el arreglo del fallo y la nueva
19 característica.
20 \item Frecuentemente trabajo en varias tareas diferentes en un mismo
21 proyecto al mismo tiempo, cada una aislada convenientemente de las
22 otras en su propio repositorio. Trabajar de esta manera significa
23 que a menudo debo fusionar una parte de mi propio trabajo con
24 otra.
25 \end{itemize}
26
27 Como fusionar es una operación tan necesaria y común, Mercurial la
28 facilita. Revisemos el proceso. Empezaremos clonando (otro)
29 % TODO poner interrogante de apertura
30 repositorio (ve lo seguido que aparecen?) y haciendo un cambio en él.
31 \interaction{tour.merge.clone}
32 Ahora deberíamos tener dos copias de \filename{hello.c} con contenidos
33 diferentes. El historial de los dos repositorios diverge ahora, como
34 se ilustra en la figura~\ref{fig:tour-merge:sep-repos}.
35 \interaction{tour.merge.cat}
36
37 \begin{figure}[ht]
38 \centering
39 \grafix{tour-merge-sep-repos}
40 \caption{Historial reciente divergente de los repositorios
41 \dirname{my-hello} y \dirname{my-new-hello}}
42 \label{fig:tour-merge:sep-repos}
43 \end{figure}
44
45 Ya sabemos que jalar los cambios desde nuestro repositorio
46 \dirname{my-hello} no tendrá efecto en el directorio de trabajo.
47 \interaction{tour.merge.pull}
48 Sin embargo, el comando \hgcmd{pull} dice algo acerca de
49 ``frentes''\ndt{El autor se refiere a \emph{heads} aquí.}.
50
51 \subsection{Conjuntos de cambios de frentes}
52
53 Un frente es un cambio que no tiene descendientes, o hijos, como
54 también se les conoce. La revisión de punta es, por tanto, un frente,
55 porque la revisión más reciente en un repositorio no tiene ningún
56 % TODO cambio en la redacción de la frase, pero espero que conserve el
57 % sentido. Querido human@, apruebe o corrija :D
58 hijo. Sin embargo, un repositorio puede contener más de un frente.
59
60 \begin{figure}[ht]
61 \centering
62 \grafix{tour-merge-pull}
63 \caption{Contenidos del repositorio después de jalar
64 \dirname{my-hello} a \dirname{my-new-hello}}
65 \label{fig:tour-merge:pull}
66 \end{figure}
67
68 En la figura~\ref{fig:tour-merge:pull} usted puede ver el efecto que
69 tiene jalar los cambios de \dirname{my-hello} a \dirname{my-new-hello}.
70 El historial que ya existía en \dirname{my-new-hello} se mantiene
71 intacto, pero fue añadida una nueva revisión. Refiriéndonos a la
72 figura~\ref{fig:tour-merge:sep-repos}, podemos ver que el \emph{ID del
73 conjunto de cambios} se mantiene igual en el nuevo repositorio, pero
74 el \emph{número de revisión} ha cambiado. (Incidentalmente, éste es un
75 buen ejemplo de porqué no es seguro usar números de revisión cuando se
76 habla de conjuntos de cambios). Podemos ver los frentes en un
77 repositorio usando el comando \hgcmd{heads}\ndt{Frentes.}.
78 \interaction{tour.merge.heads}
79
80 \subsection{Hacer la fusión}
81
82 % TODO poner interrogante de apertura
83 Qué pasa si tratamos de usar el comando usual, \hgcmd{update}, para
84 actualizar el nuevo frente?
85 \interaction{tour.merge.update}
86 Mercurial nos indica que el comando \hgcmd{update} no hará la fusión;
87 no actualizará el directorio de trabajo cuando considera que lo que
88 deseamos hacer es una fusión, a menos que lo obliguemos a hacerlo.
89 En vez de \hgcmd{update}, usamos el comando \hgcmd{merge} para hacer
90 la fusión entre los dos frentes.
91 \interaction{tour.merge.merge}
92
93 \begin{figure}[ht]
94 \centering
95 \grafix{tour-merge-merge}
96 \caption{Directorio de trabajo y repositorio durante la fusión, y
97 consignación consecuente}
98 \label{fig:tour-merge:merge}
99 \end{figure}
100
101 Esto actualiza el directorio de trabajo, de tal forma que contenga los
102 cambios de \emph{ambos} frentes, lo que se ve reflejado tanto en la
103 salida de \hgcmd{parents} como en los contenidos de \filename{hello.c}.
104 \interaction{tour.merge.parents}
105
106 \subsection{Consignar los resultados de la fusión}
107
108 Siempre que hacemos una fusión, \hgcmd{parents} mostrará dos padres
109 hasta que consignemos (\hgcmd{commit}) los resultados de la fusión.
110 \interaction{tour.merge.commit}
111 Ahora tenemos una nueva revisión de punta; note que tiene \emph{los
112 dos} frentes anteriores como sus padres. Estos son las mismas
113 revisiones que mostró previamente el comando \hgcmd{parents}.
114 \interaction{tour.merge.tip}
115 En la figura~\ref{fig:tour-merge:merge} usted puede apreciar una
116 representación de lo que pasa en el directorio de trabajo durante la
117 fusión cuando se hace la consignación. Durante la fusión, el
118 directorio de trabajo tiene dos conjuntos de cambios como sus padres,
119 y éstos se vuelven los padres del nuevo conjunto de cambios.
120
121 \section{Fusionar cambios con conflictos}
122
123 La mayoría de las fusiones son algo simple, pero a veces usted se
124 encontrará fusionando cambios donde más de uno de ellos afecta las
125 mismas secciones de los mismos ficheros. A menos que ambas
126 modificaciones sean idénticas, el resultado es un \emph{conflicto}, en
127 donde usted debe decidir cómo reconciliar ambos cambios y producir un
128 resultado coherente.
129
130 \begin{figure}[ht]
131 \centering
132 \grafix{tour-merge-conflict}
133 \caption{Cambios con conflictos a un documento}
134 \label{fig:tour-merge:conflict}
135 \end{figure}
136
137 La figura~\ref{fig:tour-merge:conflict} ilustra un ejemplo con dos
138 cambios generando conflictos en un documento. Empezamos con una sola
139 versión de el fichero; luego hicimos algunos cambios; mientras tanto,
140 alguien más hizo cambios diferentes en el mismo texto. Lo que debemos
141 hacer para resolver el conflicto causado por ambos cambios es decidir
142 cómo debe quedar finalmente el fichero.
143
144 Mercurial no tiene ninguna utilidad integrada para manejar conflictos.
145 En vez de eso, ejecuta un programa externo llamado \command{hgmerge}.
146 Es un guión de línea de comandos que es instalado junto con Mercurial;
147 usted puede modificarlo para que se comporte como usted lo desee. Por
148 defecto, lo que hace es tratar de encontrar una de varias herramientas
149 para fusionar que es probable que estén instaladas en su sistema.
150 Primero se intenta con unas herramientas para fusionar cambios
151 automáticamente; si esto no tiene éxito (porque la fusión demanda
152 una guía humana) o dichas herramientas no están presentes, el guión
153 intenta con herramientas gráficas para fusionar.
154
155 También es posible hacer que Mercurial ejecute otro programa o guión
156 en vez de \command{hgmerge}, definiendo la variable de entorno
157 \envar{HGMERGE} con el nombre del programa de su preferencia.
158
159 \subsection{Usar una herramienta gráfica para fusión}
160
161 Mi herramienta favorita para hacer fusiones es \command{kdiff3}, y la
162 usaré para describir las características comunes de las herramientas
163 gráficas para hacer fusiones. Puede ver una captura de pantalla de
164 \command{kdiff3} ejecutándose, en la
165 figura~\ref{fig:tour-merge:kdiff3}. El tipo de fusión que la
166 herramienta hace se conoce como \emph{fusión de tres vías}, porque hay
167 tres versiones diferentes del archivo en que estamos interesados.
168 Debido a esto la herramienta divide la parte superior de la ventana en
169 tres paneles.
170 \begin{itemize}
171 \item A la izquierda está la revisión \emph{base} del fichero, p.ej.~la
172 versión más reciente de la que descienden las dos versiones que
173 estamos tratando de fusionar.
174 \item En la mitad está ``nuestra'' versión del fichero, con las
175 modificaciones que hemos hecho.
176 \item A la derecha está la versión del fichero de ``ellos'', la que
177 forma parte del conjunto de cambios que estamos tratando de
178 fusionar.
179 \end{itemize}
180 En el panel inferior se encuentra el \emph{resultado} actual de la
181 fusión. Nuestra tarea es reemplazar todo el texto rojo, que muestra
182 los conflictos sin resolver, con una fusión adecuada de ``nuestra''
183 versión del fichero y la de ``ellos''.
184
185 Los cuatro paneles están \emph{enlazados}; si avanzamos vertical o
186 horizontalmente en cualquiera de ellos, los otros son actualizados
187 para mostrar las secciones correspondientes del fichero que tengan
188 asociado.
189
190 \begin{figure}[ht]
191 \centering
192 \grafix[width=\textwidth]{kdiff3}
193 \caption{Usando \command{kdiff3} para fusionar versiones de un
194 fichero}
195 \label{fig:tour-merge:kdiff3}
196 \end{figure}
197
198 En cada conflicto del fichero podemos escoger resolverlo usando
199 cualquier combinación del texto de la revisión base, la nuestra, o la
200 de ellos. También podemos editar manualmente el fichero en que queda
201 la fusión, si es necesario hacer cambios adicionales.
202
203 Hay \emph{muchas} herramientas para fusionar ficheros disponibles. Se
204 diferencian en las plataformas para las que están disponibles, y en
205 sus fortalezas y debilidades particulares. La mayoría están afinadas
206 para fusionar texto plano, mientras que otras están pensadas para
207 formatos de archivos especializados (generalmente XML).
208
209 \subsection{A worked example}
210
211 In this example, we will reproduce the file modification history of
212 figure~\ref{fig:tour-merge:conflict} above. Let's begin by creating a
213 repository with a base version of our document.
214 \interaction{tour-merge-conflict.wife}
215 We'll clone the repository and make a change to the file.
216 \interaction{tour-merge-conflict.cousin}
217 And another clone, to simulate someone else making a change to the
218 file. (This hints at the idea that it's not all that unusual to merge
219 with yourself when you isolate tasks in separate repositories, and
220 indeed to find and resolve conflicts while doing so.)
221 \interaction{tour-merge-conflict.son}
222 Having created two different versions of the file, we'll set up an
223 environment suitable for running our merge.
224 \interaction{tour-merge-conflict.pull}
225
226 In this example, I won't use Mercurial's normal \command{hgmerge}
227 program to do the merge, because it would drop my nice automated
228 example-running tool into a graphical user interface. Instead, I'll
229 set \envar{HGMERGE} to tell Mercurial to use the non-interactive
230 \command{merge} command. This is bundled with many Unix-like systems.
231 If you're following this example on your computer, don't bother
232 setting \envar{HGMERGE}.
233 \interaction{tour-merge-conflict.merge}
234 Because \command{merge} can't resolve the conflicting changes, it
235 leaves \emph{merge markers} inside the file that has conflicts,
236 indicating which lines have conflicts, and whether they came from our
237 version of the file or theirs.
238
239 Mercurial can tell from the way \command{merge} exits that it wasn't
240 able to merge successfully, so it tells us what commands we'll need to
241 run if we want to redo the merging operation. This could be useful
242 if, for example, we were running a graphical merge tool and quit
243 because we were confused or realised we had made a mistake.
244
245 If automatic or manual merges fail, there's nothing to prevent us from
246 ``fixing up'' the affected files ourselves, and committing the results
247 of our merge:
248 \interaction{tour-merge-conflict.commit}
249
250 \section{Simplifying the pull-merge-commit sequence}
251 \label{sec:tour-merge:fetch}
252
253 The process of merging changes as outlined above is straightforward,
254 but requires running three commands in sequence.
255 \begin{codesample2}
256 hg pull
257 hg merge
258 hg commit -m 'Merged remote changes'
259 \end{codesample2}
260 In the case of the final commit, you also need to enter a commit
261 message, which is almost always going to be a piece of uninteresting
262 ``boilerplate'' text.
263
264 It would be nice to reduce the number of steps needed, if this were
265 possible. Indeed, Mercurial is distributed with an extension called
266 \hgext{fetch} that does just this.
267
268 Mercurial provides a flexible extension mechanism that lets people
269 extend its functionality, while keeping the core of Mercurial small
270 and easy to deal with. Some extensions add new commands that you can
271 use from the command line, while others work ``behind the scenes,''
272 for example adding capabilities to the server.
273
274 The \hgext{fetch} extension adds a new command called, not
275 surprisingly, \hgcmd{fetch}. This extension acts as a combination of
276 \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling
277 changes from another repository into the current repository. If it
278 finds that the changes added a new head to the repository, it begins a
279 merge, then commits the result of the merge with an
280 automatically-generated commit message. If no new heads were added,
281 it updates the working directory to the new tip changeset.
282
283 Enabling the \hgext{fetch} extension is easy. Edit your
284 \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
285 or create an \rcsection{extensions} section. Then add a line that
286 simply reads ``\Verb+fetch +''.
287 \begin{codesample2}
288 [extensions]
289 fetch =
290 \end{codesample2}
291 (Normally, on the right-hand side of the ``\texttt{=}'' would appear
292 the location of the extension, but since the \hgext{fetch} extension
293 is in the standard distribution, Mercurial knows where to search for
294 it.)
295
296 %%% Local Variables:
297 %%% mode: latex
298 %%% TeX-master: "00book"
299 %%% End: