Fossil SCM

Added a second case study to the gitusers.md doc: "Checking Out A Version By Date"

wyoung 2020-11-02 07:33 trunk
Commit ca909620927bc7bc5cef988e5f637146dc646747c3f76c57c169207c7c8ee930
Parent f378f5dc5bb8836…
1 file changed +134 -10
~ www/gitusers.md
M www/gitusers.md
+134 -10
--- www/gitusers.md
+++ www/gitusers.md
@@ -7,11 +7,11 @@
77
88
 Although Fossil shares many similarities with Git, there are enough
99
 differences that we can’t provide a simple “translation dictionary” for
1010
 some commands. This document is more concerned with those cases than the
1111
 simple 1:1 mappings, which you can likely find on your own. In many
12
-cases, the sub-commands are identical: `fossil bisect` does essentially
12
+cases, the sub-commands are identical: [`fossil bisect`][bis] does essentially
1313
 the same thing as `git bisect`, for example.
1414
1515
 We present this from the perspective of Git users moving to Fossil, but
1616
 it is also possible to read this document as a Fossil user who speaks
1717
 only pidgin Git, who may often have questions of the form, “Now how do I
@@ -29,10 +29,11 @@
2929
 you to understand some of the other Fossil docs better.
3030
3131
 We focus more on practical command examples here than on [the
3232
 philosophical underpinnings][fvg] that drive these differences.
3333
34
+[bis]: /help?cmd=bisect
3435
 [ffor]: https://fossil-scm.org/forum
3536
 [fvg]: ./fossil-v-git.wiki
3637
3738
3839
 <a id="mwd"></a>
@@ -411,11 +412,11 @@
411412
 [infoc]: /help?cmd=info
412413
 [infow]: /help?cmd=/info
413414
 [ocomp]: https://www.bigocheatsheet.com/
414415
 [tlc]: /help?cmd=timeline
415416
 [tlw]: /help?cmd=/timeline
416
-[up]: /help?cmd=update
417
+[up]: /help?cmd=update
417418
 [wdm]: ./fossil-v-git.wiki#durable
418419
419420
420421
 ## <a id="slcom"></a> Summary Line Convention In Commit Comments
421422
@@ -744,18 +745,141 @@
744745
745746
746747
 ----
747748
748749
749
-<a id="morigin"></a>
750
-## Multiple "origin" Servers
751
-
752
-In this final section of the document, we’ll go into a lot more detail
753
-to illustrate the points above, not just give a quick summary of this
754
-single difference.
755
-
756
-Consider a common use case at the time of this writing — during the
750
+## <a id="cvdate" name="cs1"></a> Case Study 1: Checking Out A Version By Date
751
+
752
+Let’s get into something a bit more complicated: a case study showing
753
+how the concepts lined out above cause Fossil to materially differ in
754
+day-to-day operation from Git.
755
+
756
+A common thing to need to do in a version control system is to check out
757
+a version by date. Perhaps this is because your customer gave you a
758
+vague bug report — “I think it broke on a Wednesday… Yes, there was a
759
+full moon, and the Dodgers were playing in Boston…” — or perhaps you’re
760
+poking semi-randomly through history to find a “good” version to set up
761
+a [`bisect`][bis] operation.
762
+
763
+Because Git doesn’t maintain comprehensive lookup tables into its log —
764
+[as detailed above](#log) — you will find pages online recommending
765
+horrorshow commands like this:
766
+
767
+ git checkout $(git rev-list -n 1 --first-parent --before="2020-04-12" master)
768
+
769
+That’s [the top answer on Stack Overflow][gcod] for the first hit on
770
+“git checkout by date” in the web search engine I used.
771
+
772
+We believe you get such answers for requests for help with Git in part
773
+because of its lack of an always-up-to-date index into its log and in
774
+part because of its “small tools loosely joined” design philosophy. This
775
+sort of command is therefore composed piece by piece:
776
+
777
+<center>◆  ◆  ◆</center>
778
+
779
+**Given:** Git lacks a reliable lookup-by-date index into its log.
780
+
781
+**Goal:** Find the commit ID nearest a given date, you poor sod.
782
+
783
+“Oh, I know, I’ll search the rev-list, which outputs commit IDs by
784
+parsing the log backwards from `HEAD`! Easy!”
785
+
786
+ git rev-list --before=2020-04-12
787
+
788
+“Blast! Forgot the commit ID!”
789
+
790
+ git rev-list --before=2020-04-12 master
791
+
792
+“Double blast! It just spammed my terminal with revision IDs! I need to
793
+limit it to the single closest match:
794
+
795
+ git rev-list -n 1 --before=2020-04-12 master
796
+
797
+“Okay, it gives me a single revision ID now, but is it what I’m after?
798
+Let’s take a look…”
799
+
800
+ git show $(git rev-list -n 1 --before=2020-04-12 master)
801
+
802
+“Um… Why does it give me a commit from 2019-12-15? Maybe that was when
803
+it was committed on another branch, and I’m seeing a merge-commit made
804
+months later? Off to search the web… Okay, it says I need to give the
805
+`--no-merges` flag to show only regular commits, not merge-commits:”
806
+
807
+ git show $(git rev-list -n 1 --no-merges --before=2020-04-12 master)
808
+
809
+“Well poop: it shows the same commit! Eff it; let’s just try it and hope
810
+it’s close enough.”
811
+
812
+ git checkout $(git rev-list -n 1 --no-merges --before=2020-04-12 master)
813
+
814
+“Success! Just so easy!”
815
+
816
+<center>◆  ◆  ◆</center>
817
+
818
+This vignette is meant to explain some of Git’s popularity: it rewards
819
+the sort of people who enjoy puzzles, many of whom are software
820
+developers and thus need a tool like Git. Too bad if you’re just a
821
+normal user.
822
+
823
+And too bad if you’re a Windows user who doesn’t want to use [Git
824
+Bash][gbash], since neither of the stock OS command shells have a
825
+command interpolation feature needed to run that horrid command.
826
+
827
+(By the way, if you think the bit about “a commit from 2019-12-15” in my
828
+little story above is made up, try `git rev-parse master@{2020-04-12}`
829
+on [Git’s own repository][gitgh]: it gives [this commit][grpgh]! Oddly,
830
+GitHub shows the date we asked for, unlike the `git show` command above.
831
+It’s success, of a sort, though it leaves us wondering why there’s a
832
+discrepancy.)
833
+
834
+But hark! The same Stack Overflow answer gives a much simpler
835
+alternative based on Git’s [`rev-parse` feature][grp]:
836
+
837
+ git checkout master@{2020-04-12}
838
+
839
+It’s a bit cryptic, but it’s much nicer than the prior command.
840
+
841
+Too bad it only works if the target commit is in Git’s [reflog], which
842
+Git automatically prunes to 90 days of history from time to time. But
843
+the above command won’t fail outright if the reflog can’t resolve the
844
+given date, it will instead give an *incorrect* result on `stdout`,
845
+*possibly* accompanied by a warning on *stderr!* While I was writing
846
+this, it happily gave me a commit from 2019-07-19 until I nuked the
847
+repository and re-cloned, after which it at least warned me that the
848
+reflog didn’t go back that far… But it still gave me an answer: a wrong
849
+one!
850
+
851
+Why? Because Git lacks comprehensive up-to-date indices into its log.
852
+When I nuked my clone and re-cloned, I also nuked my stale reflog, so my
853
+command above started giving me today’s latest commit, that being as far
854
+back in history as it could dig. Who wants this behavior?
855
+
856
+Well, at least it works on Windows! That’s something!
857
+
858
+But woe betide you if you leave off the `master` bit. Or forget some bit
859
+of the cryptic punctuation.
860
+
861
+You may be asking with an exasperated huff, “What is your *point*, man?”
862
+The point is that the equivalent in Fossil is simply:
863
+
864
+ fossil up 2020-04-12
865
+
866
+…and the commit will *always* be from the 12th of April, 2020, no matter
867
+whether it’s a fresh clone or an ancient one, praise be Ritchie!
868
+
869
+[gbash]: https://appuals.com/what-is-git-bash/
870
+[gcod]: https://stackoverflow.com/a/6990682/142454
871
+[gitgh]: https://github.com/git/git/
872
+[grp]: https://git-scm.com/docs/git-rev-parse
873
+[grpgh]: https://github.com/git/git/commit/a99bc27aec74071aa1
874
+[reflog]: https://git-scm.com/docs/git-reflog
875
+
876
+----
877
+
878
+## <a id="morigin" name="cs2"></a> Case Study 2: Multiple "origin" Servers
879
+
880
+Now let us consider a common use case at the time of this writing — during the
757881
 COVID-19 pandemic — where you’re working from home a lot, going into the
758882
 office one part-day a week only to do things that have to be done
759883
 on-site at the office. Let us also say you have no remote
760884
 access back into the work LAN, such as because your site IT is paranoid
761885
 about security. You may still want off-machine backups of your commits
762886
--- www/gitusers.md
+++ www/gitusers.md
@@ -7,11 +7,11 @@
7
8 Although Fossil shares many similarities with Git, there are enough
9 differences that we can’t provide a simple “translation dictionary” for
10 some commands. This document is more concerned with those cases than the
11 simple 1:1 mappings, which you can likely find on your own. In many
12 cases, the sub-commands are identical: `fossil bisect` does essentially
13 the same thing as `git bisect`, for example.
14
15 We present this from the perspective of Git users moving to Fossil, but
16 it is also possible to read this document as a Fossil user who speaks
17 only pidgin Git, who may often have questions of the form, “Now how do I
@@ -29,10 +29,11 @@
29 you to understand some of the other Fossil docs better.
30
31 We focus more on practical command examples here than on [the
32 philosophical underpinnings][fvg] that drive these differences.
33
 
34 [ffor]: https://fossil-scm.org/forum
35 [fvg]: ./fossil-v-git.wiki
36
37
38 <a id="mwd"></a>
@@ -411,11 +412,11 @@
411 [infoc]: /help?cmd=info
412 [infow]: /help?cmd=/info
413 [ocomp]: https://www.bigocheatsheet.com/
414 [tlc]: /help?cmd=timeline
415 [tlw]: /help?cmd=/timeline
416 [up]: /help?cmd=update
417 [wdm]: ./fossil-v-git.wiki#durable
418
419
420 ## <a id="slcom"></a> Summary Line Convention In Commit Comments
421
@@ -744,18 +745,141 @@
744
745
746 ----
747
748
749 <a id="morigin"></a>
750 ## Multiple "origin" Servers
751
752 In this final section of the document, we’ll go into a lot more detail
753 to illustrate the points above, not just give a quick summary of this
754 single difference.
755
756 Consider a common use case at the time of this writing — during the
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
757 COVID-19 pandemic — where you’re working from home a lot, going into the
758 office one part-day a week only to do things that have to be done
759 on-site at the office. Let us also say you have no remote
760 access back into the work LAN, such as because your site IT is paranoid
761 about security. You may still want off-machine backups of your commits
762
--- www/gitusers.md
+++ www/gitusers.md
@@ -7,11 +7,11 @@
7
8 Although Fossil shares many similarities with Git, there are enough
9 differences that we can’t provide a simple “translation dictionary” for
10 some commands. This document is more concerned with those cases than the
11 simple 1:1 mappings, which you can likely find on your own. In many
12 cases, the sub-commands are identical: [`fossil bisect`][bis] does essentially
13 the same thing as `git bisect`, for example.
14
15 We present this from the perspective of Git users moving to Fossil, but
16 it is also possible to read this document as a Fossil user who speaks
17 only pidgin Git, who may often have questions of the form, “Now how do I
@@ -29,10 +29,11 @@
29 you to understand some of the other Fossil docs better.
30
31 We focus more on practical command examples here than on [the
32 philosophical underpinnings][fvg] that drive these differences.
33
34 [bis]: /help?cmd=bisect
35 [ffor]: https://fossil-scm.org/forum
36 [fvg]: ./fossil-v-git.wiki
37
38
39 <a id="mwd"></a>
@@ -411,11 +412,11 @@
412 [infoc]: /help?cmd=info
413 [infow]: /help?cmd=/info
414 [ocomp]: https://www.bigocheatsheet.com/
415 [tlc]: /help?cmd=timeline
416 [tlw]: /help?cmd=/timeline
417 [up]: /help?cmd=update
418 [wdm]: ./fossil-v-git.wiki#durable
419
420
421 ## <a id="slcom"></a> Summary Line Convention In Commit Comments
422
@@ -744,18 +745,141 @@
745
746
747 ----
748
749
750 ## <a id="cvdate" name="cs1"></a> Case Study 1: Checking Out A Version By Date
751
752 Let’s get into something a bit more complicated: a case study showing
753 how the concepts lined out above cause Fossil to materially differ in
754 day-to-day operation from Git.
755
756 A common thing to need to do in a version control system is to check out
757 a version by date. Perhaps this is because your customer gave you a
758 vague bug report — “I think it broke on a Wednesday… Yes, there was a
759 full moon, and the Dodgers were playing in Boston…” — or perhaps you’re
760 poking semi-randomly through history to find a “good” version to set up
761 a [`bisect`][bis] operation.
762
763 Because Git doesn’t maintain comprehensive lookup tables into its log —
764 [as detailed above](#log) — you will find pages online recommending
765 horrorshow commands like this:
766
767 git checkout $(git rev-list -n 1 --first-parent --before="2020-04-12" master)
768
769 That’s [the top answer on Stack Overflow][gcod] for the first hit on
770 “git checkout by date” in the web search engine I used.
771
772 We believe you get such answers for requests for help with Git in part
773 because of its lack of an always-up-to-date index into its log and in
774 part because of its “small tools loosely joined” design philosophy. This
775 sort of command is therefore composed piece by piece:
776
777 <center>◆  ◆  ◆</center>
778
779 **Given:** Git lacks a reliable lookup-by-date index into its log.
780
781 **Goal:** Find the commit ID nearest a given date, you poor sod.
782
783 “Oh, I know, I’ll search the rev-list, which outputs commit IDs by
784 parsing the log backwards from `HEAD`! Easy!”
785
786 git rev-list --before=2020-04-12
787
788 “Blast! Forgot the commit ID!”
789
790 git rev-list --before=2020-04-12 master
791
792 “Double blast! It just spammed my terminal with revision IDs! I need to
793 limit it to the single closest match:
794
795 git rev-list -n 1 --before=2020-04-12 master
796
797 “Okay, it gives me a single revision ID now, but is it what I’m after?
798 Let’s take a look…”
799
800 git show $(git rev-list -n 1 --before=2020-04-12 master)
801
802 “Um… Why does it give me a commit from 2019-12-15? Maybe that was when
803 it was committed on another branch, and I’m seeing a merge-commit made
804 months later? Off to search the web… Okay, it says I need to give the
805 `--no-merges` flag to show only regular commits, not merge-commits:”
806
807 git show $(git rev-list -n 1 --no-merges --before=2020-04-12 master)
808
809 “Well poop: it shows the same commit! Eff it; let’s just try it and hope
810 it’s close enough.”
811
812 git checkout $(git rev-list -n 1 --no-merges --before=2020-04-12 master)
813
814 “Success! Just so easy!”
815
816 <center>◆  ◆  ◆</center>
817
818 This vignette is meant to explain some of Git’s popularity: it rewards
819 the sort of people who enjoy puzzles, many of whom are software
820 developers and thus need a tool like Git. Too bad if you’re just a
821 normal user.
822
823 And too bad if you’re a Windows user who doesn’t want to use [Git
824 Bash][gbash], since neither of the stock OS command shells have a
825 command interpolation feature needed to run that horrid command.
826
827 (By the way, if you think the bit about “a commit from 2019-12-15” in my
828 little story above is made up, try `git rev-parse master@{2020-04-12}`
829 on [Git’s own repository][gitgh]: it gives [this commit][grpgh]! Oddly,
830 GitHub shows the date we asked for, unlike the `git show` command above.
831 It’s success, of a sort, though it leaves us wondering why there’s a
832 discrepancy.)
833
834 But hark! The same Stack Overflow answer gives a much simpler
835 alternative based on Git’s [`rev-parse` feature][grp]:
836
837 git checkout master@{2020-04-12}
838
839 It’s a bit cryptic, but it’s much nicer than the prior command.
840
841 Too bad it only works if the target commit is in Git’s [reflog], which
842 Git automatically prunes to 90 days of history from time to time. But
843 the above command won’t fail outright if the reflog can’t resolve the
844 given date, it will instead give an *incorrect* result on `stdout`,
845 *possibly* accompanied by a warning on *stderr!* While I was writing
846 this, it happily gave me a commit from 2019-07-19 until I nuked the
847 repository and re-cloned, after which it at least warned me that the
848 reflog didn’t go back that far… But it still gave me an answer: a wrong
849 one!
850
851 Why? Because Git lacks comprehensive up-to-date indices into its log.
852 When I nuked my clone and re-cloned, I also nuked my stale reflog, so my
853 command above started giving me today’s latest commit, that being as far
854 back in history as it could dig. Who wants this behavior?
855
856 Well, at least it works on Windows! That’s something!
857
858 But woe betide you if you leave off the `master` bit. Or forget some bit
859 of the cryptic punctuation.
860
861 You may be asking with an exasperated huff, “What is your *point*, man?”
862 The point is that the equivalent in Fossil is simply:
863
864 fossil up 2020-04-12
865
866 …and the commit will *always* be from the 12th of April, 2020, no matter
867 whether it’s a fresh clone or an ancient one, praise be Ritchie!
868
869 [gbash]: https://appuals.com/what-is-git-bash/
870 [gcod]: https://stackoverflow.com/a/6990682/142454
871 [gitgh]: https://github.com/git/git/
872 [grp]: https://git-scm.com/docs/git-rev-parse
873 [grpgh]: https://github.com/git/git/commit/a99bc27aec74071aa1
874 [reflog]: https://git-scm.com/docs/git-reflog
875
876 ----
877
878 ## <a id="morigin" name="cs2"></a> Case Study 2: Multiple "origin" Servers
879
880 Now let us consider a common use case at the time of this writing — during the
881 COVID-19 pandemic — where you’re working from home a lot, going into the
882 office one part-day a week only to do things that have to be done
883 on-site at the office. Let us also say you have no remote
884 access back into the work LAN, such as because your site IT is paranoid
885 about security. You may still want off-machine backups of your commits
886

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button