hgbook
changeset 121:9094c9fda8ec
Start chapter on error recovery.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Nov 15 15:59:41 2006 -0800 (2006-11-15) |
parents | 51c9168ab5f8 |
children | 3af28630fe8c |
files | en/Makefile en/concepts.tex en/daily.tex en/examples/rollback en/undo.tex |
line diff
1.1 --- a/en/Makefile Wed Nov 15 13:10:30 2006 -0800 1.2 +++ b/en/Makefile Wed Nov 15 15:59:41 2006 -0800 1.3 @@ -18,7 +18,8 @@ 1.4 srcinstall.tex \ 1.5 template.tex \ 1.6 tour-basic.tex \ 1.7 - tour-merge.tex 1.8 + tour-merge.tex \ 1.9 + undo.tex 1.10 1.11 image-sources := \ 1.12 filelog.svg \ 1.13 @@ -54,6 +55,7 @@ 1.14 mq.tarball \ 1.15 mq.tools \ 1.16 mq.tutorial \ 1.17 + rollback \ 1.18 template.simple \ 1.19 template.svnstyle \ 1.20 tour \
2.1 --- a/en/concepts.tex Wed Nov 15 13:10:30 2006 -0800 2.2 +++ b/en/concepts.tex Wed Nov 15 15:59:41 2006 -0800 2.3 @@ -110,6 +110,7 @@ 2.4 arbitrary binary contents; it doesn't need to treat text as special. 2.5 2.6 \subsection{Safe operation} 2.7 +\label{sec:concepts:txn} 2.8 2.9 Mercurial only ever \emph{appends} data to the end of a revlog file. 2.10 It never modifies a section of a file after it has written it. This
3.1 --- a/en/daily.tex Wed Nov 15 13:10:30 2006 -0800 3.2 +++ b/en/daily.tex Wed Nov 15 15:59:41 2006 -0800 3.3 @@ -165,6 +165,8 @@ 3.4 file. It treats these copied files specially when you merge your work 3.5 with someone else's. 3.6 3.7 +\subsection{The results of copying during a merge} 3.8 + 3.9 What happens during a merge is that changes ``follow'' a copy. To 3.10 best illustrate what this means, let's create an example. We'll start 3.11 with the usual tiny repository that contains a single file. 3.12 @@ -307,6 +309,13 @@ 3.13 something you might expect to ``simply work,'' but not all revision 3.14 control systems actually do this.) 3.15 3.16 +Whereas having changes follow a copy is a feature where you can 3.17 +perhaps nod and say ``yes, that might be useful,'' it should be clear 3.18 +that having them follow a rename is definitely important. Without 3.19 +this facility, it would simply be too easy for changes to become 3.20 +orphaned when files are renamed. 3.21 + 3.22 + 3.23 %%% Local Variables: 3.24 %%% mode: latex 3.25 %%% TeX-master: "00book"
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/examples/rollback Wed Nov 15 15:59:41 2006 -0800 4.3 @@ -0,0 +1,37 @@ 4.4 +#!/bin/bash 4.5 + 4.6 +hg init a 4.7 +cd a 4.8 +echo a > a 4.9 +hg ci -A -m 'First commit' 4.10 + 4.11 +echo a >> a 4.12 + 4.13 +#$ name: tip 4.14 + 4.15 +#$ name: commit 4.16 + 4.17 +hg status 4.18 +echo b > b 4.19 +hg commit -m 'Add file b' 4.20 + 4.21 +#$ name: status 4.22 + 4.23 +hg status 4.24 +hg tip 4.25 + 4.26 +#$ name: rollback 4.27 + 4.28 +hg rollback 4.29 +hg tip 4.30 +hg status 4.31 + 4.32 +#$ name: add 4.33 + 4.34 +hg add b 4.35 +hg commit -m 'Add file b, this time for real' 4.36 + 4.37 +#$ name: twice 4.38 + 4.39 +hg rollback 4.40 +hg rollback
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/undo.tex Wed Nov 15 15:59:41 2006 -0800 5.3 @@ -0,0 +1,117 @@ 5.4 +\chapter{Finding and fixing your mistakes} 5.5 +\label{chap:undo} 5.6 + 5.7 +To err might be human, but to really handle the consequences well 5.8 +takes a top-notch revision control system. In this chapter, we'll 5.9 +discuss some of the techniques you can use when you find that a 5.10 +problem has crept into your project. Mercurial has some highly 5.11 +capable features that will help you to isolate the sources of 5.12 +problems, and to handle them appropriately. 5.13 + 5.14 +\section{Easily recovered errors} 5.15 + 5.16 +\subsection{The accidental commit} 5.17 + 5.18 +I have the occasional but persistent problem of typing rather more 5.19 +quickly than I can think, which sometimes results in me committing a 5.20 +changeset that is either incomplete or plain wrong. In my case, the 5.21 +usual kind of incomplete changeset is one in which I've created a new 5.22 +source file, but forgotten to \hgcmd{add} it. A ``plain wrong'' 5.23 +changeset is not as common, but no less annoying. 5.24 + 5.25 +\subsection{Rolling back a transaction} 5.26 + 5.27 +In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats 5.28 +each modification of a repository as a \emph{transaction}. Every time 5.29 +you commit a changeset or pull changes from another repository, 5.30 +Mercurial remembers what you did. You can undo, or \emph{roll back}, 5.31 +exactly one of these actions using the \hgcmd{rollback} command. 5.32 + 5.33 +Here's a mistake that I often find myself making: committing a change 5.34 +in which I've created a new file, but forgotten to \hgcmd{add} it. 5.35 +\interaction{rollback.commit} 5.36 +Looking at the output of \hgcmd{status} after the commit immediately 5.37 +confirms the error. 5.38 +\interaction{rollback.status} 5.39 +The commit captured the changes to the file \filename{a}, but not the 5.40 +new file \filename{b}. If I were to push this changeset to a 5.41 +repository that I shared with a colleague, the chances are high that 5.42 +something in \filename{a} would refer to \filename{b}, which would not 5.43 +be present in their repository when they pulled my changes. I would 5.44 +thus become the object of some indignation. 5.45 + 5.46 +However, luck is with me---I've caught my error before I pushed the 5.47 +changeset. I use the \hgcmd{rollback} command, and Mercurial makes 5.48 +that last changeset vanish. 5.49 +\interaction{rollback.rollback} 5.50 +Notice that the changeset is no longer present in the repository's 5.51 +history, and the working directory once again thinks that the file 5.52 +\filename{a} is modified. The changeset has been completely erased. 5.53 +I can now safely \hgcmd{add} the file \filename{b}, and rerun my 5.54 +commit. 5.55 +\interaction{rollback.add} 5.56 + 5.57 +\subsection{The erroneous pull} 5.58 + 5.59 +It's common practice with Mercurial to maintain separate development 5.60 +branches of a project in different repositories. Your development 5.61 +team might have one shared repository for your project's ``0.9'' 5.62 +release, and another, containing different changes, for the ``1.0'' 5.63 +release. 5.64 + 5.65 +Given this, you can imagine that the consequences could be messy if 5.66 +you had a local ``0.9'' repository, and accidentally pulled changes 5.67 +from the shared ``1.0'' repository into it. At worst, you could be 5.68 +paying insufficient attention, and push those changes into the shared 5.69 +``0.9'' tree, confusing your entire team (but don't worry, we'll 5.70 +return to this horror scenario later). However, it's more likely that 5.71 +you'll notice immediately, because Mercurial will display the URL it's 5.72 +pulling from, or you will see it pull a suspiciously large number of 5.73 +changes into the repository. 5.74 + 5.75 +The \hgcmd{rollback} command will work nicely to expunge all of the 5.76 +changesets that you just pulled. Mercurial groups all changes from 5.77 +one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is 5.78 +all you need to undo this mistake. 5.79 + 5.80 +\subsection{Rolling back is useless once you've pushed} 5.81 + 5.82 +The value of the \hgcmd{rollback} command drops to zero once you've 5.83 +pushed your changes to another repository. Rolling back a change 5.84 +makes it disappear entirely, but \emph{only} in the repository in 5.85 +which you perform the \hgcmd{rollback}. Because a rollback eliminates 5.86 +history, there's no way for the disappearance of a change to propagate 5.87 +between repositories. 5.88 + 5.89 +If you've pushed a change to another repository---particularly if it's 5.90 +a shared repository---it has essentially ``escaped into the wild,'' 5.91 +and you'll have to recover from your mistake in a different way. What 5.92 +will happen if you push a changeset somewhere, then roll it back, then 5.93 +pull from the repository you pushed to, is that the changeset will 5.94 +reappear in your repository. 5.95 + 5.96 +(If you absolutely know for sure that the change you want to roll back 5.97 +is the most recent change in the repository that you pushed to, 5.98 +\emph{and} you know that nobody else could have pulled it from that 5.99 +repository, you can roll back the changeset there, too, but you really 5.100 +should really not rely on this working reliably. If you do this, 5.101 +sooner or later a change really will make it into a repository that 5.102 +you don't directly control (or have forgotten about), and come back to 5.103 +bite you.) 5.104 + 5.105 +\subsection{You can only roll back once} 5.106 + 5.107 +Mercurial stores exactly one transaction in its transaction log; that 5.108 +transaction is the most recent one that occurred in the repository. 5.109 +This means that you can only roll back one transaction. If you expect 5.110 +to be able to roll back one transaction, then its predecessor, this is 5.111 +not the behaviour you will get. 5.112 +\interaction{rollback.twice} 5.113 +Once you've rolled back one transaction in a repository, you can't 5.114 +roll back again in that repository until you perform another commit or 5.115 +pull. 5.116 + 5.117 +%%% Local Variables: 5.118 +%%% mode: latex 5.119 +%%% TeX-master: "00book" 5.120 +%%% End: