commit b5bd6133383ebef019a1d03cfc0943d596d71722 from: Stefan Sperling date: Thu Aug 15 10:56:52 2019 UTC initial examples page commit - 577b639042adcfefcbc2cc932b84bc8f343d8405 commit + b5bd6133383ebef019a1d03cfc0943d596d71722 blob - /dev/null blob + 126742de73491b0f8156d26fe8258747ab5de1e9 (mode 644) --- /dev/null +++ examples.html @@ -0,0 +1,173 @@ + + + + +Game of Trees (Got): Examples + + + + + +

+ +Game of Trees +Examples +

+
+ +

+
+These examples are supplemental documentation to the man pages, which are +available both in the installed system and +online. + +

Quick Links:

+ + + + Amending the latest commit
+ Using got(1) with ports tree + +
+ +

+

+ +

+ +

+Sometimes a mistake is found in the latest commit on a branch. +This section explains how such a mistake can be corrected with Got. + +

+As a first step, Got can create another commit which undoes the changes +made by the latest commit. Assuming a branch called master, +the latest commit on this branch can be identified by the same +name (master). +In a clean work tree according to got status, run: +

+$ got backout master
+$ got commit -m 'oops, roll back previous'
+
+ +Using got backout a second time will now fetch the rolled-back +change into the work tree as a local change which can be amended:

+ +
+$ got backout master
+(edit files)
+$ got commit -m 'fixed version of previous change'
+
+ +The history of the tree latest commits on the branch would +now look something like this: + +
+$ got log -l 3
+-----------------------------------------------
+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!
+ 
+
+ +

+If commit 7ef28ff8dd61cbf38f88784ea8c11e373757985f has already +been copied to another repository, our story ends here because the history +must now be considered immutable. + +

+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: + +

+$ got log -l 4 | grep ^commit| tail -n 1
+commit e27a7222faaa171dcb086ea0b566dc7bebb74a0b (origin/master)
+
+ +

+Back-date the work tree to this commit and ask Got to edit the history +leading up to the latest commit on the branch: + +

+$ got update -c e27a7222fa
+$ got histedit
+
+ +

+The histedit command will open a histedit script in an editor: + +

+# 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
+
+ +

+To make the mistaken commits disappear from history, the corresponding +lines can changed to execute drop commands, and the log message +of the latest commit can be changed to that of the original commit: + +

+drop 7ef28ff8dd61cbf38f88784ea8c11e373757985f this is surely a great idea!
+drop 82f6abb8b1a22fe62d2a8a8d0cdbb73c9d85fcda oops, roll back previous
+pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
+mesg this is surely a great idea!
+
+ +

+After saving the file and exiting the editor, Got will create a new +version of history which does not contain the mistake: + +

+$ got log -l 1
+-----------------------------------------------
+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!
+ 
+
+ +

CAVEAT: +

The mesg 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: + +

+[...]
+pick bcb49d15e041ddffb59397d2fe851fdb1729b005 fixed version of previous change
+mesg
+
+ +

+ +WIP, coming soon... + + + +