igor@374: \chapter{Encontrar y arreglar sus equivocaciones} jerojasro@343: \label{chap:undo} jerojasro@343: igor@374: Errar es humano, pero tratar adecuadamente las consecuencias requiere igor@374: un sistema de control de revisiones de primera categoría. En este igor@374: capítulo, discutiremos algunas técnicas que puede usar cuando igor@374: encuentra que hay un problema enraizado en su proyecto. Mercurial igor@374: tiene unas características poderosas que le ayudarán a isolar las igor@374: fuentes de los problemas, y a dar cuenta de ellas apropiadamente. igor@374: jerojasro@516: \section{Borrar el historial local} igor@374: igor@374: \subsection{La consignación accidental} igor@374: igor@374: Tengo el problema ocasional, pero persistente de teclear más rápido de igor@374: lo que pienso, que aveces resulta en consignar un conjunto de cambios igor@374: incompleto o simplemente malo. En mi caso, el conjunto de cambios igor@378: incompleto consiste en que creé un nuevo fichero fuente, pero olvidé igor@374: hacerle \hgcmd{add}. Un conjunto de cambios``simplemente malo'' no es igor@374: tan común, pero sí resulta muy molesto. igor@374: igor@378: \subsection{Hacer rollback una transacción} jerojasro@343: \label{sec:undo:rollback} jerojasro@343: igor@374: En la sección~\ref{sec:concepts:txn}, mencioné que Mercurial trata igor@374: modificación a un repositorio como una \emph{transacción}. Cada vez igor@374: que consigna un conjunto de cambios o lo jala de otro repositorio, igor@378: Mercurial recuerda lo que hizo. Puede deshacer, o hacer \emph{roll back}\ndt{El significado igual que en los igor@378: ambientes de sistemas manejadores de bases de datos se refiere a igor@378: la atomicidad e integridad al devolver un conjunto de acciones que igor@378: permitan dejar el repositorio en un estado consistente previo}, igor@374: exactamente una de tales acciones usando la orden \hgcmd{rollback}. igor@374: (Ver en la sección~\ref{sec:undo:rollback-after-push} una anotación igor@374: importante acerca del uso de esta orden.) igor@374: igor@374: A continuación una equivocación que me sucede frecuentemente: igor@374: consignar un cambio en el cual he creado un nuevo fichero, pero he igor@374: olvidado hacerle \hgcmd{add}. jerojasro@343: \interaction{rollback.commit} igor@374: La salida de \hgcmd{status} después de la consignación confirma igor@374: inmediatamente este error. jerojasro@343: \interaction{rollback.status} igor@378: La consignación capturó los cambios en el fichero \filename{a}, pero igor@374: no el nuevo fichero \filename{b}. Si yo publicara este conjunto de igor@374: cambios a un repositorio compartido con un colega, es bastante igor@374: probable que algo en \filename{a} se refiriera a \filename{b}, el cual igor@374: podría no estar presente cuando jalen mis cambios del repositorio. Me igor@374: convertiría el sujeto de cierta indignación. igor@374: igor@374: Como sea, la suerte me acompaña---Encontré mi error antes de publicar igor@374: el conjunto de cambios. Uso la orden \hgcmd{rollback}, y Mercurial igor@374: hace desaparecer el último conjunto de cambios. jerojasro@343: \interaction{rollback.rollback} jerojasro@516: El conjunto de cambios ya no está en el historial del repositorio, y el igor@374: directorio de trabajo cree que el fichero \filename{a} ha sido igor@377: modificado. La consignación y el roll back dejaron el directorio de igor@377: trabajo exactamente como estaba antes de la consignación; el conjunto igor@374: de cambios ha sido eliminado totlamente. Ahora puedo hacer \hgcmd{add} igor@374: al fichero \filename{b}, y hacer de nuevo la consignación. jerojasro@343: \interaction{rollback.add} jerojasro@343: igor@374: \subsection{Erroneamente jalado} igor@374: igor@374: Mantener ramas de desarrollo separadas de un proyecto en distintos igor@374: repositorios es una práctica común con Mercurial. Su equipo de igor@374: desarrollo puede tener un repositorio compartido para la versión ``0.9'' igor@374: y otra con cambios distintos para la versión ``1.0''. igor@374: igor@374: Con este escenario, puede imaginar las consecuencias si tuviera un igor@374: repositorio local ``0.9'', y jalara accidentalmente los cambios del igor@374: repositorio compartido de la versión ``1.0'' en este. En el peor de igor@374: los casos, por falta de atención, es posible que publique tales igor@374: cambios en el árbol compartido ``0.9'', confundiendo a todo su equipo jerojasro@520: de trabajo (pero no se preocupe, volveremos a este terrorífico igor@374: escenario posteriormente). En todo caso, es muy probable que usted se igor@374: de cuenta inmediatamente, dado que Mercurial mostrará el URL de donde igor@374: está jalando, o que vea jalando una sospechosa gran cantidad de igor@374: cambios en el repositorio. igor@374: igor@377: La orden \hgcmd{rollback} excluirá eficientemente los conjuntos de igor@377: cambios que haya acabado de jalar. Mercurial agrupa todos los cambios igor@377: de un \hgcmd{pull} a una única transacción y bastará con un igor@377: \hgcmd{rollback} para deshacer esta equivocación. igor@377: igor@377: \subsection{Después de publicar, un roll back es futil} jerojasro@343: \label{sec:undo:rollback-after-push} jerojasro@343: igor@377: El valor de \hgcmd{rollback} se anula cuando ha publicado sus cambios igor@377: a otro repositorio. Un cambio desaparece totalmente al hacer roll back, igor@377: pero \emph{solamente} en el repositorio en el cual aplica jerojasro@516: \hgcmd{rollback}. Debido a que un roll back elimina el historial, igor@377: no hay forma de que la desaparición de un cambio se propague entre igor@377: repositorios. igor@377: igor@377: Si ha publicado un cambio en otro repositorio---particularmente si es igor@377: un repositorio público---esencialmente está ``en terreno agreste,'' igor@377: y tendrá que reparar la equivocación de un modo distinto. Lo que igor@377: pasará si publica un conjunto de cambios en algún sitio, hacer igor@377: rollback y después volver a jalar del repositorio del cual había igor@377: publicado, es que el conjunto de cambios reaparecerá en su repositorio. igor@377: igor@377: (Si está absolutamente segruro de que el conjunto de cambios al que igor@377: desea hacer rollback es el cambio más reciente del repositorio en el igor@377: cual publicó, \emph{y} sabe que nadie más pudo haber jalado de tal igor@377: repositorio, puede hacer rollback del conjunto de cambios allí, pero igor@377: es mejor no confiar en una solución de este estilo. Si lo hace, tarde igor@377: o temprano un conjunto de cambios logrará colarse en un repositorio jerojasro@520: que usted no controle directamente (o del cual se ha olvidado), y igor@377: volverá a hostigarle.) igor@377: igor@377: \subsection{Solamente hay un roll back} igor@377: igor@377: Mercurial almacena exactamente una transacción en su bitácora de igor@377: transacciones; tal transacción es la más reciente de las que haya igor@377: ocurrido en el repositorio. Esto significa que solamente puede hacer igor@377: roll back a una transacción. Si espera poder hacer roll back a una igor@377: transacción después al antecesor, observará que no es el igor@377: comportamiento que obtendrá. jerojasro@343: \interaction{rollback.twice} igor@377: Una vez que haya aplicado un rollback en una transacción a un igor@377: repositorio, no podrá volver a hacer rollback hasta que haga una igor@377: consignación o haya jalado. jerojasro@343: igor@386: \section{Revertir un cambio equivocado} igor@386: igor@386: Si modifica un fichero y se da cuenta que no quería realmente cambiar igor@386: tal fichero, y todavía no ha consignado los cambios, la orden igor@386: necesaria es \hgcmd{revert}. Observa el conjunto de cambios padre del igor@386: directorio y restaura los contenidos del fichero al estado de tal igor@386: conjunto de cambios. (Es una forma larga de decirlo, usualmente igor@386: deshace sus modificaciones.) igor@386: igor@386: Ilustremos como actúa la orden \hgcmd{revert} con un ejemplo igor@386: pequeño. Comenzaremos modificando un fichero al cual Mercurial ya está igor@386: siguiendo. jerojasro@343: \interaction{daily.revert.modify} igor@386: Si no queremos ese cambio, podemos aplicar \hgcmd{revert} al fichero. jerojasro@343: \interaction{daily.revert.unmodify} igor@386: La orden \hgcmd{revert} nos brinda un grado adicional de seguridad igor@386: guardando nuestro fichero modificado con la extensión \filename{.orig}. jerojasro@343: \interaction{daily.revert.status} jerojasro@343: igor@386: Este es un resumen de casos en los cuales la orden \hgcmd{revert} es igor@386: de utilidad. Describiremos cada uno de ellos con más detalle en la igor@386: sección siguiente. jerojasro@343: \begin{itemize} igor@386: \item Si usted modifica un fichero, lo restaurará a su estado sin igor@386: modificación previo. igor@386: \item Si usted hace \hgcmd{add} a un fichero, revertirá el estado de igor@386: ``adicionado'' del fichero, pero no lo tocará igor@386: \item Si borra un fichero sin decirle a Mercurial, restaurará el igor@386: fichero con sus contenidos sin modificación. igor@386: \item Si usa la orden \hgcmd{remove} para eliminar un fichero, deshará igor@386: el estado ``removido'' del fichero, y lo restaurará con sus igor@386: contenidos sin modificación. jerojasro@343: \end{itemize} jerojasro@343: igor@386: \subsection{Errores al administrar ficheros} jerojasro@343: \label{sec:undo:mgmt} jerojasro@343: igor@386: La orden \hgcmd{revert} es útil para más que ficheros modificados. Le igor@386: permite reversar los resultados de todas las órdenes de administración igor@386: de ficheros que provee Mercurial---\hgcmd{add}, \hgcmd{remove}, y las igor@386: demás. igor@386: igor@386: Si usted hace \hgcmd{add} a un fichero, y no deseaba que Mercurial le igor@386: diera seguimiento, use \hgcmd{revert} para deshacer la adición. No se igor@386: preocupe; Mercurial no modificará de forma alguna el fichero. igor@386: Solamente lo ``desmarcará''. jerojasro@343: \interaction{daily.revert.add} jerojasro@343: igor@386: De forma similar, Si le solicita a Mercurial hacer \hgcmd{remove} a un igor@386: fichero, puede usar \hgcmd{revert} para restarurarlo a los contenidos igor@386: que tenía la revisión padre del directorio de trabajo. jerojasro@343: \interaction{daily.revert.remove} igor@386: Funciona de la misma manera para un fichero que usted haya eliminado igor@386: manualmente, sin decirle a Mercurial (recuerde que en la terminología igor@386: de Mercurial esta clase de fichero se llama ``faltante''). jerojasro@343: \interaction{daily.revert.missing} jerojasro@343: igor@386: Si usted revierte un \hgcmd{copy}, el fichero a donde se copió igor@386: permanece en su directorio de trabajo, pero sin seguimiento. Dado que igor@386: una copia no afecta el fichero fuente de copiado de ninguna maner, igor@386: Mercurial no hace nada con este. jerojasro@343: \interaction{daily.revert.copy} jerojasro@343: igor@386: \subsubsection{Un caso ligeramente especial:revertir un renombramiento} igor@386: igor@386: Si hace \hgcmd{rename} a un fichero, hay un detalle que debe tener en igor@386: cuenta. Cuando aplica \hgcmd{revert} a un cambio de nombre, no es igor@386: suficiente proveer el nombre del fichero destino, como puede verlo en igor@386: el siguiente ejemplo. jerojasro@343: \interaction{daily.revert.rename} igor@386: Como puede ver en la salida de \hgcmd{status}, el fichero con el nuevo igor@386: nombre no se identifica más como agregado, pero el fichero con el igor@386: nombre-\emph{inicial} se elimna! Esto es contra-intuitivo (por lo igor@386: menos para mí), pero por lo menos es fácil arreglarlo. jerojasro@343: \interaction{daily.revert.rename-orig} igor@386: Por lo tanto, recuerde, para revertir un \hgcmd{rename}, debe proveer igor@386: \emph{ambos} nombres, la fuente y el destino. jerojasro@343: jerojasro@343: % TODO: the output doesn't look like it will be removed! jerojasro@343: igor@386: (A propósito, si elimina un fichero, y modifica el fichero con el igor@386: nuevo nombre, al revertir ambos componentes del renombramiento, cuando igor@386: Mercurial restaure el fichero que fue eliminado como parte del igor@386: renombramiento, no será modificado. igor@400: Si necesita que las modificaciones en el fichero destino del igor@386: renombramiento se muestren, no olvide copiarlas encima.) igor@386: igor@387: Estos aspectos engorrosos al revertir un renombramiento se constituyen igor@386: discutiblemente en un fallo de Mercurial. jerojasro@343: igor@387: \section{Tratar cambios consignados} igor@387: igor@387: Considere un caso en el que ha consignado el cambio $a$, y otro cambio igor@387: $b$ sobre este; se ha dado cuenta que el cambio $a$ era igor@387: incorrecto. Mercurial le permite ``retroceder'' un conjunto de cambios igor@387: completo automáticamente, y construir bloques que le permitan revertir igor@387: parte de un conjunto de cambios a mano. igor@387: igor@387: Antes de leer esta sección, hay algo para tener en cuenta: la orden jerojasro@518: \hgcmd{backout} deshace cambios \emph{adicionando} al historial, sin igor@387: modificar o borrar. Es la herramienta correcta si está arreglando igor@387: fallos, pero no si está tratando de deshacer algún cambio que tiene igor@387: consecuencias catastróficas. Para tratar con esos, vea la sección~\ref{sec:undo:aaaiiieee}. igor@387: igor@387: \subsection{Retroceder un conjunto de cambios} igor@387: igor@387: La orden \hgcmd{backout} le permite ``deshacer'' los efectos de todo jerojasro@516: un conjunto de cambios de forma automatizada. Dado que el historial de igor@387: Mercurial es inmutable, esta orden \emph{no} se deshace del conjunto igor@387: de cambios que usted desea deshacer. En cambio, crea un nuevo igor@387: conjunto de cambios que \emph{reversa} el conjunto de cambios que igor@387: usted indique. igor@387: igor@387: La operación de la orden \hgcmd{backout} es un poco intrincada, y lo igor@387: ilustraremos con algunos ejemplos. Primero crearemos un repositorio igor@387: con algunos cambios sencillos. jerojasro@343: \interaction{backout.init} jerojasro@343: igor@387: La orden \hgcmd{backout} toma un ID de conjunto de cambios como su igor@387: argumento; el conjunto de cambios a retroceder. Normalmente igor@387: \hgcmd{backout} le ofrecerá un editor de texto para escribir el igor@387: mensaje de la consignación, para dejar un registro de por qué está igor@387: retrocediendo. En este ejemplo, colocamos un mensaje en la jerojasro@522: consignación usando la opción \hgopt{backout}{-m}. igor@387: igor@388: \subsection{Retroceder el conjunto de cambios punta} igor@387: igor@387: Comenzamos retrocediendo el último conjunto de cambios que consignamos. jerojasro@343: \interaction{backout.simple} igor@387: Puede ver que la segunda línea de \filename{myfile} ya no está igor@387: presente. La salida de \hgcmd{log} nos da una idea de lo que la orden igor@387: \hgcmd{backout} ha hecho. jerojasro@343: \interaction{backout.simple.log} igor@387: Vea que el nuevo conjunto de cambios que \hgcmd{backout} ha creado es igor@387: un hijo del conjunto de cambios que retrocedimos. Es más sencillo de igor@387: ver en la figura~\ref{fig:undo:backout}, que presenta una vista jerojasro@517: gráfica del historial de cambios. Como puede ver, el historial es jerojasro@516: bonito y lineal. jerojasro@343: jerojasro@343: \begin{figure}[htb] jerojasro@343: \centering jerojasro@343: \grafix{undo-simple} igor@387: \caption{Retroceso de un cambio con la orden \hgcmd{backout}} jerojasro@343: \label{fig:undo:backout} jerojasro@343: \end{figure} jerojasro@343: igor@388: \subsection{Retroceso de un cambio que no es la punta} igor@387: igor@387: Si desea retrocede un cambio distinto al último que ha consignado, use igor@387: la opción \hgopt{backout}{--merge} a la orden \hgcmd{backout}. jerojasro@343: \interaction{backout.non-tip.clone} igor@387: Que resulta en un retroceso de un conjunto de cambios ``en un sólo igor@387: tiro'', una operación que resulta normalmente rápida y sencilla. jerojasro@343: \interaction{backout.non-tip.backout} jerojasro@343: igor@387: Si ve los contenidos del fichero \filename{myfile} después de igor@387: finalizar el retroceso, verá que el primer y el tercer cambio están igor@387: presentes, pero no el segundo. jerojasro@343: \interaction{backout.non-tip.cat} jerojasro@343: jerojasro@516: Como lo muestra el historial gráfico en la igor@387: figura~\ref{fig:undo:backout-non-tip}, Mercurial realmente consigna igor@387: \emph{dos} cambios en estas situaciones (los nodos encerrados en una igor@387: caja son aquellos que Mercurial consigna automaticamente). Antes de igor@387: que Mercurial comience el proceso de retroceso, primero recuerda cuál igor@387: es el padre del directorio de trabajo. Posteriormente hace un igor@387: retroceso al conjunto de cambios objetivo y lo consigna como un igor@387: conjunto de cambios. Finalmente, fusiona con el padre anterior del igor@387: directorio de trabajo, y consigna el resultado de la fusión. jerojasro@343: jerojasro@343: % TODO: to me it looks like mercurial doesn't commit the second merge automatically! jerojasro@343: jerojasro@343: \begin{figure}[htb] jerojasro@343: \centering jerojasro@343: \grafix{undo-non-tip} igor@388: \caption{Retroceso automatizado de un cambio a algo que no es la punta con la orden \hgcmd{backout}} jerojasro@343: \label{fig:undo:backout-non-tip} jerojasro@343: \end{figure} jerojasro@343: igor@387: El resultado es que usted termina ``donde estaba'', solamente con un jerojasro@516: poco de historial adicional que deshace el efecto de un conjunto de igor@387: cambios que usted quería evitar. jerojasro@343: igor@388: \subsubsection{Use siempre la opción \hgopt{backout}{--merge}} igor@388: igor@388: De hecho, dado que la opción \hgopt{backout}{--merge} siempre hara lo igor@388: ``correcto'' esté o no retrocediendo el conjunto de cambios punta igor@388: (p.e.~no tratará de fusionar si está retrocediendo la punta, dado que igor@388: no es necesario), usted debería usar \emph{siempre} esta opción cuando igor@388: ejecuta la orden \hgcmd{backout}. igor@388: igor@388: \subsection{Más control sobre el proceso de retroceso} igor@388: igor@388: A pesar de que recomiendo usar siempre la opción igor@388: \hgopt{backout}{--merge} cuando está retrocediendo un cambio, la orden igor@388: \hgcmd{backout} le permite decidir cómo mezclar un retroceso de un igor@388: conjunto de cambios. Es muy extraño que usted necestite tomar control igor@388: del proceso de retroceso de forma manual, pero puede ser útil entender igor@388: lo que la orden \hgcmd{backout} está haciendo automáticamente para igor@388: usted. Para ilustrarlo, clonemos nuestro primer repositorio, pero igor@388: omitamos el retroceso que contiene. jerojasro@343: jerojasro@343: \interaction{backout.manual.clone} igor@388: Como en el ejemplo anterior, consignaremos un tercer cambio, después igor@388: haremos retroceso de su padre, y veremos qué pasa. jerojasro@343: \interaction{backout.manual.backout} igor@388: Nuestro nuevo conjunto de cambios es de nuevo un descendiente del igor@388: conjunto de cambio que retrocedimos; es por lo tanto una nueva cabeza, igor@388: \emph{no} un descendiente del conjunto de cambios que era la punta. La igor@388: orden \hgcmd{backout} fue muy explícita diciéndolo. jerojasro@343: \interaction{backout.manual.log} jerojasro@343: jerojasro@516: De nuevo, es más sencillo lo que pasó viendo una gráfica del jerojasro@516: historial de revisiones, en la figura~\ref{fig:undo:backout-manual}. igor@388: Esto nos aclara que cuando usamos \hgcmd{backout} para retroceder un igor@388: cambio a algo que no sea la punta, Mercurial añade una nueva cabeza al igor@388: repositorio (el cambio que consignó está encerrado en una caja). jerojasro@343: jerojasro@343: \begin{figure}[htb] jerojasro@343: \centering jerojasro@343: \grafix{undo-manual} igor@388: \caption{Retroceso usando la orden \hgcmd{backout}} jerojasro@343: \label{fig:undo:backout-manual} jerojasro@343: \end{figure} jerojasro@343: igor@388: Después de que la orden \hgcmd{backout} ha terminado, deja un nuevo igor@388: conjunto de cambios de ``retroceso'' como el padre del directorio de trabajo. jerojasro@343: \interaction{backout.manual.parents} igor@388: Ahora tenemos dos conjuntos de cambios aislados. jerojasro@343: \interaction{backout.manual.heads} jerojasro@343: igor@388: Reflexionemos acerca de lo que esperamos ver como contenidos de igor@388: \filename{myfile}. El primer cambio debería estar presente, porque igor@388: nunca le hicimos retroceso. El segundo cambio debió desaparecer, jerojasro@517: puesto que es el que retrocedimos. Dado que la gráfica del historial igor@388: muestra que el tercer camlio es una cabeza separada, \emph{no} igor@388: esperamos ver el tercer cambio presente en \filename{myfile}. jerojasro@343: \interaction{backout.manual.cat} igor@400: Para que el tercer cambio esté en el fichero, hacemos una fusión usual igor@388: de las dos cabezas. jerojasro@343: \interaction{backout.manual.merge} jerojasro@516: Después de eso, el historial gráfica de nuestro repositorio luce como igor@388: la figura~\ref{fig:undo:backout-manual-merge}. jerojasro@343: jerojasro@343: \begin{figure}[htb] jerojasro@343: \centering jerojasro@343: \grafix{undo-manual-merge} igor@388: \caption{Fusión manual de un retroceso} jerojasro@343: \label{fig:undo:backout-manual-merge} jerojasro@343: \end{figure} jerojasro@343: igor@388: \subsection{Por qué \hgcmd{backout} hace lo que hace} igor@388: igor@388: Esta es una descripción corta de cómo trabaja la orden \hgcmd{backout}. jerojasro@343: \begin{enumerate} igor@388: \item Se asegura de que el directorio de trabajo es ``limpio'', esto igor@388: es, que la salida de \hgcmd{status} debería ser vacía. igor@388: \item Recuerda el padre actual del directorio de trabajo. A este igor@388: conjunto de cambio lo llamaremos \texttt{orig} igor@388: \item Hace el equivalente de un \hgcmd{update} para sincronizar el igor@388: directorio de trabajo con el conjunto de cambios que usted quiere igor@388: retroceder. Lo llamaremos \texttt{backout} igor@388: \item Encuentra el padre del conjunto de cambios. Lo llamaremos igor@388: \texttt{parent}. igor@400: \item Para cada fichero del conjunto de cambios que el igor@388: \texttt{retroceso} afecte, hará el equivalente a igor@388: \hgcmdargs{revert}{-r parent} sobre ese fichero, para restaurarlo a igor@388: los contenidos que tenía antes de que el conjunto de cambios fuera igor@388: consignado. igor@388: \item Se consigna el resultado como un nuevo conjunto de cambios y igor@388: tiene a \texttt{backout} como su padre. igor@388: \item Si especifica \hgopt{backout}{--merge} en la línea de comandos, igor@388: se fusiona con \texttt{orig}, y se consigna el resultado de la igor@388: fusión. jerojasro@343: \end{enumerate} jerojasro@343: igor@388: Una vía alternativa de implementar la orden \hgcmd{backout} sería usar igor@388: \hgcmd{export} sobre el conjunto de cambios a retroceder como un diff igor@388: y después usar laa opción \cmdopt{patch}{--reverse} de la orden igor@388: \command{patch} para reversar el efecto del cambio sin molestar el igor@388: directorio de trabajo. Suena mucho más simple, pero no funcionaría igor@388: bien ni de cerca. igor@388: igor@388: La razón por la cual \hgcmd{backout} hace una actualización, una igor@388: consignación, una fusión y otra consignación es para dar a la igor@388: maquinaria de fusión la mayor oportunidad de hacer un buen trabajo igor@388: cuando se trata con todos los cambios \emph{entre} el cambio que está igor@388: retrocediendo y la punta actual. igor@388: igor@388: Si está retrocediendo un conjunto de cambios que está a unas ~100 jerojasro@516: atrás en su historial del proyecto, las posibilidades de que una orden igor@388: \command{patch} sea capaz de ser aplicada a un diff reverso, igor@388: claramente no son altas, porque los cambios que intervienen podrían igor@388: ``no coincidir con el contexto'' que \command{patch} usa para igor@388: determinar si puede aplicar un parche (si esto suena como cháchara, igor@388: vea una discusión de la orden \command{patch} en \ref{sec:mq:patch}). igor@388: Adicionalmente, la maquinaria de fusión de Mercurial manejará ficheros igor@388: y directorios renombrados, cambios de permisos, y modificaciones a igor@400: ficheros binarios, nada de lo cual la orden \command{patch} puede manejar. jerojasro@343: igor@389: \section{Cambios que nunca debieron ocurrir} jerojasro@343: \label{sec:undo:aaaiiieee} jerojasro@343: igor@389: En la mayoría de los casos, la orden \hgcmd{backout} es exactamente lo igor@389: que necesita para deshacer los efectos de un cambio. Deja un registro igor@389: permanente y exacto de lo que usted hizo, cuando se consignó el igor@389: conjunto de cambios original y cuando se hizo la limpieza. igor@389: igor@389: En ocasiones particulares, puede haber consignado un cambio que no igor@389: debería estar de ninguna forma en el repositorio. Por ejemplo, sería igor@389: muy inusual, y considerado como una equivocación, consignar los igor@400: ficheros objeto junto con el código fuente. los ficheros objeto no igor@389: tienen valor intrínseco y son \emph{grandes}, por lo tanto aumentan el igor@389: tamaño del repositorio y la cantidad de tiempo que se emplea al clonar igor@389: o jalar cambios. igor@389: igor@389: Antes de discutir las opciones que tiene si consignó cambio del tipo igor@389: ``bolsa de papel deschable'' (el tipo que es tan malo que le gustaría igor@389: colocarse una bolsa de papel desechable en su cabeza), permítame igor@389: discutir primero unas aproximaciones que probablemente no funcionen. igor@389: jerojasro@516: Dado que Mercurial trata de forma acumulativa al historial---cada jerojasro@516: cambio se coloca encima de todos los cambios que le jerojasro@516: preceden---usualmente usted no puede hacer que unos cambios desastrosos igor@389: desaparezcan. La única excepción es cuando usted ha acabado de igor@389: consignar un cambio y este no ha sido publicado o jalado en otro igor@389: repositorio. Ahí es cuando puede usar la orden \hgcmd{rollback} con jerojasro@516: seguridad, como detallé en la sección~\ref{sec:undo:rollback}. igor@389: igor@389: Después de que usted haya publicado un cambio en otro repositorio, usted igor@389: \emph{podría} usar la orden \hgcmd{rollback} para hacer que en su copia igor@389: local desaparezca el cambio, pero no tendrá las consecuencias que igor@389: desea. El cambio estará presente en un repositorio remoto, y igor@389: reaparecerá en su repositorio local la próxima vez que jale igor@389: igor@389: Si una situación como esta se presenta, y usted sabe en qué igor@389: repositorios su mal cambio se ha propagado, puede \emph{intentar} igor@389: deshacerse del conjunto de cambios de \emph{todos} los repositorios en igor@389: los que se pueda encontrar. Esta por supuesto, no es una solución igor@389: satisfactoria: si usted deja de hacerlo en un solo repositorio, igor@389: mientras esté eliminándolo, el cambio todavía estará ``allí afuera'', igor@389: y podría propagarse más tarde. igor@389: igor@389: Si ha consignado uno o más cambios \emph{después} del cambio que desea igor@389: desaparecer, sus opciones son aún más reducidas. Mercurial no provee jerojasro@516: una forma de ``cabar un hueco'' en el historial, dejando los conjuntos igor@389: de cambios intactos. igor@389: igor@389: %Dejamos de traducir lo que viene a continuación, porque será igor@389: %modificado por upstream... jerojasro@343: jerojasro@343: XXX This needs filling out. The \texttt{hg-replay} script in the jerojasro@343: \texttt{examples} directory works, but doesn't handle merge jerojasro@343: changesets. Kind of an important omission. jerojasro@343: igor@397: \subsection{Cómo protegerse de cambios que han ``escapado''} igor@397: igor@397: Si ha consignado cambios a su repositorio local y estos han sido igor@397: publicados o jalados en cualquier otro sitio, no es necesariamente un igor@397: desastre. Puede protegerse de antemano de ciertas clases de conjuntos igor@397: de cambios malos. Esto es particularmente sencillo si su equipo de igor@397: trabajo jala cambios de un repositorio central. igor@397: jerojasro@458: Al configurar algunos ganchos en el repositorio central para validar jerojasro@520: conjuntos de cambios (ver capítulo~\ref{chap:hook}), puede prevenir la igor@397: publicación automáticamente de cierta clase de cambios malos. Con tal igor@397: configuración, cierta clase de conjuntos de cambios malos tenderán igor@397: naturalmente a``morir'' debido a que no pueden propagarse al igor@397: repositorio central. Esto sucederá sin necesidad de intervención igor@397: explícita. igor@397: igor@397: Por ejemplo, un gancho de cambios de entrada que verifique que un igor@397: conjunto de cambios compila, puede prevenir que la gente ``rompa igor@397: la compilación'' inadvertidamente. igor@397: igor@397: \section{Al encuentro de la fuente de un fallo} jerojasro@343: \label{sec:undo:bisect} jerojasro@343: igor@397: Aunque es muy bueno poder retroceder el conjunto de cambios que igor@397: originó un fallo, se requiere que usted sepa cual conjunto de cambios igor@397: retroceder. Mercurial brinda una orden invaluable, llamada igor@397: \hgcmd{bisect}, que ayuda a automatizar este proceso y a alcanzarlo igor@397: muy eficientemente. igor@397: igor@397: La idea tras la orden \hgcmd{bisect} es que el conjunto de cambios que igor@397: ha introducido un cambio de comportamiento pueda identificarse con una igor@397: prueba binaria sencilla. No tiene que saber qué pieza de código igor@397: introdujo el cambio, pero si requiere que sepa cómo probar la igor@397: existencia de un fallo. La orden \hgcmd{bisect} usa su prueba para igor@397: dirigir su búsqueda del conjunto de cambios que introdujo el código igor@397: causante del fallo. igor@397: igor@397: A continuación un conjunto de escenarios que puede ayudarle a entender igor@397: cómo puede aplicar esta orden. jerojasro@343: \begin{itemize} igor@397: \item La versión más reciente de su programa tiene un fallo que usted igor@397: recuerda no estaba hace unas semanas, pero no sabe cuándo fue igor@397: introducido. En este caso, su prueba binaria busca la presencia de igor@397: tal fallo. igor@397: \item Usted arregló un fallo en un apurto, y es hora de dar por igor@397: cerrado el caso en la base de datos de fallos de su equipo de igor@397: trabajo. La base de datos de fallos requiere el ID del conjunto de igor@397: cambios que permita dar por cerrado el caso, pero usted no recuerda igor@397: qué conjunto de cambios arregló tal fallo. De nuevo la prueba igor@397: binaria revisa la presencia del fallo. igor@397: \item Su programa funciona correctamente, pero core ~15\% más lento igor@397: que la última vez que lo midió. Usted desea saber qué conjunto de igor@397: cambios introdujo esta disminución de desempeño. En este caso su igor@397: prueba binaria mide el desempeño de su programa, para ver dónde es igor@397: ``rápido'' y dónde es ``lento''. igor@397: \item Los tamaños de los componentes del proyecto que usted lleva se igor@397: expandieron recientemente, y sospecha que algo cambio en la forma en igor@397: que se construye su proyecto. jerojasro@343: \end{itemize} jerojasro@343: igor@397: Para estos ejemplos debería ser claro que la orden \hgcmd{bisect} igor@397: es útil no solamente para encontrar la fuente de los fallos. Puede igor@397: usarla para encontrar cualquier ``propiedad emergente'' de un jerojasro@520: repositorio (Cualquier cosa que usted no pueda encontrar con una igor@400: búsqueda de texto sencilla sobre los ficheros en el árbol) para la igor@397: cual pueda escribir una prueba binaria. igor@397: igor@397: A continuación introduciremos algo terminología, para aclarar qué igor@397: partes del proceso de búsqueda son su responsabilidad y cuáles de igor@397: Mercurial. Una \emph{prueba} es algo que \emph{usted} ejecuta cuando igor@397: \hgcmd{bisect} elige un conjunto de cambios. Un \emph{sondeo} es lo que igor@397: \hgcmd{bisect} ejecuta para decidir si una revisión es buena. Finalmente, igor@397: usaremos la palabra ``biseccionar', en frases como ``buscar con la igor@397: orden \hgcmd{bisect}''. igor@397: igor@397: Una forma sencilla de automatizar el proceso de búsqueda sería probar igor@397: cada conjunto de cambios. Lo cual escala muy poco. Si le tomó diez igor@397: minutos hacer pruebas sobre un conjunto de cambios y tiene 10.000 igor@397: conjuntos de cambios en su repositorio, esta aproximación exhaustiva igor@397: tomaría en promedio~35 \emph{días} para encontrar el conjunto de igor@397: cambios que introdujo el fallo. Incluso si supiera que el fallo se igor@397: introdujo en un de los últimos 500 conjuntos de cambios y limitara la igor@397: búsqueda a ellos, estaría tomabdi más de 40 horas para encontrar al igor@397: conjunto de cambios culpable. igor@397: jerojasro@516: La orden \hgcmd{bisect} usa su conocimiento de la ``forma'' del jerojasro@516: historial de revisiones de su proyecto para hacer una búsqueda igor@397: proporcional al \emph{logaritmo} del número de conjunto de cambios a jerojasro@516: revisar (el tipo de búsqueda que realiza se llama búsqueda igor@397: binaria). Con esta aproximación, el buscar entre 10.000 conjuntos de jerojasro@516: cambios tomará menos de 3 horas, incluso a diez minutos por prueba (La igor@397: búsqueda requerirá cerca de 14 pruebas). Al limitar la búsqueda a la igor@397: última centena de conjuntos de cambios, tomará a lo sumo una jerojasro@516: hora (Apenas unas 7 pruebas). igor@397: igor@397: La orden \hgcmd{bisect} tiene en cuenta la naturaleza ``ramificada'' jerojasro@517: del historial de revisiones del proyecto con Mercurial, así que no igor@397: hay problemas al tratar con ramas, fusiones o cabezas múltiples en un jerojasro@516: repositorio. Puede evitar ramas enteras de historial con un solo igor@397: sondeo. jerojasro@343: igor@398: \subsection{Uso de la orden \hgcmd{bisect}} igor@398: igor@398: A continuación un ejemplo de \hgcmd{bisect} en acción. jerojasro@343: jerojasro@343: \begin{note} igor@398: En las versiones 0.9.5 y anteriores de Mercurial, \hgcmd{bisect} no igor@398: era una orden incluída en la distribución principal: se ofrecía como igor@398: una extensión de Mercurial. Esta sección describe la orden embebida igor@398: y no la extensión anterior. jerojasro@343: \end{note} jerojasro@343: igor@398: Creamos un repostorio para probar el comando \hgcmd{bisect} de forma igor@398: aislada jerojasro@343: \interaction{bisect.init} igor@398: Simularemos de forma sencilla un proyecto con un fallo: haremos igor@398: cambios triviales en un ciclo, e indicaremos que un cambio específico igor@398: sea el ``fallo''. Este ciclo crea 35 conjuntos de cambios, cada uno igor@400: añade un único fichero al repositorio. Representaremos nuestro ``fallo'' igor@398: con un fichero que contiene el texto ``tengo un gub''. jerojasro@343: \interaction{bisect.commits} jerojasro@343: igor@398: A continuación observaremos cómo usar la orden \hgcmd{bisect}. Podemos igor@398: usar el mecanismo de ayuda embebida que trae Mercurial. jerojasro@343: \interaction{bisect.help} jerojasro@343: igor@398: La orden \hgcmd{bisect} trabaja en etapas, de la siguiente forma: jerojasro@343: \begin{enumerate} igor@398: \item Usted ejecuta una prueba binaria. jerojasro@343: \begin{itemize} igor@398: \item Si la prueba es exitosa, usted se lo indicará a \hgcmd{bisect} igor@398: ejecutando la orden \hgcmdargs{bisect}{good}. igor@398: \item Si falla, ejecutará la orden \hgcmdargs{bisect}{--bad}. jerojasro@343: \end{itemize} igor@398: \item La orden usa su información para decidir qué conjuntos de igor@398: cambios deben probarse a continuación. igor@398: \item Actualiza el directorio de trabajo a tal conjunto de cambios y igor@398: el proceso se lleva a cabo de nuevo. jerojasro@343: \end{enumerate} igor@398: El proceso termina cuando \hgcmd{bisect} identifica un único conjunto igor@398: de cambios que marca el punto donde se encontró la transición de igor@398: ``exitoso'' a ``fallido''. igor@398: igor@398: Para comenzar la búsqueda, es indispensable ejecutar la orden igor@398: \hgcmdargs{bisect}{--reset}. jerojasro@343: \interaction{bisect.search.init} jerojasro@343: igor@398: En nuestro caso, la prueba binaria es sencilla: revisamos si el igor@400: fichero en el repositorio contiene la cadena ``tengo un gub''. Si la igor@398: tiene, este conjunto de cambios contiene aquel que ``causó el fallo''. igor@398: Por convención, un conjunto de cambios que tiene la propiedad que igor@398: estamos buscando es ``malo'', mientras que el otro que no la tiene es igor@398: ``bueno''. igor@398: igor@398: En la mayoría de casos, la revisión del directorio actual (usualmente igor@398: la punta) exhibe el problema introducido por el cambio con el fallo, igor@398: por lo tanto la marcaremos como ``mala''. jerojasro@343: \interaction{bisect.search.bad-init} jerojasro@343: igor@398: Nuestra próxima tarea es nominar al conjunto de cambios que sabemos igor@398: \emph{no} tiene el fallo; la orden \hgcmd{bisect} ``acotará'' su igor@398: búsqueda entre el primer par de conjuntos de cambios buenos y malos. igor@398: En nuestro caso, sabemos que la revisión~10 no tenía el fallo. (Más igor@398: adelante diré un poco más acerca de la elección del conjunto de igor@398: cambios ``bueno''.) jerojasro@343: \interaction{bisect.search.good-init} jerojasro@343: igor@398: Note que esta orden mostró algo. jerojasro@343: \begin{itemize} igor@398: \item Nos dijo cuántos conjuntos de cambios debe considerar antes de igor@398: que pueda identifica aquel que introdujo el fallo, y cuántas pruebas igor@398: se requerirán. igor@398: \item Actualizó el directorio de trabajo al siguiente conjunto de igor@398: cambios, y nos dijo qué conjunto de cambios está evaluando. jerojasro@343: \end{itemize} jerojasro@343: igor@398: Ahora ejecutamos nuestra prueba en el directorio de trabajo. Usamos la igor@398: orden \command{grep} para ver si nuestro fichero ``malo'' está igor@398: presente en el directorio de trabajo. Si lo está, esta revisión es igor@398: mala; si no esta revisión es buena. jerojasro@343: \interaction{bisect.search.step1} jerojasro@343: igor@398: Esta prueba luce como candidata perfecta para automatizarse, por lo igor@398: tanto la convertimos en una función de interfaz de comandos. jerojasro@343: \interaction{bisect.search.mytest} igor@398: Ahora podemos ejecutar un paso entero de pruebas con un solo comando, jerojasro@343: \texttt{mytest}. jerojasro@343: \interaction{bisect.search.step2} igor@398: Unas invocaciones más de nuestra prueba, y hemos terminado. jerojasro@343: \interaction{bisect.search.rest} jerojasro@343: igor@398: Aunque teníamos unos~40 conjuntos de cambios en los cuales buscar, la igor@398: orden \hgcmd{bisect} nos permitió encontrar el conjunto de cambios que igor@398: introdujo el ``fallo'' con sólo cinco pruebas. Porque el número de igor@398: pruebas que la orden \hgcmd{bisect} ejecuta crece logarítmicamente con igor@398: la cantidad de conjuntos de cambios a buscar, la ventaja que esto igor@398: tiene frente a la búsqueda por``fuerza bruta'' crece con cada igor@398: conjunto de cambios que usted adicione. igor@398: igor@398: \subsection{Limpieza después de la búsqueda} igor@398: igor@398: Cuando haya terminado de usar la orden \hgcmd{bisect} en un igor@398: repositorio, puede usar la orden \hgcmdargs{bisect}{reset} para igor@398: deshacerse de la información que se estaba usando para lograr la igor@398: búsqueda. Lar orden no usa mucho espacio, así que no hay problema si igor@398: olvida ejecutar la orden. En todo caso, \hgcmd{bisect} no le igor@398: permitirá comenzar una nueva búsqueda sobre el repositorio hasta que igor@398: no aplique \hgcmdargs{bisect}{reset}. jerojasro@343: \interaction{bisect.search.reset} jerojasro@343: igor@401: \section{Consejos para encontrar fallos efectivamente} igor@401: igor@401: \subsection{Dar una entrada consistente} igor@401: igor@401: La orden \hgcmd{bisect} requiere que usted ofrezca un reporte correcto igor@401: del resultado de cada prueba que aplique. Si usted le dice que una igor@401: prueba falla cuando en realidad era acertada, \emph{podría} detectar igor@401: la inconsistencia. Si puede identificar una inconsistencia en sus igor@401: reportes, le dirá que un conjunto de cambios particular es a la vez igor@401: bueno y malo. Aunque puede no hacerlo; estaría tratando de reportar igor@401: un conjunto de cambios como el responsable de un fallo aunque no lo igor@401: sea. igor@401: igor@401: \subsection{Automatizar tanto como se pueda} igor@401: igor@401: Cuando comencé a usar la orden \hgcmd{bisect}, intenté ejecutar igor@401: algunas veces las pruebas a mano desde la línea de comandos. Es una igor@401: aproximación a la cual no esta acostumbrado. Después de algunos igor@401: intentos, me di cuenta que estaba cometiendo tantas equivocaciones que igor@401: tenía que comenzar de nuevo con mis búsquedas varias veces antes de igor@401: llegar a los resultados deseados. igor@401: igor@401: Mi problema inicial al dirigir a la orden \hgcmd{bisect} manualmente igor@401: ocurrieron incluso con búsquedas en repositorios pequeños; si el igor@401: problema que está buscando es más sutil, o el número de pruebas que igor@401: \hgcmd{bisect} debe aplicar, la posibilidad de errar es mucho más igor@401: alta. Una vez que comencé a automatizar mis pruebas, obtuve mejores igor@401: resultados. igor@401: igor@401: La clave para las pruebas automatizadas se puede resumir en: jerojasro@343: \begin{itemize} igor@401: \item pruebe siempre buscando el mismo síntoma y igor@401: \item ofrezca siempre datos consistentes a la orden \hgcmd{bisect}. jerojasro@343: \end{itemize} igor@401: En mi tutorial de ejemplo anterior, la orden \command{grep} busca el igor@401: síntoma, y la construcción \texttt{if} toma el resultado de esta igor@401: prueba y verifica que siempre alimentamos con los mismos datos a la igor@401: orden \hgcmd{bisect}. La función \texttt{mytest} los une de una forma igor@401: reproducible, logrando que cada prueba sea uniforme y consistente. igor@401: igor@401: \subsection{Verificar los resultados} igor@401: igor@401: Dado que la salida de la búsqueda de \hgcmd{bisect} es tan buena como igor@401: los datos ofrecidos por usted, no confíe en esto como si fuera la igor@401: verdad absoluta. Una forma sencilla de asegurarse es ejecutar igor@401: manualmente su prueba a cada uno de los siguientes conjuntos de igor@401: cambios: jerojasro@343: \begin{itemize} igor@401: \item El conjunto de cambios que se reportó como la primera versión igor@401: erronea. Su prueba debería dar un reporte de fallo. igor@401: \item El conjunto de cambios padre (cada padre, si es una fusión). igor@401: Su prueba debería reportar este(os) conjunto(s) de cambios como igor@401: bueno(s). igor@401: \item Un hijo del conjunto de cambios. Su prueba debería reportar al igor@401: conjunto de cambios hijo como malo. jerojasro@343: \end{itemize} jerojasro@343: igor@401: \subsection{Tener en cuenta la interferencia entre fallos} igor@401: igor@401: Es posible que su búsqueda de un fallo pueda viciarse por la presencia igor@401: de otro. Por ejemplo, digamos que su programa se revienta en la igor@401: revisión 100, y que funcionó correctamente en la revisión 50. Sin su igor@401: conocimiento, alguien introdujo un fallo con consecuencias grandes en igor@401: la revisión 60, y lo arregló en la revisión 80. Sus resultados igor@401: estarían distorcionados de una o muchas formas. igor@401: igor@401: Es posible que este fallo ``enmascare'' completamente al suyo, y que igor@401: podría haberse revelado antes de que su propio fallo haya tenido jerojasro@520: oportunidad de manifestarse. Si no puede saltar el otro fallo (por igor@401: ejemplo, este evita que su proyecto se arme o compile), y de esta igor@401: forma no se pueda revisar si su fallo esté presente en un conjunto igor@401: particular de cambios, la orden \hgcmd{bisect} no podrá ayudarle igor@401: directamente. En cambio, puede marcar este conjunto de cambios como igor@401: al ejecutar \hgcmdargs{bisect}{--skip}. igor@401: igor@401: Un problema distinto podría surgir si su prueba de la presencia de un igor@401: fallo no es suficientemente específica. Si usted busca ``mi programa igor@401: se revienta'', entonces tanto su fallo como el otro fallo sin relación igor@401: que terminan presentando síntomas distintos, podría terminar igor@401: confundiendo a \hgcmd{bisect}. igor@401: igor@401: Otra situación en la cual sería de mucha utilidad emplear a igor@401: \hgcmdargs{bisect}{--skip} surge cuando usted no puede probar una igor@401: revisión porque su proyecto estaba en una situación de rompimiento y igor@401: por lo tanto en un estado en el cual era imposible hacer la prueba en igor@401: esa revisión, tal vez porque alguien consignó un cambio que hacía igor@401: imposible la construcción del proyecto. igor@401: igor@401: \subsection{Acotar la búsqueda perezosamente} igor@401: igor@401: Elegir los primeros ``buenos'' y ``malos'' conjuntos de cambios que igor@401: marcarán los límites de su búsqueda en general es sencillo, pero vale igor@401: la pena discutirlo. Desde la perspectiva de \hgcmd{bisect}, el igor@401: conjunto de cambios ``más nuevo'' por convención es el ``malo'', y el igor@401: otro conjunto de cambios es el ``bueno''. igor@401: igor@401: Si no recuerda cuál podría ser el cambio ``bueno'', para informar a igor@401: \hgcmd{bisect}, podría hacer pruebas aleatorias en el peor de los igor@401: casos. Pero recuerde eliminar aquellos conjuntos de cambios que jerojasro@520: podrían no exhibir el fallo (tal vez porque la característica donde se igor@401: presenta el fallo todavía no está presente) y aquellos en los cuales jerojasro@520: otro fallo puede enmascararlo (como se discutió anteriormente). igor@401: igor@401: Incluso si termina ``muy atrás'' por miles de conjuntos de cambios o jerojasro@516: meses de historial, solamente estaŕa adicionando unas pruebas contadas igor@401: para \hgcmd{bisect}, gracias al comportamiento logarítmico. jerojasro@343: jerojasro@343: %%% Local Variables: jerojasro@343: %%% mode: latex jerojasro@343: %%% TeX-master: "00book" jerojasro@343: %%% End: