hgbook

annotate es/concepts.tex @ 417:7e838acf7350

find changesets by author, revision, files, or words in the commit message
translated more paragraphs of collab to spanish
author Igor TAmara <igor@tamarapatino.org>
date Thu Nov 13 23:09:45 2008 -0500 (2008-11-13)
parents 0eda2936ef77
children bc2136732cd6
rev   line source
jerojasro@393 1 \chapter{Tras bambalinas}
jerojasro@343 2 \label{chap:concepts}
jerojasro@343 3
jerojasro@393 4 A diferencia de varios sistemas de control de revisiones, los
jerojasro@393 5 conceptos en los que se fundamenta Mercurial son lo suficientemente
jerojasro@393 6 simples como para entender fácilmente cómo funciona el software.
jerojasro@393 7 Saber esto no es necesario, pero considero útil tener un ``modelo
jerojasro@393 8 mental'' de qué es lo que sucede.
jerojasro@393 9
jerojasro@393 10 Comprender esto me da la confianza de que Mercurial ha sido
jerojasro@393 11 cuidadosamente diseñado para ser tanto \emph{seguro} como
jerojasro@393 12 \emph{eficiente}. Y tal vez con la misma importancia, si es fácil
jerojasro@393 13 para mí hacerme a una idea adecuada de qué está haciendo el software
jerojasro@393 14 cuando llevo a cabo una tarea relacionada con control de revisiones,
jerojasro@393 15 es menos probable que me sosprenda su comportamiento.
jerojasro@393 16
jerojasro@393 17 En este capítulo, cubriremos inicialmente los conceptos centrales
jerojasro@393 18 del diseño de Mercurial, y luego discutiremos algunos detalles
jerojasro@393 19 interesantes de su implementación.
jerojasro@393 20
jerojasro@393 21 \section{Registro del historial de Mercurial}
jerojasro@393 22
jerojasro@393 23 \subsection{Seguir el historial de un único fichero}
jerojasro@393 24
jerojasro@393 25 Cuando Mercurial sigue las modificaciones a un fichero, guarda el
jerojasro@393 26 historial de dicho fichero en un objeto de metadatos llamado
jerojasro@395 27 \emph{filelog}\ndt{Fichero de registro}. Cada entrada en el fichero
jerojasro@395 28 de registro contiene suficiente información para reconstruir una
jerojasro@395 29 revisión del fichero que se está siguiendo. Los ficheros de registro
jerojasro@395 30 son almacenados como ficheros el el directorio
jerojasro@395 31 \sdirname{.hg/store/data}. Un fichero de registro contiene dos tipos
jerojasro@395 32 de información: datos de revisiones, y un índice para ayudar a
jerojasro@395 33 Mercurial a buscar revisiones eficientemente.
jerojasro@395 34
jerojasro@395 35 El fichero de registro de un fichero grande, o con un historial muy
jerojasro@395 36 largo, es guardado como ficheros separados para datos (sufijo
jerojasro@395 37 ``\texttt{.d}'') y para el índice (sufijo ``\texttt{.i}''). Para
jerojasro@395 38 ficheros pequeños con un historial pequeño, los datos de revisiones y
jerojasro@395 39 el índice son combinados en un único fichero ``\texttt{.i}''. La
jerojasro@395 40 correspondencia entre un fichero en el directorio de trabajo y el
jerojasro@395 41 fichero de registro que hace seguimiento a su historial en el
jerojasro@395 42 repositorio se ilustra en la figura~\ref{fig:concepts:filelog}.
jerojasro@343 43
jerojasro@343 44 \begin{figure}[ht]
jerojasro@343 45 \centering
jerojasro@343 46 \grafix{filelog}
jerojasro@396 47 \caption{Relación entre ficheros en el directorio de trabajo y
jerojasro@396 48 ficheros de registro en el repositorio}
jerojasro@343 49 \label{fig:concepts:filelog}
jerojasro@343 50 \end{figure}
jerojasro@343 51
jerojasro@396 52 \subsection{Administración de ficheros monitoreados}
jerojasro@396 53
jerojasro@396 54 Mercurial usa una estructura llamada \emph{manifiesto} para
jerojasro@396 55 % TODO collect together => centralizar
jerojasro@396 56 centralizar la información que maneja acerca de los ficheros que
jerojasro@396 57 monitorea. Cada entrada en el manifiesto contiene información acerca
jerojasro@396 58 de los ficheros involucrados en un único conjunto de cambios. Una
jerojasro@396 59 entrada registra qué ficheros están presentes en el conjunto de
jerojasro@396 60 cambios, la revisión de cada fichero, y otros cuantos metadatos del
jerojasro@396 61 mismo.
jerojasro@396 62
jerojasro@396 63 \subsection{Registro de información del conjunto de cambios}
jerojasro@396 64
jerojasro@396 65 La \emph{bitácora de cambios} contiene información acerca de cada
jerojasro@396 66 conjunto de cambios. Cada revisión indica quién consignó un cambio, el
jerojasro@396 67 comentario para el conjunto de cambios, otros datos relacionados con
jerojasro@396 68 el conjunto de cambios, y la revisión del manifiesto a usar.
jerojasro@396 69
jerojasro@396 70 \subsection{Relaciones entre revisiones}
jerojasro@396 71
jerojasro@396 72 Dentro de una bitácora de cambios, un manifiesto, o un fichero de
jerojasro@396 73 registro, cada revisión conserva un apuntador a su padre inmediato
jerojasro@396 74 (o sus dos padres, si es la revisión de una fusión). Como menciońe
jerojasro@396 75 anteriormente, también hay relaciones entre revisiones \emph{a través}
jerojasro@396 76 de estas estructuras, y tienen naturaleza jerárquica.
jerojasro@396 77
jerojasro@396 78 Por cada conjunto de cambios en un repositorio, hay exactamente una
jerojasro@396 79 revisión almacenada en la bitácora de cambios. Cada revisión de la
jerojasro@396 80 bitácora de cambios contiene un apuntador a una única revisión del
jerojasro@396 81 manifiesto. Una revisión del manifiesto almacena un apuntador a una
jerojasro@396 82 única revisión de cada fichero de registro al que se le hacía
jerojasro@396 83 seguimiento cuando fue creado el conjunto de cambios. Estas relaciones
jerojasro@396 84 se ilustran en la figura~\ref{fig:concepts:metadata}.
jerojasro@343 85
jerojasro@343 86 \begin{figure}[ht]
jerojasro@343 87 \centering
jerojasro@343 88 \grafix{metadata}
jerojasro@396 89 \caption{Relaciones entre metadatos}
jerojasro@343 90 \label{fig:concepts:metadata}
jerojasro@343 91 \end{figure}
jerojasro@343 92
jerojasro@406 93 Como lo muestra la figura, \emph{no} hay una relación ``uno a uno''
jerojasro@406 94 entre las revisiones en el conjunto de cambios, el manifiesto, o el
jerojasro@406 95 fichero de registro. Si el manifiesto no ha sido modificado de un
jerojasro@406 96 conjunto de cambios a otro, las entradas en la bitácora de cambios
jerojasro@406 97 para esos conjuntos de cambios apuntarán a la misma revisión del
jerojasro@406 98 manifiesto. Si un fichero monitoreado por Mercurial no sufre ningún
jerojasro@406 99 cambio de un conjunto de cambios a otro, la entrada para dicho fichero
jerojasro@406 100 en las dos revisiones del manifiesto apuntará a la misma revisión de
jerojasro@406 101 su fichero de registro.
jerojasro@406 102
jerojasro@406 103 \section{Almacenamiento seguro y eficiente}
jerojasro@406 104
jerojasro@406 105 La base común de las bitácoras de cambios, los manifiestos, y los
jerojasro@406 106 ficheros de registros es provista por una única estructura llamada el
jerojasro@406 107 \emph{revlog}\ndt{Contracción de \emph{revision log}, registro de
jerojasro@406 108 revisión.}.
jerojasro@406 109
jerojasro@406 110 \subsection{Almacenamiento eficiente}
jerojasro@406 111
jerojasro@406 112 El revlog provee almacenamiento eficiente de revisiones por medio del
jerojasro@406 113 mecanismo de \emph{deltas}\ndt{Diferencias.}. En vez de almacenar una
jerojasro@406 114 copia completa del fichero por cada revisión, almacena los cambios
jerojasro@406 115 necesarios para transformar una revisión anterior en la nueva
jerojasro@406 116 revisión. Para muchos tipos de fichero, estos deltas son típicamente
jerojasro@406 117 de una fracción porcentual del tamaño de una copia completa del
jerojasro@406 118 fichero.
jerojasro@406 119
jerojasro@406 120 Algunos sistemas de control de revisiones obsoletos sólo pueden
jerojasro@406 121 manipular deltas de ficheros de texto plano. Ellos o bien almacenan
jerojasro@406 122 los ficheros binarios como instantáneas completas, o codificados en
jerojasro@406 123 alguna representación de texto plano adecuada, y ambas alternativas
jerojasro@406 124 son enfoques que desperdician bastantes recursos. Mercurial puede
jerojasro@406 125 manejar deltas de ficheros con contenido binario arbitrario; no
jerojasro@406 126 necesita tratar el texto plano como un caso especial.
jerojasro@343 127
jerojasro@410 128 \subsection{Operación segura}
jerojasro@343 129 \label{sec:concepts:txn}
jerojasro@343 130
jerojasro@410 131 Mercurial sólo \emph{añade} datos al final de los ficheros de revlog. Nunca
jerojasro@410 132 modifica ninguna sección de un fichero una vez ha sido escrita. Esto es más
jerojasro@410 133 robusto y eficiente que otros esquemas que requieren modificar o reescribir
jerojasro@410 134 datos.
jerojasro@410 135
jerojasro@410 136 Adicionalmente, Mercurial trata cada escritura como parte de una
jerojasro@410 137 \emph{transacción}, que puede cubrir varios ficheros. Una transacción es
jerojasro@410 138 \emph{atómica}: o bien la transacción tiene éxito y entonces todos sus efectos
jerojasro@410 139 son visibles para todos los lectores, o la operación completa es cancelada.
jerojasro@410 140 % TODO atomicidad no existe de acuerdo a DRAE, reemplazar
jerojasro@410 141 Esta garantía de atomicidad implica que, si usted está ejecutando dos copias de
jerojasro@410 142 Mercurial, donde una de ellas está leyendo datos y la otra los está escribiendo,
jerojasro@410 143 el lector nunca verá un resultado escrito parcialmente que podría confundirlo.
jerojasro@410 144
jerojasro@410 145 El hecho de que Mercurial sólo hace adiciones a los ficheros hace más fácil
jerojasro@410 146 proveer esta garantía transaccional. A medida que sea más fácil hacer
jerojasro@410 147 operaciones como ésta, más confianza tendrá usted en que sean hechas
jerojasro@410 148 correctamente.
jerojasro@410 149
jerojasro@410 150 \subsection{Recuperación rápida de datos}
jerojasro@410 151
jerojasro@410 152 Mercurial evita ingeniosamente un problema común a todos los sistemas de control
jerojasro@410 153 de revisiones anteriores> el problema de la
jerojasro@410 154 \emph{recuperación\ndt{\emph{Retrieval}. Recuperación en el sentido de traer los
jerojasro@410 155 datos, o reconstruirlos a partir de otros datos, pero no debido a una falla o
jerojasro@410 156 calamidad, sino a la operación normal del sistema.} ineficiente de datos}.
jerojasro@410 157 Muchos sistemas de control de revisiones almacenan los contenidos de una
jerojasro@410 158 revisión como una serie incremental de modificaciones a una ``instantánea''.
jerojasro@410 159 Para reconstruir una versión cualquiera, primero usted debe leer la instantánea,
jerojasro@410 160 y luego cada una de las revisiones entre la instantánea y su versión objetivo.
jerojasro@410 161 Entre más largo sea el historial de un fichero, más revisiones deben ser leídas,
jerojasro@410 162 y por tanto toma más tiempo reconstruir una versión particular.
jerojasro@343 163
jerojasro@343 164 \begin{figure}[ht]
jerojasro@343 165 \centering
jerojasro@343 166 \grafix{snapshot}
jerojasro@410 167 \caption{Instantánea de un revlog, con deltas incrementales}
jerojasro@343 168 \label{fig:concepts:snapshot}
jerojasro@343 169 \end{figure}
jerojasro@343 170
jerojasro@410 171 La innovación que aplica Mercurial a este problema es simple pero efectiva.
jerojasro@410 172 Una vez la cantidad de información de deltas acumulada desde la última
jerojasro@410 173 instantánea excede un umbral fijado de antemano, se almacena una nueva
jerojasro@410 174 instantánea (comprimida, por supuesto), en lugar de otro delta. Esto hace
jerojasro@410 175 posible reconstruir \emph{cualquier} versión de un fichero rápidamente. Este
jerojasro@410 176 enfoque funciona tan bien que desde entonces ha sido copiado por otros sistemas
jerojasro@410 177 de control de revisiones.
jerojasro@410 178
jerojasro@410 179 La figura~\ref{fig:concepts:snapshot} ilustra la idea. En una entrada en el
jerojasro@410 180 fichero índice de un revlog, Mercurial almacena el rango de entradas (deltas)
jerojasro@410 181 del fichero de datos que se deben leer para reconstruir una revisión en
jerojasro@410 182 particular.
jerojasro@410 183
jerojasro@410 184 \subsubsection{Nota al margen: la influencia de la compresión de vídeo}
jerojasro@410 185
jerojasro@410 186 Si le es familiar la compresión de vídeo, o ha mirado alguna vez una emisión de
jerojasro@410 187 TV a través de cable digital o un servicio de satélite, puede que sepa que la
jerojasro@410 188 mayor parte de los esquemas de compresión de vídeo almacenan cada cuadro del
jerojasro@410 189 mismo como un delta contra el cuadro predecesor. Adicionalmente, estos esquemas
jerojasro@411 190 usan técnicas de compresión ``con pérdida'' para aumentar la tasa de
jerojasro@410 191 compresión, por lo que los errores visuales se acumulan a lo largo de una
jerojasro@410 192 cantidad de deltas inter-cuadros.
jerojasro@343 193
jerojasro@415 194 Ya que existe la posibilidad de que un flujo de vídeo se ``pierda''
jerojasro@415 195 ocasionalmente debido a fallas en la señal, y para limitar la acumulación de
jerojasro@415 196 errores introducida por la compresión con pérdidas, los codificadores de vídeo
jerojasro@415 197 insertan periódicamente un cuadro completo (también llamado ``cuadro clave'') en
jerojasro@415 198 el flujo de vídeo; el siguiente delta es generado con respecto a dicho cuadro.
jerojasro@415 199 Esto quiere decir que si la señal de vídeo se interrumpe, se reanudará una vez
jerojasro@415 200 se reciba el siguiente cuadro clave. Además, la acumulación de errores de
jerojasro@415 201 codificación se reinicia con cada cuadro clave.
jerojasro@415 202
jerojasro@415 203 \subsection{Identificación e integridad fuerte}
jerojasro@415 204
jerojasro@416 205 Además de la información de deltas e instantáneas, una entrada en un
jerojasro@415 206 % TODO de pronto aclarar qué diablos es un hash?
jerojasro@416 207 revlog contiene un hash criptográfico de los datos que representa.
jerojasro@416 208 Esto hace difícil falsificar el contenido de una revisión, y hace
jerojasro@416 209 fácil detectar una corrupción accidental.
jerojasro@416 210
jerojasro@416 211 Los hashes proveen más que una simple revisión de corrupción: son
jerojasro@416 212 usados como los identificadores para las revisiones.
jerojasro@416 213 % TODO no entendí completamente la frase a continuación
jerojasro@416 214 Los hashes de
jerojasro@416 215 identificación de conjuntos de cambios que usted ve como usuario final
jerojasro@416 216 son de las revisiones de la bitácora de cambios. Aunque los ficheros
jerojasro@416 217 de registro y el manifiesto también usan hashes, Mercurial sólo los
jerojasro@416 218 usa tras bambalinas.
jerojasro@416 219
jerojasro@416 220 Mercurial verifica que los hashes sean correctos cuando recupera
jerojasro@416 221 revisiones de ficheros y cuando jala cambios desde otro repositorio.
jerojasro@416 222 Si se encuentra un problema de integridad, Mercurial se quejará y
jerojasro@416 223 detendrá cualquier operación que esté haciendo.
jerojasro@416 224
jerojasro@416 225 Además del efecto que tiene en la eficiencia en la recuperación, el
jerojasro@416 226 uso periódico de instantáneas de Mercurial lo hace más robusto frente
jerojasro@416 227 a la corrupción parcial de datos. Si un fichero de registro se
jerojasro@416 228 corrompe parcialmente debido a un error de hardware o del sistema, a
jerojasro@416 229 menudo es posible reconstruir algunas o la mayoría de las revisiones a
jerojasro@416 230 partir de las secciones no corrompidas del fichero de registro, tanto
jerojasro@416 231 antes como después de la sección corrompida. Esto no sería posible con
jerojasro@416 232 un sistema de almacenamiento basado únicamente en deltas.
jerojasro@343 233
jerojasro@343 234 \section{Revision history, branching,
jerojasro@343 235 and merging}
jerojasro@343 236
jerojasro@343 237 Every entry in a Mercurial revlog knows the identity of its immediate
jerojasro@343 238 ancestor revision, usually referred to as its \emph{parent}. In fact,
jerojasro@343 239 a revision contains room for not one parent, but two. Mercurial uses
jerojasro@343 240 a special hash, called the ``null ID'', to represent the idea ``there
jerojasro@343 241 is no parent here''. This hash is simply a string of zeroes.
jerojasro@343 242
jerojasro@343 243 In figure~\ref{fig:concepts:revlog}, you can see an example of the
jerojasro@343 244 conceptual structure of a revlog. Filelogs, manifests, and changelogs
jerojasro@343 245 all have this same structure; they differ only in the kind of data
jerojasro@343 246 stored in each delta or snapshot.
jerojasro@343 247
jerojasro@343 248 The first revision in a revlog (at the bottom of the image) has the
jerojasro@343 249 null ID in both of its parent slots. For a ``normal'' revision, its
jerojasro@343 250 first parent slot contains the ID of its parent revision, and its
jerojasro@343 251 second contains the null ID, indicating that the revision has only one
jerojasro@343 252 real parent. Any two revisions that have the same parent ID are
jerojasro@343 253 branches. A revision that represents a merge between branches has two
jerojasro@343 254 normal revision IDs in its parent slots.
jerojasro@343 255
jerojasro@343 256 \begin{figure}[ht]
jerojasro@343 257 \centering
jerojasro@343 258 \grafix{revlog}
jerojasro@343 259 \caption{}
jerojasro@343 260 \label{fig:concepts:revlog}
jerojasro@343 261 \end{figure}
jerojasro@343 262
jerojasro@343 263 \section{The working directory}
jerojasro@343 264
jerojasro@343 265 In the working directory, Mercurial stores a snapshot of the files
jerojasro@343 266 from the repository as of a particular changeset.
jerojasro@343 267
jerojasro@343 268 The working directory ``knows'' which changeset it contains. When you
jerojasro@343 269 update the working directory to contain a particular changeset,
jerojasro@343 270 Mercurial looks up the appropriate revision of the manifest to find
jerojasro@343 271 out which files it was tracking at the time that changeset was
jerojasro@343 272 committed, and which revision of each file was then current. It then
jerojasro@343 273 recreates a copy of each of those files, with the same contents it had
jerojasro@343 274 when the changeset was committed.
jerojasro@343 275
jerojasro@343 276 The \emph{dirstate} contains Mercurial's knowledge of the working
jerojasro@343 277 directory. This details which changeset the working directory is
jerojasro@343 278 updated to, and all of the files that Mercurial is tracking in the
jerojasro@343 279 working directory.
jerojasro@343 280
jerojasro@343 281 Just as a revision of a revlog has room for two parents, so that it
jerojasro@343 282 can represent either a normal revision (with one parent) or a merge of
jerojasro@343 283 two earlier revisions, the dirstate has slots for two parents. When
jerojasro@343 284 you use the \hgcmd{update} command, the changeset that you update to
jerojasro@343 285 is stored in the ``first parent'' slot, and the null ID in the second.
jerojasro@343 286 When you \hgcmd{merge} with another changeset, the first parent
jerojasro@343 287 remains unchanged, and the second parent is filled in with the
jerojasro@343 288 changeset you're merging with. The \hgcmd{parents} command tells you
jerojasro@343 289 what the parents of the dirstate are.
jerojasro@343 290
jerojasro@343 291 \subsection{What happens when you commit}
jerojasro@343 292
jerojasro@343 293 The dirstate stores parent information for more than just book-keeping
jerojasro@343 294 purposes. Mercurial uses the parents of the dirstate as \emph{the
jerojasro@343 295 parents of a new changeset} when you perform a commit.
jerojasro@343 296
jerojasro@343 297 \begin{figure}[ht]
jerojasro@343 298 \centering
jerojasro@343 299 \grafix{wdir}
jerojasro@343 300 \caption{The working directory can have two parents}
jerojasro@343 301 \label{fig:concepts:wdir}
jerojasro@343 302 \end{figure}
jerojasro@343 303
jerojasro@343 304 Figure~\ref{fig:concepts:wdir} shows the normal state of the working
jerojasro@343 305 directory, where it has a single changeset as parent. That changeset
jerojasro@343 306 is the \emph{tip}, the newest changeset in the repository that has no
jerojasro@343 307 children.
jerojasro@343 308
jerojasro@343 309 \begin{figure}[ht]
jerojasro@343 310 \centering
jerojasro@343 311 \grafix{wdir-after-commit}
jerojasro@343 312 \caption{The working directory gains new parents after a commit}
jerojasro@343 313 \label{fig:concepts:wdir-after-commit}
jerojasro@343 314 \end{figure}
jerojasro@343 315
jerojasro@343 316 It's useful to think of the working directory as ``the changeset I'm
jerojasro@343 317 about to commit''. Any files that you tell Mercurial that you've
jerojasro@343 318 added, removed, renamed, or copied will be reflected in that
jerojasro@343 319 changeset, as will modifications to any files that Mercurial is
jerojasro@343 320 already tracking; the new changeset will have the parents of the
jerojasro@343 321 working directory as its parents.
jerojasro@343 322
jerojasro@343 323 After a commit, Mercurial will update the parents of the working
jerojasro@343 324 directory, so that the first parent is the ID of the new changeset,
jerojasro@343 325 and the second is the null ID. This is shown in
jerojasro@343 326 figure~\ref{fig:concepts:wdir-after-commit}. Mercurial doesn't touch
jerojasro@343 327 any of the files in the working directory when you commit; it just
jerojasro@343 328 modifies the dirstate to note its new parents.
jerojasro@343 329
jerojasro@343 330 \subsection{Creating a new head}
jerojasro@343 331
jerojasro@343 332 It's perfectly normal to update the working directory to a changeset
jerojasro@343 333 other than the current tip. For example, you might want to know what
jerojasro@343 334 your project looked like last Tuesday, or you could be looking through
jerojasro@343 335 changesets to see which one introduced a bug. In cases like this, the
jerojasro@343 336 natural thing to do is update the working directory to the changeset
jerojasro@343 337 you're interested in, and then examine the files in the working
jerojasro@343 338 directory directly to see their contents as they werea when you
jerojasro@343 339 committed that changeset. The effect of this is shown in
jerojasro@343 340 figure~\ref{fig:concepts:wdir-pre-branch}.
jerojasro@343 341
jerojasro@343 342 \begin{figure}[ht]
jerojasro@343 343 \centering
jerojasro@343 344 \grafix{wdir-pre-branch}
jerojasro@343 345 \caption{The working directory, updated to an older changeset}
jerojasro@343 346 \label{fig:concepts:wdir-pre-branch}
jerojasro@343 347 \end{figure}
jerojasro@343 348
jerojasro@343 349 Having updated the working directory to an older changeset, what
jerojasro@343 350 happens if you make some changes, and then commit? Mercurial behaves
jerojasro@343 351 in the same way as I outlined above. The parents of the working
jerojasro@343 352 directory become the parents of the new changeset. This new changeset
jerojasro@343 353 has no children, so it becomes the new tip. And the repository now
jerojasro@343 354 contains two changesets that have no children; we call these
jerojasro@343 355 \emph{heads}. You can see the structure that this creates in
jerojasro@343 356 figure~\ref{fig:concepts:wdir-branch}.
jerojasro@343 357
jerojasro@343 358 \begin{figure}[ht]
jerojasro@343 359 \centering
jerojasro@343 360 \grafix{wdir-branch}
jerojasro@343 361 \caption{After a commit made while synced to an older changeset}
jerojasro@343 362 \label{fig:concepts:wdir-branch}
jerojasro@343 363 \end{figure}
jerojasro@343 364
jerojasro@343 365 \begin{note}
jerojasro@343 366 If you're new to Mercurial, you should keep in mind a common
jerojasro@343 367 ``error'', which is to use the \hgcmd{pull} command without any
jerojasro@343 368 options. By default, the \hgcmd{pull} command \emph{does not}
jerojasro@343 369 update the working directory, so you'll bring new changesets into
jerojasro@343 370 your repository, but the working directory will stay synced at the
jerojasro@343 371 same changeset as before the pull. If you make some changes and
jerojasro@343 372 commit afterwards, you'll thus create a new head, because your
jerojasro@343 373 working directory isn't synced to whatever the current tip is.
jerojasro@343 374
jerojasro@343 375 I put the word ``error'' in quotes because all that you need to do
jerojasro@343 376 to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}. In
jerojasro@343 377 other words, this almost never has negative consequences; it just
jerojasro@343 378 surprises people. I'll discuss other ways to avoid this behaviour,
jerojasro@343 379 and why Mercurial behaves in this initially surprising way, later
jerojasro@343 380 on.
jerojasro@343 381 \end{note}
jerojasro@343 382
jerojasro@343 383 \subsection{Merging heads}
jerojasro@343 384
jerojasro@343 385 When you run the \hgcmd{merge} command, Mercurial leaves the first
jerojasro@343 386 parent of the working directory unchanged, and sets the second parent
jerojasro@343 387 to the changeset you're merging with, as shown in
jerojasro@343 388 figure~\ref{fig:concepts:wdir-merge}.
jerojasro@343 389
jerojasro@343 390 \begin{figure}[ht]
jerojasro@343 391 \centering
jerojasro@343 392 \grafix{wdir-merge}
jerojasro@343 393 \caption{Merging two heads}
jerojasro@343 394 \label{fig:concepts:wdir-merge}
jerojasro@343 395 \end{figure}
jerojasro@343 396
jerojasro@343 397 Mercurial also has to modify the working directory, to merge the files
jerojasro@343 398 managed in the two changesets. Simplified a little, the merging
jerojasro@343 399 process goes like this, for every file in the manifests of both
jerojasro@343 400 changesets.
jerojasro@343 401 \begin{itemize}
jerojasro@343 402 \item If neither changeset has modified a file, do nothing with that
jerojasro@343 403 file.
jerojasro@343 404 \item If one changeset has modified a file, and the other hasn't,
jerojasro@343 405 create the modified copy of the file in the working directory.
jerojasro@343 406 \item If one changeset has removed a file, and the other hasn't (or
jerojasro@343 407 has also deleted it), delete the file from the working directory.
jerojasro@343 408 \item If one changeset has removed a file, but the other has modified
jerojasro@343 409 the file, ask the user what to do: keep the modified file, or remove
jerojasro@343 410 it?
jerojasro@343 411 \item If both changesets have modified a file, invoke an external
jerojasro@343 412 merge program to choose the new contents for the merged file. This
jerojasro@343 413 may require input from the user.
jerojasro@343 414 \item If one changeset has modified a file, and the other has renamed
jerojasro@343 415 or copied the file, make sure that the changes follow the new name
jerojasro@343 416 of the file.
jerojasro@343 417 \end{itemize}
jerojasro@343 418 There are more details---merging has plenty of corner cases---but
jerojasro@343 419 these are the most common choices that are involved in a merge. As
jerojasro@343 420 you can see, most cases are completely automatic, and indeed most
jerojasro@343 421 merges finish automatically, without requiring your input to resolve
jerojasro@343 422 any conflicts.
jerojasro@343 423
jerojasro@343 424 When you're thinking about what happens when you commit after a merge,
jerojasro@343 425 once again the working directory is ``the changeset I'm about to
jerojasro@343 426 commit''. After the \hgcmd{merge} command completes, the working
jerojasro@343 427 directory has two parents; these will become the parents of the new
jerojasro@343 428 changeset.
jerojasro@343 429
jerojasro@343 430 Mercurial lets you perform multiple merges, but you must commit the
jerojasro@343 431 results of each individual merge as you go. This is necessary because
jerojasro@343 432 Mercurial only tracks two parents for both revisions and the working
jerojasro@343 433 directory. While it would be technically possible to merge multiple
jerojasro@343 434 changesets at once, the prospect of user confusion and making a
jerojasro@343 435 terrible mess of a merge immediately becomes overwhelming.
jerojasro@343 436
jerojasro@343 437 \section{Other interesting design features}
jerojasro@343 438
jerojasro@343 439 In the sections above, I've tried to highlight some of the most
jerojasro@343 440 important aspects of Mercurial's design, to illustrate that it pays
jerojasro@343 441 careful attention to reliability and performance. However, the
jerojasro@343 442 attention to detail doesn't stop there. There are a number of other
jerojasro@343 443 aspects of Mercurial's construction that I personally find
jerojasro@343 444 interesting. I'll detail a few of them here, separate from the ``big
jerojasro@343 445 ticket'' items above, so that if you're interested, you can gain a
jerojasro@343 446 better idea of the amount of thinking that goes into a well-designed
jerojasro@343 447 system.
jerojasro@343 448
jerojasro@343 449 \subsection{Clever compression}
jerojasro@343 450
jerojasro@343 451 When appropriate, Mercurial will store both snapshots and deltas in
jerojasro@343 452 compressed form. It does this by always \emph{trying to} compress a
jerojasro@343 453 snapshot or delta, but only storing the compressed version if it's
jerojasro@343 454 smaller than the uncompressed version.
jerojasro@343 455
jerojasro@343 456 This means that Mercurial does ``the right thing'' when storing a file
jerojasro@343 457 whose native form is compressed, such as a \texttt{zip} archive or a
jerojasro@343 458 JPEG image. When these types of files are compressed a second time,
jerojasro@343 459 the resulting file is usually bigger than the once-compressed form,
jerojasro@343 460 and so Mercurial will store the plain \texttt{zip} or JPEG.
jerojasro@343 461
jerojasro@343 462 Deltas between revisions of a compressed file are usually larger than
jerojasro@343 463 snapshots of the file, and Mercurial again does ``the right thing'' in
jerojasro@343 464 these cases. It finds that such a delta exceeds the threshold at
jerojasro@343 465 which it should store a complete snapshot of the file, so it stores
jerojasro@343 466 the snapshot, again saving space compared to a naive delta-only
jerojasro@343 467 approach.
jerojasro@343 468
jerojasro@343 469 \subsubsection{Network recompression}
jerojasro@343 470
jerojasro@343 471 When storing revisions on disk, Mercurial uses the ``deflate''
jerojasro@343 472 compression algorithm (the same one used by the popular \texttt{zip}
jerojasro@343 473 archive format), which balances good speed with a respectable
jerojasro@343 474 compression ratio. However, when transmitting revision data over a
jerojasro@343 475 network connection, Mercurial uncompresses the compressed revision
jerojasro@343 476 data.
jerojasro@343 477
jerojasro@343 478 If the connection is over HTTP, Mercurial recompresses the entire
jerojasro@343 479 stream of data using a compression algorithm that gives a better
jerojasro@343 480 compression ratio (the Burrows-Wheeler algorithm from the widely used
jerojasro@343 481 \texttt{bzip2} compression package). This combination of algorithm
jerojasro@343 482 and compression of the entire stream (instead of a revision at a time)
jerojasro@343 483 substantially reduces the number of bytes to be transferred, yielding
jerojasro@343 484 better network performance over almost all kinds of network.
jerojasro@343 485
jerojasro@343 486 (If the connection is over \command{ssh}, Mercurial \emph{doesn't}
jerojasro@343 487 recompress the stream, because \command{ssh} can already do this
jerojasro@343 488 itself.)
jerojasro@343 489
jerojasro@343 490 \subsection{Read/write ordering and atomicity}
jerojasro@343 491
jerojasro@343 492 Appending to files isn't the whole story when it comes to guaranteeing
jerojasro@343 493 that a reader won't see a partial write. If you recall
jerojasro@343 494 figure~\ref{fig:concepts:metadata}, revisions in the changelog point to
jerojasro@343 495 revisions in the manifest, and revisions in the manifest point to
jerojasro@343 496 revisions in filelogs. This hierarchy is deliberate.
jerojasro@343 497
jerojasro@343 498 A writer starts a transaction by writing filelog and manifest data,
jerojasro@343 499 and doesn't write any changelog data until those are finished. A
jerojasro@343 500 reader starts by reading changelog data, then manifest data, followed
jerojasro@343 501 by filelog data.
jerojasro@343 502
jerojasro@343 503 Since the writer has always finished writing filelog and manifest data
jerojasro@343 504 before it writes to the changelog, a reader will never read a pointer
jerojasro@343 505 to a partially written manifest revision from the changelog, and it will
jerojasro@343 506 never read a pointer to a partially written filelog revision from the
jerojasro@343 507 manifest.
jerojasro@343 508
jerojasro@343 509 \subsection{Concurrent access}
jerojasro@343 510
jerojasro@343 511 The read/write ordering and atomicity guarantees mean that Mercurial
jerojasro@343 512 never needs to \emph{lock} a repository when it's reading data, even
jerojasro@343 513 if the repository is being written to while the read is occurring.
jerojasro@343 514 This has a big effect on scalability; you can have an arbitrary number
jerojasro@343 515 of Mercurial processes safely reading data from a repository safely
jerojasro@343 516 all at once, no matter whether it's being written to or not.
jerojasro@343 517
jerojasro@343 518 The lockless nature of reading means that if you're sharing a
jerojasro@343 519 repository on a multi-user system, you don't need to grant other local
jerojasro@343 520 users permission to \emph{write} to your repository in order for them
jerojasro@343 521 to be able to clone it or pull changes from it; they only need
jerojasro@343 522 \emph{read} permission. (This is \emph{not} a common feature among
jerojasro@343 523 revision control systems, so don't take it for granted! Most require
jerojasro@343 524 readers to be able to lock a repository to access it safely, and this
jerojasro@343 525 requires write permission on at least one directory, which of course
jerojasro@343 526 makes for all kinds of nasty and annoying security and administrative
jerojasro@343 527 problems.)
jerojasro@343 528
jerojasro@343 529 Mercurial uses locks to ensure that only one process can write to a
jerojasro@343 530 repository at a time (the locking mechanism is safe even over
jerojasro@343 531 filesystems that are notoriously hostile to locking, such as NFS). If
jerojasro@343 532 a repository is locked, a writer will wait for a while to retry if the
jerojasro@343 533 repository becomes unlocked, but if the repository remains locked for
jerojasro@343 534 too long, the process attempting to write will time out after a while.
jerojasro@343 535 This means that your daily automated scripts won't get stuck forever
jerojasro@343 536 and pile up if a system crashes unnoticed, for example. (Yes, the
jerojasro@343 537 timeout is configurable, from zero to infinity.)
jerojasro@343 538
jerojasro@343 539 \subsubsection{Safe dirstate access}
jerojasro@343 540
jerojasro@343 541 As with revision data, Mercurial doesn't take a lock to read the
jerojasro@343 542 dirstate file; it does acquire a lock to write it. To avoid the
jerojasro@343 543 possibility of reading a partially written copy of the dirstate file,
jerojasro@343 544 Mercurial writes to a file with a unique name in the same directory as
jerojasro@343 545 the dirstate file, then renames the temporary file atomically to
jerojasro@343 546 \filename{dirstate}. The file named \filename{dirstate} is thus
jerojasro@343 547 guaranteed to be complete, not partially written.
jerojasro@343 548
jerojasro@343 549 \subsection{Avoiding seeks}
jerojasro@343 550
jerojasro@343 551 Critical to Mercurial's performance is the avoidance of seeks of the
jerojasro@343 552 disk head, since any seek is far more expensive than even a
jerojasro@343 553 comparatively large read operation.
jerojasro@343 554
jerojasro@343 555 This is why, for example, the dirstate is stored in a single file. If
jerojasro@343 556 there were a dirstate file per directory that Mercurial tracked, the
jerojasro@343 557 disk would seek once per directory. Instead, Mercurial reads the
jerojasro@343 558 entire single dirstate file in one step.
jerojasro@343 559
jerojasro@343 560 Mercurial also uses a ``copy on write'' scheme when cloning a
jerojasro@343 561 repository on local storage. Instead of copying every revlog file
jerojasro@343 562 from the old repository into the new repository, it makes a ``hard
jerojasro@343 563 link'', which is a shorthand way to say ``these two names point to the
jerojasro@343 564 same file''. When Mercurial is about to write to one of a revlog's
jerojasro@343 565 files, it checks to see if the number of names pointing at the file is
jerojasro@343 566 greater than one. If it is, more than one repository is using the
jerojasro@343 567 file, so Mercurial makes a new copy of the file that is private to
jerojasro@343 568 this repository.
jerojasro@343 569
jerojasro@343 570 A few revision control developers have pointed out that this idea of
jerojasro@343 571 making a complete private copy of a file is not very efficient in its
jerojasro@343 572 use of storage. While this is true, storage is cheap, and this method
jerojasro@343 573 gives the highest performance while deferring most book-keeping to the
jerojasro@343 574 operating system. An alternative scheme would most likely reduce
jerojasro@343 575 performance and increase the complexity of the software, each of which
jerojasro@343 576 is much more important to the ``feel'' of day-to-day use.
jerojasro@343 577
jerojasro@343 578 \subsection{Other contents of the dirstate}
jerojasro@343 579
jerojasro@343 580 Because Mercurial doesn't force you to tell it when you're modifying a
jerojasro@343 581 file, it uses the dirstate to store some extra information so it can
jerojasro@343 582 determine efficiently whether you have modified a file. For each file
jerojasro@343 583 in the working directory, it stores the time that it last modified the
jerojasro@343 584 file itself, and the size of the file at that time.
jerojasro@343 585
jerojasro@343 586 When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or
jerojasro@343 587 \hgcmd{copy} files, Mercurial updates the dirstate so that it knows
jerojasro@343 588 what to do with those files when you commit.
jerojasro@343 589
jerojasro@343 590 When Mercurial is checking the states of files in the working
jerojasro@343 591 directory, it first checks a file's modification time. If that has
jerojasro@343 592 not changed, the file must not have been modified. If the file's size
jerojasro@343 593 has changed, the file must have been modified. If the modification
jerojasro@343 594 time has changed, but the size has not, only then does Mercurial need
jerojasro@343 595 to read the actual contents of the file to see if they've changed.
jerojasro@343 596 Storing these few extra pieces of information dramatically reduces the
jerojasro@343 597 amount of data that Mercurial needs to read, which yields large
jerojasro@343 598 performance improvements compared to other revision control systems.
jerojasro@343 599
jerojasro@343 600 %%% Local Variables:
jerojasro@343 601 %%% mode: latex
jerojasro@343 602 %%% TeX-master: "00book"
jerojasro@343 603 %%% End: