Fossil SCM
Added a new section "Resetting the Repository" to the gitusers doc, following and relying on the two recently-updated sections.
Commit
bd7b10998d5cb673c969d15ad498c67651575c9d8673f058c7d3cf2423c4784a
Parent
b2a29bf41f70478…
1 file changed
+103
-5
+103
-5
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -4,15 +4,19 @@ | ||
| 4 | 4 | |
| 5 | 5 | Fossil shares many similarities with Git. In many cases, the |
| 6 | 6 | sub-commands are identical: [`fossil bisect`][fbis] does essentially the |
| 7 | 7 | same thing as [`git bisect`][gbis], for example. |
| 8 | 8 | |
| 9 | -This document covers the cases where there is no simple 1:1 mapping, | |
| 9 | +Yet, Fossil is not merely Git with a bunch of commands misspelled. If | |
| 10 | +that were the case, we could give you a two-column translation table | |
| 11 | +which would tell you how to say things like “`git reset --hard HEAD`” in | |
| 12 | +this funny ol’ Fossil dialect of Git and be done. The purpose of this | |
| 13 | +document is to cover all the cases where there is no simple 1:1 mapping, | |
| 10 | 14 | usually because of intentional design differences in Fossil that prevent |
| 11 | 15 | it from working exactly like Git. We choose to explain these differences |
| 12 | -rather than provide a simple “translation dictionary,” since to | |
| 13 | -understand the conversion, you need to know why the difference exists. | |
| 16 | +since to understand the conversion, you need to know why each difference | |
| 17 | +exists. | |
| 14 | 18 | |
| 15 | 19 | We focus on practical command examples here, leaving discussions of the |
| 16 | 20 | philosophical underpinnings that drive these command differences to [another |
| 17 | 21 | document][fvg]. The [case studies](#cs1) do get a bit philosophical, but |
| 18 | 22 | it is with the aim of illustrating how these Fossil design differences |
| @@ -589,11 +593,12 @@ | ||
| 589 | 593 | |
| 590 | 594 | 1. Alice commits to her local clone and *separately* pushes the change |
| 591 | 595 | up to the central machine C in typical Git fashion. |
| 592 | 596 | 2. Bob does the same. |
| 593 | 597 | 3. Alice says “`fossil pull`” to bring changes from C down, sees what |
| 594 | - Bob did to their shared working branch, and becomes wrothful. | |
| 598 | + Bob did to their shared working branch, and becomes most wrathful. | |
| 599 | + (Tsk, tsk.) | |
| 595 | 600 | |
| 596 | 601 | We’ll get to what you do about this situation below, but for now let us |
| 597 | 602 | focus on the fact that you’ve made it easier for [forks] to occur in the |
| 598 | 603 | development history by disabling autosync. If all three machines were |
| 599 | 604 | online and syncing at the time the sequence above began, Bob would |
| @@ -674,10 +679,103 @@ | ||
| 674 | 679 | branches, not just one named local branch. |
| 675 | 680 | |
| 676 | 681 | [capt]: ./cap-theorem.md |
| 677 | 682 | [rem]: /help?cmd=remote |
| 678 | 683 | |
| 684 | + | |
| 685 | +<a id="reset"></a> | |
| 686 | +## Resetting the Repository | |
| 687 | + | |
| 688 | +Extending from [the prior item](#syncall), you may correctly infer that | |
| 689 | +“[delete the project, and download a fresh copy][x1597]” has no part in | |
| 690 | +the Fossil Way. Ideally, you should never find yourself forced into | |
| 691 | +desperate measures like this:(^Parsing the output of `fossil status` is | |
| 692 | +usually a mistake since it relies on a potentially unstable interface. | |
| 693 | +We make no guarantee that there will always be a line beginning with | |
| 694 | +“`repo`” and that it will be separated from the repository’s file name | |
| 695 | +by a colon. The simplified example above is also liable to become | |
| 696 | +confused by whitespace in file names.) | |
| 697 | + | |
| 698 | + | |
| 699 | +``` | |
| 700 | + $ repo=$(fossil status | grep ^repo | cut -f2 -d:) | |
| 701 | + $ url=$(fossil remote) | |
| 702 | + $ fossil close # Stop here and think if it warns you! | |
| 703 | + $ mv $repo ${repo}.old | |
| 704 | + $ fossil clone $url $repo | |
| 705 | + $ fossil open --force $repo | |
| 706 | +``` | |
| 707 | + | |
| 708 | +What, then, should you as a Git transplant do instead when you find | |
| 709 | +yourself reaching for “`git reset`”? | |
| 710 | + | |
| 711 | +Since the correct answer to that depends on why you think it’s a good | |
| 712 | +solution to your immediate problem, we’ll take our motivating scenario | |
| 713 | +from the problem setup above, where we discussed Fossil’s [autosync] | |
| 714 | +feature. Let us further say Alice’s pique results from a belief that | |
| 715 | +Bob’s commit is objectively wrong-headed and should be expunged | |
| 716 | +henceforth. Since Fossil goes out of its way to ensure that [commits are | |
| 717 | +durable][wdm], it should be no further surprise that there is no easier | |
| 718 | +method to reset Bob’s clone in favor of Alice’s than the above sequence | |
| 719 | +in Fossil’s command set. Except in extreme situations, we believe that | |
| 720 | +sort of thing is unnecessary. | |
| 721 | + | |
| 722 | +Instead, Bob can say something like this: | |
| 723 | + | |
| 724 | +``` | |
| 725 | + fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip | |
| 726 | + fossil up trunk | |
| 727 | + fossil push | |
| 728 | +``` | |
| 729 | + | |
| 730 | +Unlike in Git, the “`amend`” command doesn’t modify prior committed | |
| 731 | +artifacts. Bob’s first command doesn’t delete anything, merely tells | |
| 732 | +Fossil to hide his mistake from timeline views by inserting a few new | |
| 733 | +records into the local repository to change how the client interprets | |
| 734 | +the data it finds there henceforth.(^One to change the tag marking this | |
| 735 | +commit’s branch name to “`MISTAKE`,” one to mark that branch as hidden, | |
| 736 | +and one to close it to further commits.). | |
| 737 | + | |
| 738 | +Bob’s second command switches his working directory back to the prior | |
| 739 | +commit on that branch. We’re presuming it was “`trunk`” for the sake of | |
| 740 | +the example, but it works for any parent branch name. The command works | |
| 741 | +because the name “`trunk`” now means something different to Fossil by | |
| 742 | +virtue of the first command. | |
| 743 | + | |
| 744 | +Bob’s third command pushes the changes up to the central machine to | |
| 745 | +inform everyone else of his amendment.(^Amendments don’t autosync in | |
| 746 | +Fossil because they don’t change any previous commits, allowing the | |
| 747 | +other clones to continue working safely with their existing commit | |
| 748 | +hashes.) | |
| 749 | + | |
| 750 | +In this scheme, Alice then needs to say “`fossil update trunk`” in order | |
| 751 | +to return her check-out’s parent commit to the previous version lest her | |
| 752 | +next attempted commit land atop this mistake branch. The fact that Bob | |
| 753 | +marked the branch as closed will prevent that from going thru, cluing | |
| 754 | +Alice into what she needs to do to remedy the situation, but that merely | |
| 755 | +shows why it’s a better workflow if Alice makes the amendment herself: | |
| 756 | + | |
| 757 | +``` | |
| 758 | + fossil amend --branch MISTAKE --hide --close \ | |
| 759 | + -m "shunt Bob’s erroneous commit off" tip | |
| 760 | + fossil up trunk | |
| 761 | + fossil push | |
| 762 | +``` | |
| 763 | + | |
| 764 | +Then she can fire off an email listing Bob’s assorted failings and go | |
| 765 | +about her work. This asynchronous workflow solves the problem without | |
| 766 | +requiring explicit coordination with Bob. When he gets his email, he can | |
| 767 | +then say “`fossil up trunk`” himself, which by default will trigger an | |
| 768 | +autosync, pulling down Alice’s amendments and getting him back onto her | |
| 769 | +development track. | |
| 770 | + | |
| 771 | +Remember that [branch names need not be unique](#btnames) in Fossil. You | |
| 772 | +are free to reuse this “`MISTAKE`” branch name as often as you need to. | |
| 773 | + | |
| 774 | +[autosync]: #autosync | |
| 775 | +[x1597]: https://xkcd.com/1597/ | |
| 776 | + | |
| 679 | 777 | |
| 680 | 778 | <a id="trunk"></a> |
| 681 | 779 | ## The Main Branch Is Called "`trunk`" |
| 682 | 780 | |
| 683 | 781 | In Fossil, the default name for the main branch |
| @@ -1218,11 +1316,11 @@ | ||
| 1218 | 1316 | |
| 1219 | 1317 | fossil ci |
| 1220 | 1318 | |
| 1221 | 1319 | It’s one short command for Fossil instead of three for Git — or two if |
| 1222 | 1320 | you abbreviate it as “`git commit -a && git push`” — because of Fossil’s |
| 1223 | -[autosync feature](#autosync) feature and deliberate omission of a | |
| 1321 | +[autosync] feature and deliberate omission of a | |
| 1224 | 1322 | [staging feature](#staging). |
| 1225 | 1323 | |
| 1226 | 1324 | The “Friday afternoon sync-up” case is simpler, too: |
| 1227 | 1325 | |
| 1228 | 1326 | fossil remote work |
| 1229 | 1327 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -4,15 +4,19 @@ | |
| 4 | |
| 5 | Fossil shares many similarities with Git. In many cases, the |
| 6 | sub-commands are identical: [`fossil bisect`][fbis] does essentially the |
| 7 | same thing as [`git bisect`][gbis], for example. |
| 8 | |
| 9 | This document covers the cases where there is no simple 1:1 mapping, |
| 10 | usually because of intentional design differences in Fossil that prevent |
| 11 | it from working exactly like Git. We choose to explain these differences |
| 12 | rather than provide a simple “translation dictionary,” since to |
| 13 | understand the conversion, you need to know why the difference exists. |
| 14 | |
| 15 | We focus on practical command examples here, leaving discussions of the |
| 16 | philosophical underpinnings that drive these command differences to [another |
| 17 | document][fvg]. The [case studies](#cs1) do get a bit philosophical, but |
| 18 | it is with the aim of illustrating how these Fossil design differences |
| @@ -589,11 +593,12 @@ | |
| 589 | |
| 590 | 1. Alice commits to her local clone and *separately* pushes the change |
| 591 | up to the central machine C in typical Git fashion. |
| 592 | 2. Bob does the same. |
| 593 | 3. Alice says “`fossil pull`” to bring changes from C down, sees what |
| 594 | Bob did to their shared working branch, and becomes wrothful. |
| 595 | |
| 596 | We’ll get to what you do about this situation below, but for now let us |
| 597 | focus on the fact that you’ve made it easier for [forks] to occur in the |
| 598 | development history by disabling autosync. If all three machines were |
| 599 | online and syncing at the time the sequence above began, Bob would |
| @@ -674,10 +679,103 @@ | |
| 674 | branches, not just one named local branch. |
| 675 | |
| 676 | [capt]: ./cap-theorem.md |
| 677 | [rem]: /help?cmd=remote |
| 678 | |
| 679 | |
| 680 | <a id="trunk"></a> |
| 681 | ## The Main Branch Is Called "`trunk`" |
| 682 | |
| 683 | In Fossil, the default name for the main branch |
| @@ -1218,11 +1316,11 @@ | |
| 1218 | |
| 1219 | fossil ci |
| 1220 | |
| 1221 | It’s one short command for Fossil instead of three for Git — or two if |
| 1222 | you abbreviate it as “`git commit -a && git push`” — because of Fossil’s |
| 1223 | [autosync feature](#autosync) feature and deliberate omission of a |
| 1224 | [staging feature](#staging). |
| 1225 | |
| 1226 | The “Friday afternoon sync-up” case is simpler, too: |
| 1227 | |
| 1228 | fossil remote work |
| 1229 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -4,15 +4,19 @@ | |
| 4 | |
| 5 | Fossil shares many similarities with Git. In many cases, the |
| 6 | sub-commands are identical: [`fossil bisect`][fbis] does essentially the |
| 7 | same thing as [`git bisect`][gbis], for example. |
| 8 | |
| 9 | Yet, Fossil is not merely Git with a bunch of commands misspelled. If |
| 10 | that were the case, we could give you a two-column translation table |
| 11 | which would tell you how to say things like “`git reset --hard HEAD`” in |
| 12 | this funny ol’ Fossil dialect of Git and be done. The purpose of this |
| 13 | document is to cover all the cases where there is no simple 1:1 mapping, |
| 14 | usually because of intentional design differences in Fossil that prevent |
| 15 | it from working exactly like Git. We choose to explain these differences |
| 16 | since to understand the conversion, you need to know why each difference |
| 17 | exists. |
| 18 | |
| 19 | We focus on practical command examples here, leaving discussions of the |
| 20 | philosophical underpinnings that drive these command differences to [another |
| 21 | document][fvg]. The [case studies](#cs1) do get a bit philosophical, but |
| 22 | it is with the aim of illustrating how these Fossil design differences |
| @@ -589,11 +593,12 @@ | |
| 593 | |
| 594 | 1. Alice commits to her local clone and *separately* pushes the change |
| 595 | up to the central machine C in typical Git fashion. |
| 596 | 2. Bob does the same. |
| 597 | 3. Alice says “`fossil pull`” to bring changes from C down, sees what |
| 598 | Bob did to their shared working branch, and becomes most wrathful. |
| 599 | (Tsk, tsk.) |
| 600 | |
| 601 | We’ll get to what you do about this situation below, but for now let us |
| 602 | focus on the fact that you’ve made it easier for [forks] to occur in the |
| 603 | development history by disabling autosync. If all three machines were |
| 604 | online and syncing at the time the sequence above began, Bob would |
| @@ -674,10 +679,103 @@ | |
| 679 | branches, not just one named local branch. |
| 680 | |
| 681 | [capt]: ./cap-theorem.md |
| 682 | [rem]: /help?cmd=remote |
| 683 | |
| 684 | |
| 685 | <a id="reset"></a> |
| 686 | ## Resetting the Repository |
| 687 | |
| 688 | Extending from [the prior item](#syncall), you may correctly infer that |
| 689 | “[delete the project, and download a fresh copy][x1597]” has no part in |
| 690 | the Fossil Way. Ideally, you should never find yourself forced into |
| 691 | desperate measures like this:(^Parsing the output of `fossil status` is |
| 692 | usually a mistake since it relies on a potentially unstable interface. |
| 693 | We make no guarantee that there will always be a line beginning with |
| 694 | “`repo`” and that it will be separated from the repository’s file name |
| 695 | by a colon. The simplified example above is also liable to become |
| 696 | confused by whitespace in file names.) |
| 697 | |
| 698 | |
| 699 | ``` |
| 700 | $ repo=$(fossil status | grep ^repo | cut -f2 -d:) |
| 701 | $ url=$(fossil remote) |
| 702 | $ fossil close # Stop here and think if it warns you! |
| 703 | $ mv $repo ${repo}.old |
| 704 | $ fossil clone $url $repo |
| 705 | $ fossil open --force $repo |
| 706 | ``` |
| 707 | |
| 708 | What, then, should you as a Git transplant do instead when you find |
| 709 | yourself reaching for “`git reset`”? |
| 710 | |
| 711 | Since the correct answer to that depends on why you think it’s a good |
| 712 | solution to your immediate problem, we’ll take our motivating scenario |
| 713 | from the problem setup above, where we discussed Fossil’s [autosync] |
| 714 | feature. Let us further say Alice’s pique results from a belief that |
| 715 | Bob’s commit is objectively wrong-headed and should be expunged |
| 716 | henceforth. Since Fossil goes out of its way to ensure that [commits are |
| 717 | durable][wdm], it should be no further surprise that there is no easier |
| 718 | method to reset Bob’s clone in favor of Alice’s than the above sequence |
| 719 | in Fossil’s command set. Except in extreme situations, we believe that |
| 720 | sort of thing is unnecessary. |
| 721 | |
| 722 | Instead, Bob can say something like this: |
| 723 | |
| 724 | ``` |
| 725 | fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip |
| 726 | fossil up trunk |
| 727 | fossil push |
| 728 | ``` |
| 729 | |
| 730 | Unlike in Git, the “`amend`” command doesn’t modify prior committed |
| 731 | artifacts. Bob’s first command doesn’t delete anything, merely tells |
| 732 | Fossil to hide his mistake from timeline views by inserting a few new |
| 733 | records into the local repository to change how the client interprets |
| 734 | the data it finds there henceforth.(^One to change the tag marking this |
| 735 | commit’s branch name to “`MISTAKE`,” one to mark that branch as hidden, |
| 736 | and one to close it to further commits.). |
| 737 | |
| 738 | Bob’s second command switches his working directory back to the prior |
| 739 | commit on that branch. We’re presuming it was “`trunk`” for the sake of |
| 740 | the example, but it works for any parent branch name. The command works |
| 741 | because the name “`trunk`” now means something different to Fossil by |
| 742 | virtue of the first command. |
| 743 | |
| 744 | Bob’s third command pushes the changes up to the central machine to |
| 745 | inform everyone else of his amendment.(^Amendments don’t autosync in |
| 746 | Fossil because they don’t change any previous commits, allowing the |
| 747 | other clones to continue working safely with their existing commit |
| 748 | hashes.) |
| 749 | |
| 750 | In this scheme, Alice then needs to say “`fossil update trunk`” in order |
| 751 | to return her check-out’s parent commit to the previous version lest her |
| 752 | next attempted commit land atop this mistake branch. The fact that Bob |
| 753 | marked the branch as closed will prevent that from going thru, cluing |
| 754 | Alice into what she needs to do to remedy the situation, but that merely |
| 755 | shows why it’s a better workflow if Alice makes the amendment herself: |
| 756 | |
| 757 | ``` |
| 758 | fossil amend --branch MISTAKE --hide --close \ |
| 759 | -m "shunt Bob’s erroneous commit off" tip |
| 760 | fossil up trunk |
| 761 | fossil push |
| 762 | ``` |
| 763 | |
| 764 | Then she can fire off an email listing Bob’s assorted failings and go |
| 765 | about her work. This asynchronous workflow solves the problem without |
| 766 | requiring explicit coordination with Bob. When he gets his email, he can |
| 767 | then say “`fossil up trunk`” himself, which by default will trigger an |
| 768 | autosync, pulling down Alice’s amendments and getting him back onto her |
| 769 | development track. |
| 770 | |
| 771 | Remember that [branch names need not be unique](#btnames) in Fossil. You |
| 772 | are free to reuse this “`MISTAKE`” branch name as often as you need to. |
| 773 | |
| 774 | [autosync]: #autosync |
| 775 | [x1597]: https://xkcd.com/1597/ |
| 776 | |
| 777 | |
| 778 | <a id="trunk"></a> |
| 779 | ## The Main Branch Is Called "`trunk`" |
| 780 | |
| 781 | In Fossil, the default name for the main branch |
| @@ -1218,11 +1316,11 @@ | |
| 1316 | |
| 1317 | fossil ci |
| 1318 | |
| 1319 | It’s one short command for Fossil instead of three for Git — or two if |
| 1320 | you abbreviate it as “`git commit -a && git push`” — because of Fossil’s |
| 1321 | [autosync] feature and deliberate omission of a |
| 1322 | [staging feature](#staging). |
| 1323 | |
| 1324 | The “Friday afternoon sync-up” case is simpler, too: |
| 1325 | |
| 1326 | fossil remote work |
| 1327 |