comparison en/ch08-undo.xml @ 808:557552d4699f

Add IDs to paragraphs.

807:7226e5e750a6

    &interaction.daily.revert.status;

    <tip>
      <title>Be careful with <filename>.orig</filename> files</title>

      <para>It's extremely unlikely that you are either using
	Mercurial to manage files with <filename>.orig</filename>
	extensions or that you even care about the contents of such
	files.  Just in case, though, it's useful to remember that
	<command role="hg-cmd">hg revert</command> will
	unconditionally overwrite an existing file with a

      <para id="x_103">The result is that you end up <quote>back where you
	  were</quote>, only with some extra history that undoes the
	effect of the changeset you wanted to back out.</para>

      <para>You might wonder why Mercurial does not commit the result
	of the merge that it performed.  The reason lies in Mercurial
	behaving conservatively: a merge naturally has more scope for
	error than simply undoing the effect of the tip changeset,
	so your work will be safest if you first inspect (and test!)
	the result of the merge, <emphasis>then</emphasis> commit

      changesets intact.</para>

    <sect2>
      <title>Backing out a merge</title>

      <para>Since merges are often complicated, it is not unheard of
	for a merge to be mangled badly, but committed erroneously.
	Mercurial provides an important safeguard against bad merges
	by refusing to commit unresolved files, but human ingenuity
	guarantees that it is still possible to mess a merge up and
	commit it.</para>

      <para>Given a bad merge that has been committed, usually the
	best way to approach it is to simply try to repair the damage
	by hand.  A complete disaster that cannot be easily fixed up
	by hand ought to be very rare, but the <command
	  role="hg-cmd">hg backout</command> command may help in
	making the cleanup easier. It offers a <option

	  <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para>Suppose we have a revision graph like that in <xref
	  linkend="fig:undo:bad-merge-1"/>.  What we'd like is to
	<emphasis>redo</emphasis> the merge of revisions 2 and
	3.</para>

      <para>One way to do so would be as follows.</para>

      <orderedlist>
	<listitem>
	  <para>Call <command role="hg-cmd">hg backout --rev=4
	      --parent=2</command>.  This tells <command
	      role="hg-cmd">hg backout</command> to back out revision
	    4, which is the bad merge, and to when deciding which
	    revision to prefer, to choose parent 2, one of the parents
	    of the merge.  The effect can be seen in <xref

	    </mediaobject>
	  </figure>
	</listitem>

	<listitem>
	  <para>Call <command role="hg-cmd">hg backout --rev=4
	      --parent=3</command>.  This tells <command
	      role="hg-cmd">hg backout</command> to back out revision
	    4 again, but this time to choose parent 3, the other
	    parent of the merge.  The result is visible in <xref
	    linkend="fig:undo:bad-merge-3"/>, in which the repository

	    </mediaobject>
	  </figure>
	</listitem>

	<listitem>
	  <para>Redo the bad merge by merging the two backout heads,
	    which reduces the number of heads in the repository to
	    two, as can be seen in <xref
	      linkend="fig:undo:bad-merge-4"/>.</para>
	  <figure id="fig:undo:bad-merge-4">
	    <title>Merging the backouts</title>

	    </mediaobject>
	  </figure>
	</listitem>

	<listitem>
	  <para>Merge with the commit that was made after the bad
	    merge, as shown in <xref
	      linkend="fig:undo:bad-merge-5"/>.</para>
	  <figure id="fig:undo:bad-merge-5">
	    <title>Merging the backouts</title>
	    <mediaobject>

    </sect2>

    <sect2>
      <title>What to do about sensitive changes that escape</title>

      <para>Even a carefully run project can suffer an unfortunate
	event such as the committing and uncontrolled propagation of a
	file that contains important passwords.</para>

      <para>If something like this happens to you, and the information
	that gets accidentally propagated is truly sensitive, your
	first step should be to mitigate the effect of the leak
	without trying to control the leak itself. If you are not 100%
	certain that you know exactly who could have seen the changes,
	you should immediately change passwords, cancel credit cards,
	or find some other way to make sure that the information that
	has leaked is no longer useful.  In other words, assume that
	the change has propagated far and wide, and that there's
	nothing more you can do.</para>

      <para>You might hope that there would be mechanisms you could
	use to either figure out who has seen a change or to erase the
	change permanently everywhere, but there are good reasons why
	these are not possible.</para>

      <para>Mercurial does not provide an audit trail of who has
	pulled changes from a repository, because it is usually either
	impossible to record such information or trivial to spoof it.
	In a multi-user or networked environment, you should thus be
	extremely skeptical of yourself if you think that you have
	identified every place that a sensitive changeset has

	bundles by email, have their backup software save data
	offsite, carry repositories on USB sticks, and find other
	completely innocent ways to confound your attempts to track
	down every copy of a problematic change.</para>

      <para>Mercurial also does not provide a way to make a file or
	changeset completely disappear from history, because there is
	no way to enforce its disappearance; someone could easily
	modify their copy of Mercurial to ignore such directives. In
	addition, even if Mercurial provided such a capability,
	someone who simply hadn't pulled a <quote>make this file

808:557552d4699f

    &interaction.daily.revert.status;

    <tip>
      <title>Be careful with <filename>.orig</filename> files</title>

      <para id="x_6b8">It's extremely unlikely that you are either using
	Mercurial to manage files with <filename>.orig</filename>
	extensions or that you even care about the contents of such
	files.  Just in case, though, it's useful to remember that
	<command role="hg-cmd">hg revert</command> will
	unconditionally overwrite an existing file with a

      <para id="x_103">The result is that you end up <quote>back where you
	  were</quote>, only with some extra history that undoes the
	effect of the changeset you wanted to back out.</para>

      <para id="x_6b9">You might wonder why Mercurial does not commit the result
	of the merge that it performed.  The reason lies in Mercurial
	behaving conservatively: a merge naturally has more scope for
	error than simply undoing the effect of the tip changeset,
	so your work will be safest if you first inspect (and test!)
	the result of the merge, <emphasis>then</emphasis> commit

      changesets intact.</para>

    <sect2>
      <title>Backing out a merge</title>

      <para id="x_6ba">Since merges are often complicated, it is not unheard of
	for a merge to be mangled badly, but committed erroneously.
	Mercurial provides an important safeguard against bad merges
	by refusing to commit unresolved files, but human ingenuity
	guarantees that it is still possible to mess a merge up and
	commit it.</para>

      <para id="x_6bb">Given a bad merge that has been committed, usually the
	best way to approach it is to simply try to repair the damage
	by hand.  A complete disaster that cannot be easily fixed up
	by hand ought to be very rare, but the <command
	  role="hg-cmd">hg backout</command> command may help in
	making the cleanup easier. It offers a <option

	  <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <para id="x_6bc">Suppose we have a revision graph like that in <xref
	  linkend="fig:undo:bad-merge-1"/>.  What we'd like is to
	<emphasis>redo</emphasis> the merge of revisions 2 and
	3.</para>

      <para id="x_6bd">One way to do so would be as follows.</para>

      <orderedlist>
	<listitem>
	  <para id="x_6be">Call <command role="hg-cmd">hg backout --rev=4
	      --parent=2</command>.  This tells <command
	      role="hg-cmd">hg backout</command> to back out revision
	    4, which is the bad merge, and to when deciding which
	    revision to prefer, to choose parent 2, one of the parents
	    of the merge.  The effect can be seen in <xref

	    </mediaobject>
	  </figure>
	</listitem>

	<listitem>
	  <para id="x_6bf">Call <command role="hg-cmd">hg backout --rev=4
	      --parent=3</command>.  This tells <command
	      role="hg-cmd">hg backout</command> to back out revision
	    4 again, but this time to choose parent 3, the other
	    parent of the merge.  The result is visible in <xref
	    linkend="fig:undo:bad-merge-3"/>, in which the repository

	    </mediaobject>
	  </figure>
	</listitem>

	<listitem>
	  <para id="x_6c0">Redo the bad merge by merging the two backout heads,
	    which reduces the number of heads in the repository to
	    two, as can be seen in <xref
	      linkend="fig:undo:bad-merge-4"/>.</para>
	  <figure id="fig:undo:bad-merge-4">
	    <title>Merging the backouts</title>

	    </mediaobject>
	  </figure>
	</listitem>

	<listitem>
	  <para id="x_6c1">Merge with the commit that was made after the bad
	    merge, as shown in <xref
	      linkend="fig:undo:bad-merge-5"/>.</para>
	  <figure id="fig:undo:bad-merge-5">
	    <title>Merging the backouts</title>
	    <mediaobject>

    </sect2>

    <sect2>
      <title>What to do about sensitive changes that escape</title>

      <para id="x_6c2">Even a carefully run project can suffer an unfortunate
	event such as the committing and uncontrolled propagation of a
	file that contains important passwords.</para>

      <para id="x_6c3">If something like this happens to you, and the information
	that gets accidentally propagated is truly sensitive, your
	first step should be to mitigate the effect of the leak
	without trying to control the leak itself. If you are not 100%
	certain that you know exactly who could have seen the changes,
	you should immediately change passwords, cancel credit cards,
	or find some other way to make sure that the information that
	has leaked is no longer useful.  In other words, assume that
	the change has propagated far and wide, and that there's
	nothing more you can do.</para>

      <para id="x_6c4">You might hope that there would be mechanisms you could
	use to either figure out who has seen a change or to erase the
	change permanently everywhere, but there are good reasons why
	these are not possible.</para>

      <para id="x_6c5">Mercurial does not provide an audit trail of who has
	pulled changes from a repository, because it is usually either
	impossible to record such information or trivial to spoof it.
	In a multi-user or networked environment, you should thus be
	extremely skeptical of yourself if you think that you have
	identified every place that a sensitive changeset has

	bundles by email, have their backup software save data
	offsite, carry repositories on USB sticks, and find other
	completely innocent ways to confound your attempts to track
	down every copy of a problematic change.</para>

      <para id="x_6c6">Mercurial also does not provide a way to make a file or
	changeset completely disappear from history, because there is
	no way to enforce its disappearance; someone could easily
	modify their copy of Mercurial to ignore such directives. In
	addition, even if Mercurial provided such a capability,
	someone who simply hadn't pulled a <quote>make this file