FAQ de Mercurial

¿En qué se diferencia Mercurial de CVS?

• "En mucho". Deberías leer y comprender lo básico de Mercurial antes de hacerte cargo de trabajo con Mercurial en el que tengas interés.

• Los cambios en Mercurial son atómicos.

• En Mercurial, el etiquetado es rápido y O(1).

• Mercurial facilita a todos bifurcar el repositorio central (la orden es hg clone).

• Mercurial hace que ramificar sea rápido y fácil y mantiene la fusión muy coherente (ver Publicar clones en Mercurial).

• Con Mercurial tendrás un clon completo, totalmente armado y operacional del repositorio entero de Mozilla en tu disco duro. Puedes trabajar localmente y aplicarle cambios sin afectar a nadie más. Para promocionar los cambios al repositorio principal, usa hg push.

• Las colas de Mercurial (inglés) pueden ayudarte a hacer malabarismos con los parches. Es como Quilt (inglés). La idea tras Quilt es ésta:

  Los scripts permiten manejar una serie de parches manteniendo un registro de los cambios que hace cada parche. Los parches pueden ser aplicados, des-aplicados, refrescados, etc.

  El concepto filosófico clave es que tu salida principal son parches. No archivos ".c", no archivos ".h", sino parches. Así que los parches son el objeto de primera categoría aquí.

• Cuando CVS encuentra conflictos al fusionar, pone marcadores de conflicto en tu archivo. Cuando Mercurial encuentra conflictos al fusionar, lanza un programa de fusión (inglés). Esto es como un dolor de cervicales.

• En muchos casos en los que CVS actúa por archivo o por directorio, Mercurial actúa por repositorio. Por ejemplo, un solo conjunto de cambios de Mercurial puede contener archivos a muchos archivos a lo largo del árbol.

• Esperamos que Mercurial nos permita volver a pensar la manera en la que trabajamos. Los equipos e individuos deberían poder ramificar y fusionar mucho más fácilmente - sin abrir incidencias para el equipo técnico. La gente de fuera de la comunidad que sean desarrolladores experimentados deberían ser capaces de hacer cosas sorprendentes con esto. Las compañías que mantienen bifurcaciones de Mozilla deberían poder trabajar mejor, también. Todo está por ver, no obstante.

¿Cómo instalo Mercurial?

Si usas apt-get, emerge, port, o yum para instalar software, limítate a hacer lo normal. Si obtienes como resultado una versión antigua (pre-1.0 -- compruébalo con hg version), puedes actualizarlo usando easy_install como sigue (usando apt-get en este ejemplo):

sudo apt-get install python-setuptools python-dev build-essential
sudo easy_install -U mercurial

En caso contrario, los paquetes binarios de Mercurial (inglés) están hechos para ti. Revisa también wikimo:Mercurial on Windows (inglés).

Programa de fusión

Tras instalar, elige un programa de fusión (inglés). En serio. Hazlo ahora. Si no lo haces, Mercurial elegirá uno por ti y te lo plantará en tus narices cuando menos lo esperes.

Algo razonable para hacer es configurar ui.merge=internal:merge en el archivo de configuración de Mercurial (ver más abajo), lo que hace que Mercurial intente fusionar los cambios y añadir los marcadores de conflicto (al estilo CVS) a los archivos que no pueda fusionar.

Puedes ver la lista de conflictos de fusión buscando "merging ... failed!" en la salida de update.

Configuración

Deberías configurar Mercurial antes de descargar el código. Tu archivo de configuración de Mercurial (~/.hgrc) debería tener al menos la siguiente configuración:

[ui]
username = Tu Nombre Real <[email protected]>
merge = tu-programa-de-fusión

[diff]
git = 1

[defaults]
diff=-p -U 8

En Windows, estos valores se pueden añadir a C:\Archivos de Programa\Mercurial\Mercurial.ini. En los sistemas tipo Unix, debería estar en tu archivo $HOME/.hgrc.

Puedes configurar el editor a usar para los mensajes de fusión usando la opción editor en la sección [ui] o estableciendo la variable de entorno EDITOR.

¿Cómo gestiona Mercurial los finales de línea?

La versión Windows de Mercurial no convierte automáticamente los finales de línea entre los estilos de Windows y Unix. Todos nuestros repositorios usan finales de línea Unix. Necesitamos una manera de solucionar esto en Windows, pero de momento no sabemos cómo.

(¿Qué tal si insertamos un control previo al commit que rechace los cambios que contienen CR con un mensaje de error informativo apropiado? Posiblemente querremos hacer excepciones para ciertos tipos de archivo (como poco, archivos binarios, por supuesto), pero podemos ajustar el control según consideremos necesario. Mercurial 1.0 añade un control estándar para esto en la extensión win32text que podríamos usar/adaptar --jwatt).

¿Cómo puedo...?

¿Cómo puedo descargar Mozilla?

El desarrollo principal (trunk) de Mozilla 2 está ubicado en https://hg.mozilla.org/mozilla-central/ . Revisa Código fuente de Mozilla (Mercurial) para instrucciones sobre cómo descargar el código fuente de Mozilla 2 de Mercurial.

¿Cómo puedo editar y actualizar archivos?

Puedes editar archivos a voluntad en el directorio de trabajo, exactamente igual que con CVS.

La orden común para actualizar un árbol es:

hg pull -u

No es posible actualizar sólo un directorio; tienes que actualizar el árbol entero.

¿Cómo detecto cambios y aplico parches en archivos?

• hg diff muestra las diferencias del árbol completo por defecto. Usa hg diff <dir> para ver las diferencias sólo del directorio dado. No olvides hacer hg add de cualquier archivo nuevo que estés añadiendo antes de generar el parche.

• Si estás cambiando archivos binarios o renombrando archivos puedes querer usar parches al estilo git con hg diff -g para conservar ese tipo de información en el parche.

• Al aplicar un parche generado por Mercurial, usa patch -p1, no patch -p0 (esto se debe a un fallo de la salida del diff de Mercurial — se refiere a los directorios ficticios "a" y "b". No preguntes).

• Si tienes un parche de estilo git con renombrados o cambios binarios puedes usar hg import --no-commit para aplicar el parche a tu árbol o usar hg qimport para importar el parche en mq.

Las opciones de diff preferidas son hg diff -p -U 8 que incluye 8 líneas de contexto y muestra la función relevante del bloque. Puedes convertir estas opciones en predeterminadas en el archivo de configuración de Mercurial.

¿Cómo aplico cambios?

Configuración necesaria

Antes de aplicar ningún cambio, añade estas líneas a tu archivo ~/.hgrc:

[ui]
username = Tu nombre <[email protected]>

Para subir los cambios a mozilla-central y otros repositorios alojados en mozilla tienes que tener acceso de escritura (committer), y debes editar el archivo (tu-raíz-hg-local)/.hg/hgrc (observa que éste NO es tu ~/.hgrc) para añadir esta línea:

[paths]
default = https://hg.mozilla.org/mozilla-central/
default-push = ssh://hg.mozilla.org/mozilla-central/

También tienes que decirle a SSH qué nombre de usuario utilizar al conectar con hg.mozilla.org. Éste debería ser el nombre de usuario asociado a tu cuenta LDAP en Mozilla. Puedes hacer esto bien complicando ligeramente la ruta de aplicación por defecto, o default-push, (convirtiéndola en [email protected]@hg.mozilla.org) o bien añadiendo líneas a tu ~/.ssh/config:

Host hg.mozilla.org
User [email protected]

Comprueba lo que vas a aplicar

A continuación, para comprobar si realmente vas a aplicar los cambios que quieres aplicar (especialmente importante al hacer fusiones y otros cambios complejos):

hg status
hg diff

status muestra los archivos que han cambiado en tu directorio de trabajo comparado con lo que hay en tu repositorio (las revisiones padre, que puedes ver usando hg parents). hg diff muestra los cambios reales en esos archivos, como diffs unificados. Puedes añadir la opción -U8 para ver más contexto.

Aplica al repositorio local

Como siguiente paso, aplicarás tus cambios a tu repositorio local:

hg commit

Esto aplica los cambios informado por hg status. Puedes limitar la aplicación a archivos o directorios específicos usando hg commit nombres_de_archivo. Puedes aplicar los cambios en nombre de alguna otra persona usando hg commit -u "Algún otro <[email protected]>". Revisa hg help commit para obtener más detalles.

Comprueba lo que vas a subir

Antes de que subas (push), probablemente quieras comprobar qué conjuntos de cambios se subirán. Puedes hacer esto usando la orden outgoing:

hg outgoing

Esto te dará una lista de conjuntos de cambio que se subirán al repositorio remoto predeterminado. Añade un argumento de repositorio para ver los cambios salientes (outgoing) en ese otro repositorio.

Subir al repositorio central

Para subir esos cambios hasta el repositorio central:

hg push

Obtendrás un mensaje de error sin importancia cada vez que subas:

remote: Could not chdir to home directory : No such file or directory

Ignóralo sin más.

¿Cómo actúo ante "abort: push creates new remote heads!"?

Hagas lo que hagas, no hagas 'push -f' como sugiere el mensaje (probablemente falle de todas formas, pero ni lo intentes).

Alguien ha subido nuevos cambios desde tu última descarga. A continuación has aplicado tu parche localmente y estás intentando subir ese cambio al repositorio principal, el cual tiene un último cambio distinto de aquél desde el que comenzaste.

Hay dos cosas que puedes hacer. La más sencilla es fusionar tus cambios: ejecuta hg pull, luego hg merge. Resuelve cualquier conflicto que surja, y luego aplica la fusión resultante: hg commit -m "Merge commit for bug 123456". Luego haz hg push normalmente. Esto tiene el desafortunado efecto colateral de dejar un feo cambio por fusión en el historial de revisiones y, lo que es peor, hará tu parche más difícil de retrotraer si tuviste que resolver conflictos.

Sin embargo, es lo más sencillo, y es muy seguro. Hay otra manera de afrontar el problema, pero es considerablemente más arcana -- hay un arreglo/reemplazo en progreso.

Lo más avanzado que puedes hacer es importar el cambio en mq, extraerlo de la cola, actualizar, y volver a aplicarlo de nuevo antes de subirlo:

% hg log -l 5
415[tip]   d1accb6ee840   2008-04-30 09:57 -0700   vladimir
  b=430873; fast path drawImage with a canvas as source
414   3a3ecbb4873e   2008-04-30 09:55 -0700   vladimir
  cvs sync
% hg qimport -r 415
% hg qtop
415.diff
% hg qpop
Patch queue now empty
% hg pull -u
... varios mensajes de descarga/actualización ...
% hg qpush
applying 415.diff
Now at: 415.diff
Corrige los conflictos según sea necesario; si has corregido alguno, ejecuta hg qrefresh primero
% hg qrm -r 415.diff
qrm -r significa "elimina este parche de mi cola, pero conserva la revisión"
% hg log -l 5
verifica que el registro tiene buena pinta, con tu cambio arriba del todo
% hg push

Si ya has usado mq para gestionar tus parches, asegúrate de que descargas/actualizas justo antes de aplicar y subir tu parche. Si tienes problemas con lo anterior, no hay nada malo en hacer una fusión simple como se ha descrito anteriormente.

¿Cómo veo lo que harán estas órdenes antes de ejecutarlas?

Si quieres ver lo que hará hg commit, ejecuta hg diff primero.

Si quieres ver lo que subirá hg push, ejecuta hg outgoing primero.

Si quieres ver lo que descargará hg pull, ejecuta hg incoming primero.

Estos pares de órdenes aceptan todos argumentos parecidos, y hay buenos motivos para ello. Es buena idea usarlos siempre mientras estás aprendiendo a usar Mercurial. E incluso una vez ya eres un experto, ejecutar siempre outgoing antes de push es una buena idea.

¿Cómo puedo personalizar el formato de los parches que crea Mercurial?

Edita tu archivo ~/.hgrc y añade unas líneas como éstas:

[defaults]
diff=-U 8 -p
qdiff=-U 8

[diff]
git=true

La sección [defaults] afecta a la salida predeterminada de las órdenes hg diff y hg qdiff. Las opciones se comportan igual que si estuvieran en la línea de órdenes. Prueba hg help diff para más información.

La sección [diff] afecta a todos los parches generados por Mercurial, incluso aquellos generados para el uso interno de Mercurial. Necesitas llevar mucho más cuidado con esto, pero se recomienda git=true. Sin él, Mercurial no puede comparar (diff) archivos binarios y no lleva un registro del bit de modo de ejecución.

Revertir cambios

Revertir todo el árbol a una revisión buena conocida

Es fácil, tan fácil como usar un mazo. Pero normalmente es matar moscas a cañonazos.

$ hg pull -u
$ hg revert --all -r a0193d83c208       # usa aquí la id de tu revisión buena conocida
$ hg commit                             # Sé educado, incluye la id de revisión en tu mensaje acompañando al cambio
$ hg push

Hay una alternativa más precisa:

Revertir un único conjunto de cambios

Supón que el conjunto de cambios f8f4360bf155 ha estropeado algo.

$ hg pull -u
$ hg backout f8f4360bf155               # usa la id de revisión del cambio erróneo aquí

Esto crea y aplica un nuevo conjunto de cambios que revierte todos los cambios en la revisión.

Si ves este mensaje:

the backout changeset is a new head - do not forget to merge

Esto significa que necesitas fusionar, porque tu historial ahora tiene este aspecto:

   TÚ ---> o  9123b7791b52 - Kaitlin Jones <[email protected]> - Backed out changeset f8f4360bf155
           | 
TRUNK ---> | o  4e5bfb83643f - Simon Montagu <[email protected]> - imported patch 435856
           | | 
           | o  6ee23de41631 - Phil Ringnalda <[email protected]> - Bug 438526 - Opening links w
           | | 
           | o  22baa05d0e8a - Robert O'Callahan <[email protected]> - Remove DOM testcase from exclusi
           | | 
           | o  c1aec2094f7e - Robert Longson <[email protected]> - Bug 437448. New-style nsSVGString
           | | 
           | o  306726089e22 - Robert Longson <[email protected]> - Bug 437448. New-style nsSVGString
           | | 
           | o  ba9b9a7c52a5 - Robert Longson <[email protected]> - Bug 437448. New-style nsSVGString
           |/
           o  f8f4360bf155 - Robert O'Callahan <[email protected]> - Bug 421436. Remove hack that gives
           |
           ⋮ (the past)

Tu conjunto de cambios de reversión está basado en una revisión antigua. No tiene los cambios más recientes.

Maneja esto como cualquier otra fusión. Si nunca has hecho antes una fusión, consigue ayuda (podría ser trivial o convertirse en un dolor de cabeza mayúsculo. Hay más información sobre cómo fusionar en otras partes de esta FAQ).

Ayuda

¡Ayuda, no puedo subir los cambios!

Si estás intentando subir los cambios y no puedes, prueba esto primero:

$ ssh hg.mozilla.org

Si ves un resultado como:

Permission denied (publickey,gssapi-with-mic).

puede deberse a las siguientes razones:

• necesitas configurar tu nombre de usuario correctamente
• no tienes la clave privada correcta en ~/.ssh
• no tienes una cuenta en hg.mozilla.org (si deberías tenerla, cursa un bug en mozilla.org:Server Operations).

Si ves un resultado como:

You are not allowed to use this system, go away!

entonces necesitas cursar un bug en mozilla.org:Server Operations.

Debes esperar que la orden SSH te desconecte inmediatamente, ya que no se supone que debas tener acceso a ninguna shell. Puede que te devuelva como resultado:

Could not chdir to home directory : No such file or directory

lo que no tiene consecuencias (aunque algunas personas lo verán y otras no).

Si ves un resultado como:

ssl required

entonces necesitas configurar el valor de tu default-push correctamente.

Cosas que han cambiado

• Bonsai ha sido reemplazado por el visor web de Hg. Le faltan algunas características de bonsai que estarían bien, incluyendo marcado, enlaces por número de línea y gráficas. Hay algunas diferencias de terminología:

bonsai blame == hg annotate
bonsai log == hg revisions
también puedes visualizar el repositorio usando el enlace "manifest".

• MXR para mozilla-central está ya disponible.

• No hay integración de Bugzilla para Mercurial.

• Características deseadas de Mercurial.