annotate es/tour-merge.tex @ 489:c3a867bba34a

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

\chapter{Una gira de Mercurial: fusionar trabajo}
\label{chap:tour-merge}

Hasta ahora hemos cubierto cómo clonar un repositorio, hacer cambios,
y jalar o empujar dichos cambios de un repositorio a otro. Nuestro
siguiente paso es \emph{fusionar} cambios de repositorios separados.

% TODO cambié streams por líneas. check please
\section{Fusionar líneas de trabajo}

Fusionar es una parte fundamental de trabajar con una herramienta 
de control distribuido de versiones.
\begin{itemize}
\item Alicia y Roberto tienen cada uno una copia personal del
    repositorio de un proyecto en el que están trabajando. Alicia
    arregla un fallo en su repositorio; Roberto añade una nueva
    característica en el suyo. Ambos desean que el repositorio
    compartido contenga el arreglo del fallo y la nueva
    característica.
\item Frecuentemente trabajo en varias tareas diferentes en un mismo
    proyecto al mismo tiempo, cada una aislada convenientemente de las
    otras en su propio repositorio. Trabajar de esta manera significa
    que a menudo debo fusionar una parte de mi propio trabajo con
    otra.
\end{itemize}

Como fusionar es una operación tan necesaria y común, Mercurial la
facilita. Revisemos el proceso. Empezaremos clonando (otro)
% TODO poner interrogante de apertura
repositorio (ve lo seguido que aparecen?) y haciendo un cambio en él.
\interaction{tour.merge.clone}
Ahora deberíamos tener dos copias de \filename{hello.c} con contenidos
diferentes.  El historial de los dos repositorios diverge ahora, como
se ilustra en la figura~\ref{fig:tour-merge:sep-repos}.
\interaction{tour.merge.cat}

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-sep-repos}
  \caption{Historial reciente divergente de los repositorios
      \dirname{my-hello} y \dirname{my-new-hello}}
  \label{fig:tour-merge:sep-repos}
\end{figure}

Ya sabemos que jalar los cambios desde nuestro repositorio
\dirname{my-hello} no tendrá efecto en el directorio de trabajo.
\interaction{tour.merge.pull}
Sin embargo, el comando \hgcmd{pull} dice algo acerca de
``frentes''\ndt{El autor se refiere a \emph{heads} aquí.}.  

\subsection{Conjuntos de cambios de frentes}

Un frente es un cambio que no tiene descendientes, o hijos, como
también se les conoce. La revisión de punta es, por tanto, un frente,
porque la revisión más reciente en un repositorio no tiene ningún
% TODO cambio en la redacción de la frase, pero espero que conserve el
% sentido. Querido human@, apruebe o corrija :D
hijo. Sin embargo, un repositorio puede contener más de un frente.

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-pull}
  \caption{Contenidos del repositorio después de jalar
      \dirname{my-hello} a \dirname{my-new-hello}}
  \label{fig:tour-merge:pull}
\end{figure}

En la figura~\ref{fig:tour-merge:pull} usted puede ver el efecto que
tiene jalar los cambios de \dirname{my-hello} a \dirname{my-new-hello}.
El historial que ya existía en \dirname{my-new-hello} se mantiene
intacto, pero fue añadida una nueva revisión. Refiriéndonos a la
figura~\ref{fig:tour-merge:sep-repos}, podemos ver que el \emph{ID del
conjunto de cambios} se mantiene igual en el nuevo repositorio, pero
el \emph{número de revisión} ha cambiado.  (Incidentalmente, éste es un
buen ejemplo de porqué no es seguro usar números de revisión cuando se
habla de conjuntos de cambios).  Podemos ver los frentes en un
repositorio usando el comando \hgcmd{heads}\ndt{Frentes.}.
\interaction{tour.merge.heads}

\subsection{Hacer la fusión}

% TODO poner interrogante de apertura
Qué pasa si tratamos de usar el comando usual, \hgcmd{update}, para
actualizar el nuevo frente?
\interaction{tour.merge.update}
Mercurial nos indica que el comando \hgcmd{update} no hará la fusión;
no actualizará el directorio de trabajo cuando considera que lo que
deseamos hacer es una fusión, a menos que lo obliguemos a hacerlo.
En vez de \hgcmd{update}, usamos el comando \hgcmd{merge} para hacer
la fusión entre los dos frentes.
\interaction{tour.merge.merge}

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-merge}
  \caption{Directorio de trabajo y repositorio durante la fusión, y
  consignación consecuente}
  \label{fig:tour-merge:merge}
\end{figure}

Esto actualiza el directorio de trabajo, de tal forma que contenga los
cambios de \emph{ambos} frentes, lo que se ve reflejado tanto en la
salida de \hgcmd{parents} como en los contenidos de \filename{hello.c}.
\interaction{tour.merge.parents}

\subsection{Consignar los resultados de la fusión}

Siempre que hacemos una fusión, \hgcmd{parents} mostrará dos padres
hasta que consignemos (\hgcmd{commit}) los resultados de la fusión.
\interaction{tour.merge.commit}
Ahora tenemos una nueva revisión de punta; note que tiene \emph{los
dos} frentes anteriores como sus padres. Estos son las mismas
revisiones que mostró previamente el comando \hgcmd{parents}.
\interaction{tour.merge.tip}
En la figura~\ref{fig:tour-merge:merge} usted puede apreciar una
representación de lo que pasa en el directorio de trabajo durante la
fusión cuando se hace la consignación. Durante la fusión, el
directorio de trabajo tiene dos conjuntos de cambios como sus padres,
y éstos se vuelven los padres del nuevo conjunto de cambios.

\section{Fusionar cambios con conflictos}

La mayoría de las fusiones son algo simple, pero a veces usted se
encontrará fusionando cambios donde más de uno de ellos afecta las
mismas secciones de los mismos ficheros. A menos que ambas
modificaciones sean idénticas, el resultado es un \emph{conflicto}, en
donde usted debe decidir cómo reconciliar ambos cambios y producir un
resultado coherente.

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-conflict}
  \caption{Cambios con conflictos a un documento}
  \label{fig:tour-merge:conflict}
\end{figure}

La figura~\ref{fig:tour-merge:conflict} ilustra un ejemplo con dos
cambios generando conflictos en un documento. Empezamos con una sola
versión de el fichero; luego hicimos algunos cambios; mientras tanto,
alguien más  hizo cambios diferentes en el mismo texto. Lo que debemos
hacer para resolver el conflicto causado por ambos cambios es decidir
cómo debe quedar finalmente el fichero.

Mercurial no tiene ninguna utilidad integrada para manejar conflictos.
En vez de eso, ejecuta un programa externo llamado \command{hgmerge}.
Es un guión de línea de comandos que es instalado junto con Mercurial;
usted puede modificarlo para que se comporte como usted lo desee. Por
defecto, lo que hace es tratar de encontrar una de varias herramientas
para fusionar que es probable que estén instaladas en su sistema.
Primero se intenta con unas herramientas para fusionar cambios
automáticamente; si esto no tiene éxito (porque la fusión demanda
una guía humana) o dichas herramientas no están presentes, el guión
intenta con herramientas gráficas para fusionar.

También es posible hacer que Mercurial ejecute otro programa o guión
en vez de \command{hgmerge}, definiendo la variable de entorno
\envar{HGMERGE} con el nombre del programa de su preferencia.

\subsection{Usar una herramienta gráfica para fusión}

Mi herramienta favorita para hacer fusiones es \command{kdiff3}, y la
usaré para describir las características comunes de las herramientas
gráficas para hacer fusiones. Puede ver una captura de pantalla de
\command{kdiff3} ejecutándose, en la
figura~\ref{fig:tour-merge:kdiff3}.  El tipo de fusión que la
herramienta hace se conoce como \emph{fusión de tres vías}, porque hay
tres versiones diferentes del archivo en que estamos interesados.
Debido a esto la herramienta divide la parte superior de la ventana en
tres paneles.
\begin{itemize}
\item A la izquierda está la revisión \emph{base} del fichero, p.ej.~la
    versión más reciente de la que descienden las dos versiones que
    estamos tratando de fusionar.
\item En la mitad está ``nuestra'' versión del fichero, con las
    modificaciones que hemos hecho.
\item A la derecha está la versión del fichero de ``ellos'', la que
    forma parte del conjunto de cambios que estamos tratando de
    fusionar.
\end{itemize}
En el panel inferior se encuentra el \emph{resultado} actual de la
fusión. Nuestra tarea es reemplazar todo el texto rojo, que muestra
los conflictos sin resolver, con una fusión adecuada de ``nuestra''
versión del fichero y la de ``ellos''.

Los cuatro paneles están \emph{enlazados}; si avanzamos vertical o
horizontalmente en cualquiera de ellos, los otros son actualizados
para mostrar las secciones correspondientes del fichero que tengan
asociado.

\begin{figure}[ht]
  \centering
  \grafix[width=\textwidth]{kdiff3}
  \caption{Usando \command{kdiff3} para fusionar versiones de un
  fichero}
  \label{fig:tour-merge:kdiff3}
\end{figure}

En cada conflicto del fichero podemos escoger resolverlo usando
cualquier combinación del texto de la revisión base, la nuestra, o la
de ellos. También podemos editar manualmente el fichero en que queda
la fusión, si es necesario hacer cambios adicionales.

Hay \emph{muchas} herramientas para fusionar ficheros disponibles. Se
diferencian en las plataformas para las que están disponibles, y en
sus fortalezas y debilidades particulares. La mayoría están afinadas
para fusionar texto plano, mientras que otras están pensadas para
formatos de archivos especializados (generalmente XML).

\subsection{A worked example}

In this example, we will reproduce the file modification history of
figure~\ref{fig:tour-merge:conflict} above.  Let's begin by creating a
repository with a base version of our document.
\interaction{tour-merge-conflict.wife}
We'll clone the repository and make a change to the file.
\interaction{tour-merge-conflict.cousin}
And another clone, to simulate someone else making a change to the
file.  (This hints at the idea that it's not all that unusual to merge
with yourself when you isolate tasks in separate repositories, and
indeed to find and resolve conflicts while doing so.)
\interaction{tour-merge-conflict.son}
Having created two different versions of the file, we'll set up an
environment suitable for running our merge.
\interaction{tour-merge-conflict.pull}

In this example, I won't use Mercurial's normal \command{hgmerge}
program to do the merge, because it would drop my nice automated
example-running tool into a graphical user interface.  Instead, I'll
set \envar{HGMERGE} to tell Mercurial to use the non-interactive
\command{merge} command.  This is bundled with many Unix-like systems.
If you're following this example on your computer, don't bother
setting \envar{HGMERGE}.
\interaction{tour-merge-conflict.merge}
Because \command{merge} can't resolve the conflicting changes, it
leaves \emph{merge markers} inside the file that has conflicts,
indicating which lines have conflicts, and whether they came from our
version of the file or theirs.

Mercurial can tell from the way \command{merge} exits that it wasn't
able to merge successfully, so it tells us what commands we'll need to
run if we want to redo the merging operation.  This could be useful
if, for example, we were running a graphical merge tool and quit
because we were confused or realised we had made a mistake.

If automatic or manual merges fail, there's nothing to prevent us from
``fixing up'' the affected files ourselves, and committing the results
of our merge:
\interaction{tour-merge-conflict.commit}

\section{Simplifying the pull-merge-commit sequence}
\label{sec:tour-merge:fetch}

The process of merging changes as outlined above is straightforward,
but requires running three commands in sequence.
\begin{codesample2}
  hg pull
  hg merge
  hg commit -m 'Merged remote changes'
\end{codesample2}
In the case of the final commit, you also need to enter a commit
message, which is almost always going to be a piece of uninteresting
``boilerplate'' text.

It would be nice to reduce the number of steps needed, if this were
possible.  Indeed, Mercurial is distributed with an extension called
\hgext{fetch} that does just this.

Mercurial provides a flexible extension mechanism that lets people
extend its functionality, while keeping the core of Mercurial small
and easy to deal with.  Some extensions add new commands that you can
use from the command line, while others work ``behind the scenes,''
for example adding capabilities to the server.

The \hgext{fetch} extension adds a new command called, not
surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
changes from another repository into the current repository.  If it
finds that the changes added a new head to the repository, it begins a
merge, then commits the result of the merge with an
automatically-generated commit message.  If no new heads were added,
it updates the working directory to the new tip changeset.

Enabling the \hgext{fetch} extension is easy.  Edit your
\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
or create an \rcsection{extensions} section.  Then add a line that
simply reads ``\Verb+fetch +''.
\begin{codesample2}
  [extensions]
  fetch =
\end{codesample2}
(Normally, on the right-hand side of the ``\texttt{=}'' would appear
the location of the extension, but since the \hgext{fetch} extension
is in the standard distribution, Mercurial knows where to search for
it.)

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: