commit - 577b639042adcfefcbc2cc932b84bc8f343d8405
commit + b5bd6133383ebef019a1d03cfc0943d596d71722
blob - /dev/null
blob + 126742de73491b0f8156d26fe8258747ab5de1e9 (mode 644)
--- /dev/null
+++ examples.html
+<!doctype html>
+<html lang=en>
+<meta charset=utf-8>
+
+<title>Game of Trees (Got): Examples</title>
+<meta name="description" content="Game of Trees (Got) Examples">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="stylesheet" type="text/css" href="openbsd.css">
+<link rel="canonical" href="https://gameoftrees.org/examples.html">
+
+<h2>
+<a href="index.html">
+<i>Game of Trees</i></a>
+Examples
+</h2>
+<hr>
+
+<p id="callout">
+<br>
+These examples are supplemental documentation to the man pages, which are
+available both in the installed system and
+<a href="https://gameoftrees.org/manual.html">online</a>.
+
+<h3>Quick Links:</h3>
+
+<table>
+ <tr>
+ <a href="#amend" >Amending the latest commit</a><br>
+ <a href="#ports" >Using got(1) with ports tree</a>
+ </tr>
+</table>
+
+<p>
+<hr>
+
+<h2 id="amend"><a class="permalink" href="#rollback">Amending the latest commit</a></h2>
+
+<p>
+Sometimes a mistake is found in the latest commit on a branch.
+This section explains how such a mistake can be corrected with Got.
+
+<p>
+As a first step, Got can create another commit which undoes the changes
+made by the latest commit. Assuming a branch called <tt>master</tt>,
+the latest commit on this branch can be identified by the same
+name (<tt>master</tt>).
+In a clean work tree according to <tt>got status</tt>, run:
+<pre class="cmdbox">
+$ <b>got backout master</b>
+$ <b>got commit -m 'oops, roll back previous'</b>
+</pre>
+
+Using <tt>got backout</tt> a second time will now fetch the rolled-back
+change into the work tree as a local change which can be amended:</p>
+
+<pre class="cmdbox">
+$ <b>got backout master</b>
+(edit files)
+$ <b>got commit -m 'fixed version of previous change'</b>
+</pre>
+
+The history of the tree latest commits on the branch would
+now look something like this:
+
+<pre class="cmdbox">
+$ <b>got log -l 3</b>
+-----------------------------------------------
+commit bcb49d15e041ddffb59397d2fe851fdb1729b005 (master)
+from: Flan Hacker <flan_hacker@openbsd.org>
+date: Wed Aug 14 22:07:22 2038 UTC
+
+ fixed version of previous change
+
+-----------------------------------------------
+commit 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda
+from: Flan Hacker <flan_hacker@openbsd.org>
+date: Wed Aug 14 21:37:07 2038 UTC
+
+ oops, roll back previous
+
+-----------------------------------------------
+commit 7ef28ff8dd61cbf38f88784ea8c11e373757985f
+from: Flan Hacker <flan_hacker@openbsd.org>
+date: Wed Aug 14 21:10:00 2038 UTC
+
+ this is surely a great idea!
+
+</pre>
+
+<p>
+If commit <tt>7ef28ff8dd61cbf38f88784ea8c11e373757985f</tt> has already
+been copied to another repository, our story ends here because the history
+must now be considered immutable.
+
+<p>
+Otherwise, the local branch history can be edited to cover up our little
+mistake. First, find the ID of the parent commit of the bad commit:
+
+<pre class="cmdbox">
+$ <b>got log -l 4 | grep ^commit| tail -n 1</b>
+commit e27a7222faaa171dcb086ea0b566dc7bebb74a0b (origin/master)
+</pre>
+
+<p>
+Back-date the work tree to this commit and ask Got to edit the history
+leading up to the latest commit on the branch:
+
+<pre class="cmdbox">
+$ <b>got update -c e27a7222fa</b>
+$ <b>got histedit</b>
+</pre>
+
+<p>
+The <tt>histedit</tt> command will open a histedit script in an editor:
+
+<pre class="cmdbox">
+# Available histedit commands:
+# pick (p): use commit
+# edit (e): use commit but stop for amending
+# fold (f): combine with commit below
+# drop (d): remove commit from history
+# mesg (m): single-line log message for commit above (open editor if empty)
+# Commits will be processed in order from top to bottom of this file.
+pick 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
+pick 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous
+pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
+</pre>
+
+<p>
+To make the mistaken commits disappear from history, the corresponding
+lines can changed to execute <tt>drop</tt> commands, and the log message
+of the latest commit can be changed to that of the original commit:
+
+<pre class="cmdbox">
+<b>drop</b> 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
+<b>drop</b> 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous
+pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
+<b>mesg this is surely a great idea!</b>
+</pre>
+
+<p>
+After saving the file and exiting the editor, Got will create a new
+version of history which does not contain the mistake:
+
+<pre class="cmdbox">
+$ <b>got log -l 1</b>
+-----------------------------------------------
+commit 60b83404dd25547f19d9b468b931809541a3325c (master)
+from: Flan Hacker <flan_hacker@openbsd.org>
+date: Wed Aug 14 22:17:12 2038 UTC
+
+ this is surely a great idea!
+
+</pre>
+
+<p id="callout">CAVEAT:
+<p>The <tt>mesg</tt> command of the histedit script only accepts a
+single-line log message argument. Omit the argument to write a new
+multi-line log message in an editor:
+
+<pre class="cmdbox">
+[...]
+pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
+<b>mesg</b>
+</pre>
+
+<h2 id="ports"><a class="permalink" href="#ports">Using got(1) with ports tree</a></h2>
+
+WIP, coming soon...
+
+
+</body>
+</html>
