Fossil SCM
Merge fixes from trunk
Commit
3f2365fe2648055e1f6b05c16e4c6a3cc7a1d9f66943982816ce26c872f37f4a
Parent
9a17e76ebf6eb60…
3 files changed
+1
-1
+1
+75
-38
+1
-1
| --- src/login.c | ||
| +++ src/login.c | ||
| @@ -1051,11 +1051,11 @@ | ||
| 1051 | 1051 | } |
| 1052 | 1052 | if( zUser==0 ){ |
| 1053 | 1053 | /* Invalid cookie */ |
| 1054 | 1054 | }else if( fossil_strcmp(zUser, "anonymous")==0 ){ |
| 1055 | 1055 | /* Cookies of the form "HASH/TIME/anonymous". The TIME must not be |
| 1056 | - ** too old and the sha1 hash of TIME/IPADDR/SECRET must match HASH. | |
| 1056 | + ** too old and the sha1 hash of TIME/SECRET must match HASH. | |
| 1057 | 1057 | ** SECRET is the "captcha-secret" value in the repository. |
| 1058 | 1058 | */ |
| 1059 | 1059 | double rTime = atof(zArg); |
| 1060 | 1060 | Blob b; |
| 1061 | 1061 | blob_zero(&b); |
| 1062 | 1062 |
| --- src/login.c | |
| +++ src/login.c | |
| @@ -1051,11 +1051,11 @@ | |
| 1051 | } |
| 1052 | if( zUser==0 ){ |
| 1053 | /* Invalid cookie */ |
| 1054 | }else if( fossil_strcmp(zUser, "anonymous")==0 ){ |
| 1055 | /* Cookies of the form "HASH/TIME/anonymous". The TIME must not be |
| 1056 | ** too old and the sha1 hash of TIME/IPADDR/SECRET must match HASH. |
| 1057 | ** SECRET is the "captcha-secret" value in the repository. |
| 1058 | */ |
| 1059 | double rTime = atof(zArg); |
| 1060 | Blob b; |
| 1061 | blob_zero(&b); |
| 1062 |
| --- src/login.c | |
| +++ src/login.c | |
| @@ -1051,11 +1051,11 @@ | |
| 1051 | } |
| 1052 | if( zUser==0 ){ |
| 1053 | /* Invalid cookie */ |
| 1054 | }else if( fossil_strcmp(zUser, "anonymous")==0 ){ |
| 1055 | /* Cookies of the form "HASH/TIME/anonymous". The TIME must not be |
| 1056 | ** too old and the sha1 hash of TIME/SECRET must match HASH. |
| 1057 | ** SECRET is the "captcha-secret" value in the repository. |
| 1058 | */ |
| 1059 | double rTime = atof(zArg); |
| 1060 | Blob b; |
| 1061 | blob_zero(&b); |
| 1062 |
+1
| --- src/th_lang.c | ||
| +++ src/th_lang.c | ||
| @@ -257,10 +257,11 @@ | ||
| 257 | 257 | |
| 258 | 258 | for(i=2; i<argc; i++){ |
| 259 | 259 | Th_ListAppend(interp, &zList, &nList, argv[i], argl[i]); |
| 260 | 260 | } |
| 261 | 261 | |
| 262 | + Th_SetVar(interp, argv[1], argl[1], zList, nList); | |
| 262 | 263 | Th_SetResult(interp, zList, nList); |
| 263 | 264 | Th_Free(interp, zList); |
| 264 | 265 | |
| 265 | 266 | return TH_OK; |
| 266 | 267 | } |
| 267 | 268 |
| --- src/th_lang.c | |
| +++ src/th_lang.c | |
| @@ -257,10 +257,11 @@ | |
| 257 | |
| 258 | for(i=2; i<argc; i++){ |
| 259 | Th_ListAppend(interp, &zList, &nList, argv[i], argl[i]); |
| 260 | } |
| 261 | |
| 262 | Th_SetResult(interp, zList, nList); |
| 263 | Th_Free(interp, zList); |
| 264 | |
| 265 | return TH_OK; |
| 266 | } |
| 267 |
| --- src/th_lang.c | |
| +++ src/th_lang.c | |
| @@ -257,10 +257,11 @@ | |
| 257 | |
| 258 | for(i=2; i<argc; i++){ |
| 259 | Th_ListAppend(interp, &zList, &nList, argv[i], argl[i]); |
| 260 | } |
| 261 | |
| 262 | Th_SetVar(interp, argv[1], argl[1], zList, nList); |
| 263 | Th_SetResult(interp, zList, nList); |
| 264 | Th_Free(interp, zList); |
| 265 | |
| 266 | return TH_OK; |
| 267 | } |
| 268 |
+75
-38
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -113,19 +113,19 @@ | ||
| 113 | 113 | |
| 114 | 114 | Someone coming from the Git perspective may perceive that `fossil up` |
| 115 | 115 | has two purposes: |
| 116 | 116 | |
| 117 | 117 | * Without the optional `VERSION` argument, it updates the working |
| 118 | - checkout to the tip of the current branch, like `git pull`. | |
| 118 | + checkout to the tip of the current branch, as `git pull` does. | |
| 119 | 119 | |
| 120 | 120 | * Given a `VERSION` argument, it updates to the named version. If that’s the |
| 121 | - name of a branch, it updates to the tip of that branch rather than | |
| 122 | - the current one, like `git checkout BRANCH`. | |
| 121 | + name of a branch, it updates to the *tip* of that branch, as | |
| 122 | + `git checkout BRANCH` does. | |
| 123 | 123 | |
| 124 | 124 | In fact, these are the same operation, so they’re the same command in |
| 125 | 125 | Fossil. The first form simply allows the `VERSION` to be implicit: the |
| 126 | -current branch. | |
| 126 | +tip of the current branch. | |
| 127 | 127 | |
| 128 | 128 | We think this is a more sensible command design than `git pull` vs |
| 129 | 129 | `git checkout`. ([…vs `git checkout` vs `git checkout`!][gcokoan]) |
| 130 | 130 | |
| 131 | 131 | [fpull]: /help?cmd=pull |
| @@ -144,10 +144,11 @@ | ||
| 144 | 144 | |
| 145 | 145 | This author uses a scheme like the following on mobile machines that |
| 146 | 146 | shuttle between home and the office: |
| 147 | 147 | |
| 148 | 148 | ``` pikchr toggle indent |
| 149 | +scale=0.8 | |
| 149 | 150 | box "~/museum/" fit |
| 150 | 151 | move right 0.1 |
| 151 | 152 | line right dotted |
| 152 | 153 | move right 0.05 |
| 153 | 154 | box invis "where one stores valuable fossils" ljust |
| @@ -176,20 +177,22 @@ | ||
| 176 | 177 | |
| 177 | 178 | On a Windows box, you might instead choose "`C:\Fossils`" |
| 178 | 179 | and do without the subdirectory scheme, for example. |
| 179 | 180 | |
| 180 | 181 | |
| 181 | -#### <a id="close" name="dotfile"></a> Closing A Check-Out | |
| 182 | +#### <a id="close" name="dotfile"></a> Closing a Check-Out | |
| 182 | 183 | |
| 183 | 184 | The [`fossil close`][close] command dissociates a check-out directory from the |
| 184 | -Fossil repository database, nondestructively inverting [`fossil open`][open]. It | |
| 185 | -won’t remove the managed files, and unless you give the `--force` | |
| 185 | +Fossil repository database, nondestructively inverting [`fossil open`][open]. | |
| 186 | +(Contrast [its closest inverse](#worktree), `git worktree remove`, which *is* | |
| 187 | +destructive in Git!) This Fossil command does not | |
| 188 | +remove the managed files, and unless you give the `--force` | |
| 186 | 189 | option, it won’t let you close the check-out with uncommitted changes to |
| 187 | 190 | those managed files. |
| 188 | 191 | |
| 189 | -The `close` command refuses to run without `--force` when you have | |
| 190 | -certain precious per-checkout data, which Fossil stores in the | |
| 192 | +The `close` command also refuses to run without `--force` when you have | |
| 193 | +certain other precious per-checkout data that Fossil stores in the | |
| 191 | 194 | `.fslckout` file at the root of a check-out directory. This is a SQLite |
| 192 | 195 | database that keeps track of local state such as what version you have |
| 193 | 196 | checked out, the contents of the [stash] for that working directory, the |
| 194 | 197 | [undo] buffers, per-checkout [settings][set], and so forth. The stash |
| 195 | 198 | and undo buffers are considered precious uncommitted changes, |
| @@ -226,20 +229,27 @@ | ||
| 226 | 229 | |
| 227 | 230 | The symlink trick has a number of problems, the largest being that |
| 228 | 231 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 229 | 232 | 10 Creators Update was released in spring of 2017, you had to be an |
| 230 | 233 | Administrator to use the feature besides. ([Source][wsyml]) Git solved |
| 231 | -this problem two years earlier with the `git-worktree` command in Git | |
| 232 | -2.5: | |
| 234 | +this problem back when Windows XP was Microsoft’s current offering | |
| 235 | +with the `git-worktree` command, added in Git 2.5: | |
| 233 | 236 | |
| 234 | 237 | git worktree add ../foo-branch foo-branch |
| 235 | 238 | cd ../foo-branch |
| 236 | 239 | |
| 237 | 240 | That is approximately equivalent to this in Fossil: |
| 238 | 241 | |
| 239 | 242 | mkdir ../foo-branch |
| 243 | + cd ../foo-branch | |
| 240 | 244 | fossil open /path/to/repo.fossil foo-branch |
| 245 | + | |
| 246 | +The Fossil alternative is wordier, but this tends to be one-time setup, | |
| 247 | +not something you do everyday. This author keeps a “scratch” checkout | |
| 248 | +for cases where is isn’t appropriate to reuse the “trunk” checkout. The | |
| 249 | +other peer checkouts therefore tend to track long-lived branches, so | |
| 250 | +they rarely change once a development machine is set up. | |
| 241 | 251 | |
| 242 | 252 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 243 | 253 | check-out](#close): |
| 244 | 254 | |
| 245 | 255 | git worktree remove . |
| @@ -340,13 +350,13 @@ | ||
| 340 | 350 | reads from a single disk file rather than visit potentially many |
| 341 | 351 | files in sequence as Git must, so the OS’s buffer cache can result in |
| 342 | 352 | [still better performance][35pct]. |
| 343 | 353 | |
| 344 | 354 | Unlike Git’s log, Fossil’s timeline shows info across branches by |
| 345 | -default, a feature for maintaining better situational awareness. The | |
| 355 | +default, a feature for maintaining better situational awareness. Although the | |
| 346 | 356 | `fossil timeline` command has no way to show a single branch’s commits, |
| 347 | -but you can restrict your view like this using the web UI equivalent by | |
| 357 | +you can restrict your view like this using the web UI equivalent by | |
| 348 | 358 | clicking the name of a branch on the `/timeline` or `/brlist` page. (Or |
| 349 | 359 | manually, by adding the `r=` query parameter.) Note that even in this |
| 350 | 360 | case, the Fossil timeline still shows other branches where they interact |
| 351 | 361 | with the one you’ve referenced in this way; again, better situational |
| 352 | 362 | awareness. |
| @@ -507,10 +517,13 @@ | ||
| 507 | 517 | If you only want to commit _some_ of the changes, list the names |
| 508 | 518 | of the files or directories you want to commit as arguments, like this: |
| 509 | 519 | |
| 510 | 520 | fossil commit src/feature.c doc/feature.md examples/feature |
| 511 | 521 | |
| 522 | +Note that the last element is a directory name, meaning “any changed | |
| 523 | +file under the `examples/feature` directory.” | |
| 524 | + | |
| 512 | 525 | Although there are currently no |
| 513 | 526 | <a id="csplit"></a>[commit splitting][gcspl] features in Fossil like |
| 514 | 527 | `git add -p`, `git commit -p`, or `git rebase -i`, you can get the same |
| 515 | 528 | effect by converting an uncommitted change set to a patch and then |
| 516 | 529 | running it through [Patchouli]. |
| @@ -550,43 +563,56 @@ | ||
| 550 | 563 | [gcspl]: https://git-scm.com/docs/git-rebase#_splitting_commits |
| 551 | 564 | [Patchouli]: https://pypi.org/project/patchouli/ |
| 552 | 565 | |
| 553 | 566 | |
| 554 | 567 | <a id="bneed"></a> |
| 555 | -## Create Branches At Point Of Need, Rather Than Ahead of Need | |
| 568 | +## Create Branches at Point of Need, Rather Than Ahead of Need | |
| 556 | 569 | |
| 557 | 570 | Fossil prefers that you create new branches as part of the first commit |
| 558 | 571 | on that branch: |
| 559 | 572 | |
| 560 | - fossil commit --branch my-new-branch | |
| 573 | + fossil commit --branch my-branch | |
| 561 | 574 | |
| 562 | 575 | If that commit is successful, your local check-out directory is then |
| 563 | 576 | switched to the tip of that branch, so subsequent commits don’t need the |
| 564 | 577 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 565 | 578 | adding commits to the tip of that branch. |
| 566 | 579 | |
| 567 | 580 | To switch back to the parent branch, say something like: |
| 568 | 581 | |
| 569 | - fossil update trunk # ≅ git checkout master | |
| 582 | + fossil update trunk | |
| 583 | + | |
| 584 | +(This is approximately equivalent to `git checkout master`.) | |
| 570 | 585 | |
| 571 | 586 | Fossil does also support the Git style, creating the branch ahead of |
| 572 | 587 | need: |
| 573 | 588 | |
| 574 | - fossil branch new my-new-branch | |
| 575 | - fossil update my-new-branch | |
| 589 | + fossil branch new my-branch | |
| 590 | + fossil up my-branch | |
| 576 | 591 | ...work on first commit... |
| 577 | 592 | fossil commit |
| 578 | 593 | |
| 579 | -This is more verbose, but it has the same effect: put the first commit | |
| 580 | -onto `my-new-branch` and switch the check-out directory to that branch so | |
| 581 | -subsequent commits are descendants of that initial branch commit. | |
| 594 | +This is more verbose, giving the same overall effect though the initial | |
| 595 | +actions are inverted: create a new branch for the first commit, switch | |
| 596 | +the check-out directory to that branch, and make that first commit. As | |
| 597 | +above, subsequent commits are descendants of that initial branch commit. | |
| 598 | +We think you’ll agree that creating a branch as part of the initial | |
| 599 | +commit is simpler. | |
| 582 | 600 | |
| 583 | 601 | Fossil also allows you to move a check-in to a different branch |
| 584 | 602 | *after* you commit it, using the "`fossil amend`" command. |
| 585 | 603 | For example: |
| 586 | 604 | |
| 587 | - fossil amend current --branch my-new-branch | |
| 605 | + fossil amend current --branch my-branch | |
| 606 | + | |
| 607 | +This works by inserting a tag into the repository that causes the web UI | |
| 608 | +to relabel commits from that point forward with the new name. Like Git, | |
| 609 | +Fossil’s fundamental data structure is the interlinked DAG of commit | |
| 610 | +hashes; branch names are supplemental data for making it easier for the | |
| 611 | +humans to understand this DAG, so this command does not change the core | |
| 612 | +history of the project, only annotate it for better display to the | |
| 613 | +humans. | |
| 588 | 614 | |
| 589 | 615 | (The version string “current” is one of the [special check-in names][scin] in Fossil. See |
| 590 | 616 | that document for the many other names you can give to “`amend`”, or |
| 591 | 617 | indeed to any other Fossil command documented to accept a `VERSION` or |
| 592 | 618 | `NAME` string.) |
| @@ -613,11 +639,11 @@ | ||
| 613 | 639 | This provides most of the advantages of a centralized version control |
| 614 | 640 | system while retaining the advantages of distributed version control: |
| 615 | 641 | |
| 616 | 642 | 1. Your work stays synced up with your coworkers’ efforts as long as your |
| 617 | 643 | machine can connect to the remote repository. At need, you can go |
| 618 | - off-network and continue work atop the last version you sync’d with | |
| 644 | + off-network and continue work atop the last version you synced with | |
| 619 | 645 | the remote. |
| 620 | 646 | |
| 621 | 647 | 2. It provides immediate off-machine backup of your commits. Unlike |
| 622 | 648 | centralized version control, though, you can still work while |
| 623 | 649 | disconnected; your changes will sync up with the remote once you get |
| @@ -639,11 +665,11 @@ | ||
| 639 | 665 | [setup]: ./caps/admin-v-setup.md#apsu |
| 640 | 666 | [wflow]: ./concepts.wiki#workflow |
| 641 | 667 | |
| 642 | 668 | |
| 643 | 669 | <a id="syncall"></a> |
| 644 | -## Sync Is All-Or-Nothing | |
| 670 | +## Sync Is All-or-Nothing | |
| 645 | 671 | |
| 646 | 672 | Fossil does not support the concept of syncing, pushing, or pulling |
| 647 | 673 | individual branches. When you sync/push/pull in Fossil, it |
| 648 | 674 | processes all artifacts in its hash tree: |
| 649 | 675 | branches, tags, wiki articles, tickets, forum posts, technotes… |
| @@ -711,11 +737,11 @@ | ||
| 711 | 737 | come up with a new objection that we haven’t already considered and |
| 712 | 738 | addressed there. |
| 713 | 739 | |
| 714 | 740 | There is only one sub-feature of `git rebase` that is philosophically |
| 715 | 741 | compatible with Fossil yet which currently has no functional equivalent. |
| 716 | -We cover [this and the workaround for it](#csplit) above. | |
| 742 | +We [covered this and the workaround for its lack](#csplit) above. | |
| 717 | 743 | |
| 718 | 744 | [3]: ./rebaseharm.md |
| 719 | 745 | |
| 720 | 746 | |
| 721 | 747 | ## <a id="cdiff"></a> Colorized Diffs |
| @@ -733,11 +759,12 @@ | ||
| 733 | 759 | |
| 734 | 760 | fossil set --global diff-command 'colordiff -wu' |
| 735 | 761 | |
| 736 | 762 | Because this is unconditional, unlike `git diff --color=auto`, you will |
| 737 | 763 | then have to remember to add the `-i` option to `fossil diff` commands |
| 738 | -when you want color disabled, such as when piping diff output to another | |
| 764 | +when you want color disabled, such as when producing `patch(1)` files | |
| 765 | +or piping diff output to another | |
| 739 | 766 | command that doesn’t understand ANSI escape sequences. There’s an |
| 740 | 767 | example of this [below](#dstat). |
| 741 | 768 | |
| 742 | 769 | Another way, which avoids this problem, is to say instead: |
| 743 | 770 | |
| @@ -750,14 +777,14 @@ | ||
| 750 | 777 | |
| 751 | 778 | |
| 752 | 779 | ## <a id="show"></a> Showing Information About Commits |
| 753 | 780 | |
| 754 | 781 | While there is no direct equivalent to Git’s “`show`” command, similar |
| 755 | -functionality may be present in Fossil under other commands: | |
| 782 | +functionality is present in Fossil under other commands: | |
| 756 | 783 | |
| 757 | 784 | |
| 758 | -#### <a id="patch"></a> Show A Patch For A Commit | |
| 785 | +#### <a id="patch"></a> Show a Patch for a Commit | |
| 759 | 786 | |
| 760 | 787 | git show -p COMMIT_ID |
| 761 | 788 | |
| 762 | 789 | …gives much the same output as |
| 763 | 790 | |
| @@ -769,20 +796,24 @@ | ||
| 769 | 796 | |
| 770 | 797 | You can use any of [Fossil’s special check-in names][scin] in place of |
| 771 | 798 | the `COMMIT_ID` in this and later examples. Fossil docs usually say |
| 772 | 799 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 773 | 800 | or name might not refer to a commit ID, but instead to a forum post, a |
| 774 | -wiki document, etc. The following command answers the question “What did | |
| 801 | +wiki document, etc. For instance, the following command answers the question “What did | |
| 775 | 802 | I just commit?” |
| 776 | 803 | |
| 777 | 804 | fossil diff --checkin tip |
| 805 | + | |
| 806 | +…or equivalently using a different symbolic commit name: | |
| 807 | + | |
| 808 | + fossil diff --from prev | |
| 778 | 809 | |
| 779 | 810 | [devorg]: ./fossil-v-git.wiki#devorg |
| 780 | 811 | [LKML]: https://lkml.org/ |
| 781 | 812 | |
| 782 | 813 | |
| 783 | -#### <a id="cmsg"></a> Show A Specific Commit Message | |
| 814 | +#### <a id="cmsg"></a> Show a Specific Commit Message | |
| 784 | 815 | |
| 785 | 816 | git show -s COMMIT_ID |
| 786 | 817 | |
| 787 | 818 | |
| 788 | 819 | …is |
| @@ -890,18 +921,18 @@ | ||
| 890 | 921 | |
| 891 | 922 | |
| 892 | 923 | ---- |
| 893 | 924 | |
| 894 | 925 | |
| 895 | -## <a id="cvdate" name="cs1"></a> Case Study 1: Checking Out A Version By Date | |
| 926 | +## <a id="cvdate" name="cs1"></a> Case Study 1: Checking Out a Version by Date | |
| 896 | 927 | |
| 897 | 928 | Let’s get into something a bit more complicated: a case study showing |
| 898 | 929 | how the concepts lined out above cause Fossil to materially differ in |
| 899 | 930 | day-to-day operation from Git. |
| 900 | 931 | |
| 901 | 932 | Why would you want to check out a version of a project by date? Perhaps |
| 902 | -because your customer gave you a vague bug report referencing only a | |
| 933 | +your customer gave you a vague bug report referencing only a | |
| 903 | 934 | date rather than a version. Or, you may be poking semi-randomly through |
| 904 | 935 | history to find a “good” version to anchor the start point of a |
| 905 | 936 | [`fossil bisect`][fbis] operation. |
| 906 | 937 | |
| 907 | 938 | My search engine’s first result for “git checkout by date” is [this |
| @@ -917,12 +948,12 @@ | ||
| 917 | 948 | means something else. You cannot simplify the cryptic incantation in |
| 918 | 949 | the typical use case. |
| 919 | 950 | |
| 920 | 951 | 2. A date string in Git without a time will be interpreted as |
| 921 | 952 | “[at the local wall clock time on the given date][gapxd],” so the |
| 922 | - command means something different from one second to the next. This | |
| 923 | - can be a problem if there are multiple commits on that date, because | |
| 953 | + command means something different from one second to the next! This | |
| 954 | + can be a serious problem if there are multiple commits on that date, because | |
| 924 | 955 | the command will give different results depending on the time of |
| 925 | 956 | day you run it. |
| 926 | 957 | |
| 927 | 958 | 3. It gives misleading output if there is no close match for the date |
| 928 | 959 | in the local [reflog]. It starts out empty after a fresh clone, and |
| @@ -940,11 +971,11 @@ | ||
| 940 | 971 | date value you give. |
| 941 | 972 | |
| 942 | 973 | Git tries its best, but because it’s working from a purgeable and |
| 943 | 974 | possibly-stale local cache, you cannot trust its results. |
| 944 | 975 | |
| 945 | -We cannot recommend this command at all. It’s unreliable even in the | |
| 976 | +Consequently, we cannot recommend this command at all. It’s unreliable even in the | |
| 946 | 977 | best case. |
| 947 | 978 | |
| 948 | 979 | That same Stack Overflow answer therefore goes on to recommend an |
| 949 | 980 | entirely different command: |
| 950 | 981 | |
| @@ -1020,11 +1051,11 @@ | ||
| 1020 | 1051 | then maintain that index through subsequent commits and syncs. |
| 1021 | 1052 | |
| 1022 | 1053 | * Use an indexed SQL `ORDER BY` query to match timestamps to commit |
| 1023 | 1054 | IDs for a fast and consistent result. |
| 1024 | 1055 | |
| 1025 | -* Round timestamp strings up using [rules][frud] consistent across | |
| 1056 | +* Round incomplete timestamp strings up using [rules][frud] consistent across | |
| 1026 | 1057 | computers and local time of day. |
| 1027 | 1058 | |
| 1028 | 1059 | [frud]: https://fossil-scm.org/home/file/src/name.c?ci=d2a59b03727bc3&ln=122-141 |
| 1029 | 1060 | [gbash]: https://appuals.com/what-is-git-bash/ |
| 1030 | 1061 | [gapxd]: https://github.com/git/git/blob/7f7ebe054a/date.c#L1298-L1300 |
| @@ -1195,13 +1226,19 @@ | ||
| 1195 | 1226 | The “Friday afternoon sync-up” case is simpler, too: |
| 1196 | 1227 | |
| 1197 | 1228 | fossil remote work |
| 1198 | 1229 | fossil sync |
| 1199 | 1230 | |
| 1200 | -Back at home, it’s simpler still: we can do away with the second command, | |
| 1231 | +Back at home, it’s simpler still: we may be able to do away with the second command, | |
| 1201 | 1232 | saying just “`fossil remote home`” because the sync will happen as part |
| 1202 | -of the next commit, thanks once again to Fossil’s autosync feature. | |
| 1233 | +of the next commit, thanks once again to Fossil’s autosync feature. If | |
| 1234 | +the working branch now has commits from other developers after syncing | |
| 1235 | +with the central repository, though, you’ll want to say “`fossil up`” to | |
| 1236 | +avoid creating an inadvertent fork in the branch. | |
| 1237 | + | |
| 1238 | +(Which is easy to fix if it occurs: `fossil merge` without arguments | |
| 1239 | +means “merge open tips on the current branch.”) | |
| 1203 | 1240 | |
| 1204 | 1241 | [grsync]: https://stackoverflow.com/q/1398018/142454 |
| 1205 | 1242 | [qs]: ./quickstart.wiki |
| 1206 | 1243 | [shwmd]: ./fossil-v-git.wiki#checkouts |
| 1207 | 1244 | [sn]: https://en.wikipedia.org/wiki/Sneakernet |
| 1208 | 1245 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -113,19 +113,19 @@ | |
| 113 | |
| 114 | Someone coming from the Git perspective may perceive that `fossil up` |
| 115 | has two purposes: |
| 116 | |
| 117 | * Without the optional `VERSION` argument, it updates the working |
| 118 | checkout to the tip of the current branch, like `git pull`. |
| 119 | |
| 120 | * Given a `VERSION` argument, it updates to the named version. If that’s the |
| 121 | name of a branch, it updates to the tip of that branch rather than |
| 122 | the current one, like `git checkout BRANCH`. |
| 123 | |
| 124 | In fact, these are the same operation, so they’re the same command in |
| 125 | Fossil. The first form simply allows the `VERSION` to be implicit: the |
| 126 | current branch. |
| 127 | |
| 128 | We think this is a more sensible command design than `git pull` vs |
| 129 | `git checkout`. ([…vs `git checkout` vs `git checkout`!][gcokoan]) |
| 130 | |
| 131 | [fpull]: /help?cmd=pull |
| @@ -144,10 +144,11 @@ | |
| 144 | |
| 145 | This author uses a scheme like the following on mobile machines that |
| 146 | shuttle between home and the office: |
| 147 | |
| 148 | ``` pikchr toggle indent |
| 149 | box "~/museum/" fit |
| 150 | move right 0.1 |
| 151 | line right dotted |
| 152 | move right 0.05 |
| 153 | box invis "where one stores valuable fossils" ljust |
| @@ -176,20 +177,22 @@ | |
| 176 | |
| 177 | On a Windows box, you might instead choose "`C:\Fossils`" |
| 178 | and do without the subdirectory scheme, for example. |
| 179 | |
| 180 | |
| 181 | #### <a id="close" name="dotfile"></a> Closing A Check-Out |
| 182 | |
| 183 | The [`fossil close`][close] command dissociates a check-out directory from the |
| 184 | Fossil repository database, nondestructively inverting [`fossil open`][open]. It |
| 185 | won’t remove the managed files, and unless you give the `--force` |
| 186 | option, it won’t let you close the check-out with uncommitted changes to |
| 187 | those managed files. |
| 188 | |
| 189 | The `close` command refuses to run without `--force` when you have |
| 190 | certain precious per-checkout data, which Fossil stores in the |
| 191 | `.fslckout` file at the root of a check-out directory. This is a SQLite |
| 192 | database that keeps track of local state such as what version you have |
| 193 | checked out, the contents of the [stash] for that working directory, the |
| 194 | [undo] buffers, per-checkout [settings][set], and so forth. The stash |
| 195 | and undo buffers are considered precious uncommitted changes, |
| @@ -226,20 +229,27 @@ | |
| 226 | |
| 227 | The symlink trick has a number of problems, the largest being that |
| 228 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 229 | 10 Creators Update was released in spring of 2017, you had to be an |
| 230 | Administrator to use the feature besides. ([Source][wsyml]) Git solved |
| 231 | this problem two years earlier with the `git-worktree` command in Git |
| 232 | 2.5: |
| 233 | |
| 234 | git worktree add ../foo-branch foo-branch |
| 235 | cd ../foo-branch |
| 236 | |
| 237 | That is approximately equivalent to this in Fossil: |
| 238 | |
| 239 | mkdir ../foo-branch |
| 240 | fossil open /path/to/repo.fossil foo-branch |
| 241 | |
| 242 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 243 | check-out](#close): |
| 244 | |
| 245 | git worktree remove . |
| @@ -340,13 +350,13 @@ | |
| 340 | reads from a single disk file rather than visit potentially many |
| 341 | files in sequence as Git must, so the OS’s buffer cache can result in |
| 342 | [still better performance][35pct]. |
| 343 | |
| 344 | Unlike Git’s log, Fossil’s timeline shows info across branches by |
| 345 | default, a feature for maintaining better situational awareness. The |
| 346 | `fossil timeline` command has no way to show a single branch’s commits, |
| 347 | but you can restrict your view like this using the web UI equivalent by |
| 348 | clicking the name of a branch on the `/timeline` or `/brlist` page. (Or |
| 349 | manually, by adding the `r=` query parameter.) Note that even in this |
| 350 | case, the Fossil timeline still shows other branches where they interact |
| 351 | with the one you’ve referenced in this way; again, better situational |
| 352 | awareness. |
| @@ -507,10 +517,13 @@ | |
| 507 | If you only want to commit _some_ of the changes, list the names |
| 508 | of the files or directories you want to commit as arguments, like this: |
| 509 | |
| 510 | fossil commit src/feature.c doc/feature.md examples/feature |
| 511 | |
| 512 | Although there are currently no |
| 513 | <a id="csplit"></a>[commit splitting][gcspl] features in Fossil like |
| 514 | `git add -p`, `git commit -p`, or `git rebase -i`, you can get the same |
| 515 | effect by converting an uncommitted change set to a patch and then |
| 516 | running it through [Patchouli]. |
| @@ -550,43 +563,56 @@ | |
| 550 | [gcspl]: https://git-scm.com/docs/git-rebase#_splitting_commits |
| 551 | [Patchouli]: https://pypi.org/project/patchouli/ |
| 552 | |
| 553 | |
| 554 | <a id="bneed"></a> |
| 555 | ## Create Branches At Point Of Need, Rather Than Ahead of Need |
| 556 | |
| 557 | Fossil prefers that you create new branches as part of the first commit |
| 558 | on that branch: |
| 559 | |
| 560 | fossil commit --branch my-new-branch |
| 561 | |
| 562 | If that commit is successful, your local check-out directory is then |
| 563 | switched to the tip of that branch, so subsequent commits don’t need the |
| 564 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 565 | adding commits to the tip of that branch. |
| 566 | |
| 567 | To switch back to the parent branch, say something like: |
| 568 | |
| 569 | fossil update trunk # ≅ git checkout master |
| 570 | |
| 571 | Fossil does also support the Git style, creating the branch ahead of |
| 572 | need: |
| 573 | |
| 574 | fossil branch new my-new-branch |
| 575 | fossil update my-new-branch |
| 576 | ...work on first commit... |
| 577 | fossil commit |
| 578 | |
| 579 | This is more verbose, but it has the same effect: put the first commit |
| 580 | onto `my-new-branch` and switch the check-out directory to that branch so |
| 581 | subsequent commits are descendants of that initial branch commit. |
| 582 | |
| 583 | Fossil also allows you to move a check-in to a different branch |
| 584 | *after* you commit it, using the "`fossil amend`" command. |
| 585 | For example: |
| 586 | |
| 587 | fossil amend current --branch my-new-branch |
| 588 | |
| 589 | (The version string “current” is one of the [special check-in names][scin] in Fossil. See |
| 590 | that document for the many other names you can give to “`amend`”, or |
| 591 | indeed to any other Fossil command documented to accept a `VERSION` or |
| 592 | `NAME` string.) |
| @@ -613,11 +639,11 @@ | |
| 613 | This provides most of the advantages of a centralized version control |
| 614 | system while retaining the advantages of distributed version control: |
| 615 | |
| 616 | 1. Your work stays synced up with your coworkers’ efforts as long as your |
| 617 | machine can connect to the remote repository. At need, you can go |
| 618 | off-network and continue work atop the last version you sync’d with |
| 619 | the remote. |
| 620 | |
| 621 | 2. It provides immediate off-machine backup of your commits. Unlike |
| 622 | centralized version control, though, you can still work while |
| 623 | disconnected; your changes will sync up with the remote once you get |
| @@ -639,11 +665,11 @@ | |
| 639 | [setup]: ./caps/admin-v-setup.md#apsu |
| 640 | [wflow]: ./concepts.wiki#workflow |
| 641 | |
| 642 | |
| 643 | <a id="syncall"></a> |
| 644 | ## Sync Is All-Or-Nothing |
| 645 | |
| 646 | Fossil does not support the concept of syncing, pushing, or pulling |
| 647 | individual branches. When you sync/push/pull in Fossil, it |
| 648 | processes all artifacts in its hash tree: |
| 649 | branches, tags, wiki articles, tickets, forum posts, technotes… |
| @@ -711,11 +737,11 @@ | |
| 711 | come up with a new objection that we haven’t already considered and |
| 712 | addressed there. |
| 713 | |
| 714 | There is only one sub-feature of `git rebase` that is philosophically |
| 715 | compatible with Fossil yet which currently has no functional equivalent. |
| 716 | We cover [this and the workaround for it](#csplit) above. |
| 717 | |
| 718 | [3]: ./rebaseharm.md |
| 719 | |
| 720 | |
| 721 | ## <a id="cdiff"></a> Colorized Diffs |
| @@ -733,11 +759,12 @@ | |
| 733 | |
| 734 | fossil set --global diff-command 'colordiff -wu' |
| 735 | |
| 736 | Because this is unconditional, unlike `git diff --color=auto`, you will |
| 737 | then have to remember to add the `-i` option to `fossil diff` commands |
| 738 | when you want color disabled, such as when piping diff output to another |
| 739 | command that doesn’t understand ANSI escape sequences. There’s an |
| 740 | example of this [below](#dstat). |
| 741 | |
| 742 | Another way, which avoids this problem, is to say instead: |
| 743 | |
| @@ -750,14 +777,14 @@ | |
| 750 | |
| 751 | |
| 752 | ## <a id="show"></a> Showing Information About Commits |
| 753 | |
| 754 | While there is no direct equivalent to Git’s “`show`” command, similar |
| 755 | functionality may be present in Fossil under other commands: |
| 756 | |
| 757 | |
| 758 | #### <a id="patch"></a> Show A Patch For A Commit |
| 759 | |
| 760 | git show -p COMMIT_ID |
| 761 | |
| 762 | …gives much the same output as |
| 763 | |
| @@ -769,20 +796,24 @@ | |
| 769 | |
| 770 | You can use any of [Fossil’s special check-in names][scin] in place of |
| 771 | the `COMMIT_ID` in this and later examples. Fossil docs usually say |
| 772 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 773 | or name might not refer to a commit ID, but instead to a forum post, a |
| 774 | wiki document, etc. The following command answers the question “What did |
| 775 | I just commit?” |
| 776 | |
| 777 | fossil diff --checkin tip |
| 778 | |
| 779 | [devorg]: ./fossil-v-git.wiki#devorg |
| 780 | [LKML]: https://lkml.org/ |
| 781 | |
| 782 | |
| 783 | #### <a id="cmsg"></a> Show A Specific Commit Message |
| 784 | |
| 785 | git show -s COMMIT_ID |
| 786 | |
| 787 | |
| 788 | …is |
| @@ -890,18 +921,18 @@ | |
| 890 | |
| 891 | |
| 892 | ---- |
| 893 | |
| 894 | |
| 895 | ## <a id="cvdate" name="cs1"></a> Case Study 1: Checking Out A Version By Date |
| 896 | |
| 897 | Let’s get into something a bit more complicated: a case study showing |
| 898 | how the concepts lined out above cause Fossil to materially differ in |
| 899 | day-to-day operation from Git. |
| 900 | |
| 901 | Why would you want to check out a version of a project by date? Perhaps |
| 902 | because your customer gave you a vague bug report referencing only a |
| 903 | date rather than a version. Or, you may be poking semi-randomly through |
| 904 | history to find a “good” version to anchor the start point of a |
| 905 | [`fossil bisect`][fbis] operation. |
| 906 | |
| 907 | My search engine’s first result for “git checkout by date” is [this |
| @@ -917,12 +948,12 @@ | |
| 917 | means something else. You cannot simplify the cryptic incantation in |
| 918 | the typical use case. |
| 919 | |
| 920 | 2. A date string in Git without a time will be interpreted as |
| 921 | “[at the local wall clock time on the given date][gapxd],” so the |
| 922 | command means something different from one second to the next. This |
| 923 | can be a problem if there are multiple commits on that date, because |
| 924 | the command will give different results depending on the time of |
| 925 | day you run it. |
| 926 | |
| 927 | 3. It gives misleading output if there is no close match for the date |
| 928 | in the local [reflog]. It starts out empty after a fresh clone, and |
| @@ -940,11 +971,11 @@ | |
| 940 | date value you give. |
| 941 | |
| 942 | Git tries its best, but because it’s working from a purgeable and |
| 943 | possibly-stale local cache, you cannot trust its results. |
| 944 | |
| 945 | We cannot recommend this command at all. It’s unreliable even in the |
| 946 | best case. |
| 947 | |
| 948 | That same Stack Overflow answer therefore goes on to recommend an |
| 949 | entirely different command: |
| 950 | |
| @@ -1020,11 +1051,11 @@ | |
| 1020 | then maintain that index through subsequent commits and syncs. |
| 1021 | |
| 1022 | * Use an indexed SQL `ORDER BY` query to match timestamps to commit |
| 1023 | IDs for a fast and consistent result. |
| 1024 | |
| 1025 | * Round timestamp strings up using [rules][frud] consistent across |
| 1026 | computers and local time of day. |
| 1027 | |
| 1028 | [frud]: https://fossil-scm.org/home/file/src/name.c?ci=d2a59b03727bc3&ln=122-141 |
| 1029 | [gbash]: https://appuals.com/what-is-git-bash/ |
| 1030 | [gapxd]: https://github.com/git/git/blob/7f7ebe054a/date.c#L1298-L1300 |
| @@ -1195,13 +1226,19 @@ | |
| 1195 | The “Friday afternoon sync-up” case is simpler, too: |
| 1196 | |
| 1197 | fossil remote work |
| 1198 | fossil sync |
| 1199 | |
| 1200 | Back at home, it’s simpler still: we can do away with the second command, |
| 1201 | saying just “`fossil remote home`” because the sync will happen as part |
| 1202 | of the next commit, thanks once again to Fossil’s autosync feature. |
| 1203 | |
| 1204 | [grsync]: https://stackoverflow.com/q/1398018/142454 |
| 1205 | [qs]: ./quickstart.wiki |
| 1206 | [shwmd]: ./fossil-v-git.wiki#checkouts |
| 1207 | [sn]: https://en.wikipedia.org/wiki/Sneakernet |
| 1208 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -113,19 +113,19 @@ | |
| 113 | |
| 114 | Someone coming from the Git perspective may perceive that `fossil up` |
| 115 | has two purposes: |
| 116 | |
| 117 | * Without the optional `VERSION` argument, it updates the working |
| 118 | checkout to the tip of the current branch, as `git pull` does. |
| 119 | |
| 120 | * Given a `VERSION` argument, it updates to the named version. If that’s the |
| 121 | name of a branch, it updates to the *tip* of that branch, as |
| 122 | `git checkout BRANCH` does. |
| 123 | |
| 124 | In fact, these are the same operation, so they’re the same command in |
| 125 | Fossil. The first form simply allows the `VERSION` to be implicit: the |
| 126 | tip of the current branch. |
| 127 | |
| 128 | We think this is a more sensible command design than `git pull` vs |
| 129 | `git checkout`. ([…vs `git checkout` vs `git checkout`!][gcokoan]) |
| 130 | |
| 131 | [fpull]: /help?cmd=pull |
| @@ -144,10 +144,11 @@ | |
| 144 | |
| 145 | This author uses a scheme like the following on mobile machines that |
| 146 | shuttle between home and the office: |
| 147 | |
| 148 | ``` pikchr toggle indent |
| 149 | scale=0.8 |
| 150 | box "~/museum/" fit |
| 151 | move right 0.1 |
| 152 | line right dotted |
| 153 | move right 0.05 |
| 154 | box invis "where one stores valuable fossils" ljust |
| @@ -176,20 +177,22 @@ | |
| 177 | |
| 178 | On a Windows box, you might instead choose "`C:\Fossils`" |
| 179 | and do without the subdirectory scheme, for example. |
| 180 | |
| 181 | |
| 182 | #### <a id="close" name="dotfile"></a> Closing a Check-Out |
| 183 | |
| 184 | The [`fossil close`][close] command dissociates a check-out directory from the |
| 185 | Fossil repository database, nondestructively inverting [`fossil open`][open]. |
| 186 | (Contrast [its closest inverse](#worktree), `git worktree remove`, which *is* |
| 187 | destructive in Git!) This Fossil command does not |
| 188 | remove the managed files, and unless you give the `--force` |
| 189 | option, it won’t let you close the check-out with uncommitted changes to |
| 190 | those managed files. |
| 191 | |
| 192 | The `close` command also refuses to run without `--force` when you have |
| 193 | certain other precious per-checkout data that Fossil stores in the |
| 194 | `.fslckout` file at the root of a check-out directory. This is a SQLite |
| 195 | database that keeps track of local state such as what version you have |
| 196 | checked out, the contents of the [stash] for that working directory, the |
| 197 | [undo] buffers, per-checkout [settings][set], and so forth. The stash |
| 198 | and undo buffers are considered precious uncommitted changes, |
| @@ -226,20 +229,27 @@ | |
| 229 | |
| 230 | The symlink trick has a number of problems, the largest being that |
| 231 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 232 | 10 Creators Update was released in spring of 2017, you had to be an |
| 233 | Administrator to use the feature besides. ([Source][wsyml]) Git solved |
| 234 | this problem back when Windows XP was Microsoft’s current offering |
| 235 | with the `git-worktree` command, added in Git 2.5: |
| 236 | |
| 237 | git worktree add ../foo-branch foo-branch |
| 238 | cd ../foo-branch |
| 239 | |
| 240 | That is approximately equivalent to this in Fossil: |
| 241 | |
| 242 | mkdir ../foo-branch |
| 243 | cd ../foo-branch |
| 244 | fossil open /path/to/repo.fossil foo-branch |
| 245 | |
| 246 | The Fossil alternative is wordier, but this tends to be one-time setup, |
| 247 | not something you do everyday. This author keeps a “scratch” checkout |
| 248 | for cases where is isn’t appropriate to reuse the “trunk” checkout. The |
| 249 | other peer checkouts therefore tend to track long-lived branches, so |
| 250 | they rarely change once a development machine is set up. |
| 251 | |
| 252 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 253 | check-out](#close): |
| 254 | |
| 255 | git worktree remove . |
| @@ -340,13 +350,13 @@ | |
| 350 | reads from a single disk file rather than visit potentially many |
| 351 | files in sequence as Git must, so the OS’s buffer cache can result in |
| 352 | [still better performance][35pct]. |
| 353 | |
| 354 | Unlike Git’s log, Fossil’s timeline shows info across branches by |
| 355 | default, a feature for maintaining better situational awareness. Although the |
| 356 | `fossil timeline` command has no way to show a single branch’s commits, |
| 357 | you can restrict your view like this using the web UI equivalent by |
| 358 | clicking the name of a branch on the `/timeline` or `/brlist` page. (Or |
| 359 | manually, by adding the `r=` query parameter.) Note that even in this |
| 360 | case, the Fossil timeline still shows other branches where they interact |
| 361 | with the one you’ve referenced in this way; again, better situational |
| 362 | awareness. |
| @@ -507,10 +517,13 @@ | |
| 517 | If you only want to commit _some_ of the changes, list the names |
| 518 | of the files or directories you want to commit as arguments, like this: |
| 519 | |
| 520 | fossil commit src/feature.c doc/feature.md examples/feature |
| 521 | |
| 522 | Note that the last element is a directory name, meaning “any changed |
| 523 | file under the `examples/feature` directory.” |
| 524 | |
| 525 | Although there are currently no |
| 526 | <a id="csplit"></a>[commit splitting][gcspl] features in Fossil like |
| 527 | `git add -p`, `git commit -p`, or `git rebase -i`, you can get the same |
| 528 | effect by converting an uncommitted change set to a patch and then |
| 529 | running it through [Patchouli]. |
| @@ -550,43 +563,56 @@ | |
| 563 | [gcspl]: https://git-scm.com/docs/git-rebase#_splitting_commits |
| 564 | [Patchouli]: https://pypi.org/project/patchouli/ |
| 565 | |
| 566 | |
| 567 | <a id="bneed"></a> |
| 568 | ## Create Branches at Point of Need, Rather Than Ahead of Need |
| 569 | |
| 570 | Fossil prefers that you create new branches as part of the first commit |
| 571 | on that branch: |
| 572 | |
| 573 | fossil commit --branch my-branch |
| 574 | |
| 575 | If that commit is successful, your local check-out directory is then |
| 576 | switched to the tip of that branch, so subsequent commits don’t need the |
| 577 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 578 | adding commits to the tip of that branch. |
| 579 | |
| 580 | To switch back to the parent branch, say something like: |
| 581 | |
| 582 | fossil update trunk |
| 583 | |
| 584 | (This is approximately equivalent to `git checkout master`.) |
| 585 | |
| 586 | Fossil does also support the Git style, creating the branch ahead of |
| 587 | need: |
| 588 | |
| 589 | fossil branch new my-branch |
| 590 | fossil up my-branch |
| 591 | ...work on first commit... |
| 592 | fossil commit |
| 593 | |
| 594 | This is more verbose, giving the same overall effect though the initial |
| 595 | actions are inverted: create a new branch for the first commit, switch |
| 596 | the check-out directory to that branch, and make that first commit. As |
| 597 | above, subsequent commits are descendants of that initial branch commit. |
| 598 | We think you’ll agree that creating a branch as part of the initial |
| 599 | commit is simpler. |
| 600 | |
| 601 | Fossil also allows you to move a check-in to a different branch |
| 602 | *after* you commit it, using the "`fossil amend`" command. |
| 603 | For example: |
| 604 | |
| 605 | fossil amend current --branch my-branch |
| 606 | |
| 607 | This works by inserting a tag into the repository that causes the web UI |
| 608 | to relabel commits from that point forward with the new name. Like Git, |
| 609 | Fossil’s fundamental data structure is the interlinked DAG of commit |
| 610 | hashes; branch names are supplemental data for making it easier for the |
| 611 | humans to understand this DAG, so this command does not change the core |
| 612 | history of the project, only annotate it for better display to the |
| 613 | humans. |
| 614 | |
| 615 | (The version string “current” is one of the [special check-in names][scin] in Fossil. See |
| 616 | that document for the many other names you can give to “`amend`”, or |
| 617 | indeed to any other Fossil command documented to accept a `VERSION` or |
| 618 | `NAME` string.) |
| @@ -613,11 +639,11 @@ | |
| 639 | This provides most of the advantages of a centralized version control |
| 640 | system while retaining the advantages of distributed version control: |
| 641 | |
| 642 | 1. Your work stays synced up with your coworkers’ efforts as long as your |
| 643 | machine can connect to the remote repository. At need, you can go |
| 644 | off-network and continue work atop the last version you synced with |
| 645 | the remote. |
| 646 | |
| 647 | 2. It provides immediate off-machine backup of your commits. Unlike |
| 648 | centralized version control, though, you can still work while |
| 649 | disconnected; your changes will sync up with the remote once you get |
| @@ -639,11 +665,11 @@ | |
| 665 | [setup]: ./caps/admin-v-setup.md#apsu |
| 666 | [wflow]: ./concepts.wiki#workflow |
| 667 | |
| 668 | |
| 669 | <a id="syncall"></a> |
| 670 | ## Sync Is All-or-Nothing |
| 671 | |
| 672 | Fossil does not support the concept of syncing, pushing, or pulling |
| 673 | individual branches. When you sync/push/pull in Fossil, it |
| 674 | processes all artifacts in its hash tree: |
| 675 | branches, tags, wiki articles, tickets, forum posts, technotes… |
| @@ -711,11 +737,11 @@ | |
| 737 | come up with a new objection that we haven’t already considered and |
| 738 | addressed there. |
| 739 | |
| 740 | There is only one sub-feature of `git rebase` that is philosophically |
| 741 | compatible with Fossil yet which currently has no functional equivalent. |
| 742 | We [covered this and the workaround for its lack](#csplit) above. |
| 743 | |
| 744 | [3]: ./rebaseharm.md |
| 745 | |
| 746 | |
| 747 | ## <a id="cdiff"></a> Colorized Diffs |
| @@ -733,11 +759,12 @@ | |
| 759 | |
| 760 | fossil set --global diff-command 'colordiff -wu' |
| 761 | |
| 762 | Because this is unconditional, unlike `git diff --color=auto`, you will |
| 763 | then have to remember to add the `-i` option to `fossil diff` commands |
| 764 | when you want color disabled, such as when producing `patch(1)` files |
| 765 | or piping diff output to another |
| 766 | command that doesn’t understand ANSI escape sequences. There’s an |
| 767 | example of this [below](#dstat). |
| 768 | |
| 769 | Another way, which avoids this problem, is to say instead: |
| 770 | |
| @@ -750,14 +777,14 @@ | |
| 777 | |
| 778 | |
| 779 | ## <a id="show"></a> Showing Information About Commits |
| 780 | |
| 781 | While there is no direct equivalent to Git’s “`show`” command, similar |
| 782 | functionality is present in Fossil under other commands: |
| 783 | |
| 784 | |
| 785 | #### <a id="patch"></a> Show a Patch for a Commit |
| 786 | |
| 787 | git show -p COMMIT_ID |
| 788 | |
| 789 | …gives much the same output as |
| 790 | |
| @@ -769,20 +796,24 @@ | |
| 796 | |
| 797 | You can use any of [Fossil’s special check-in names][scin] in place of |
| 798 | the `COMMIT_ID` in this and later examples. Fossil docs usually say |
| 799 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 800 | or name might not refer to a commit ID, but instead to a forum post, a |
| 801 | wiki document, etc. For instance, the following command answers the question “What did |
| 802 | I just commit?” |
| 803 | |
| 804 | fossil diff --checkin tip |
| 805 | |
| 806 | …or equivalently using a different symbolic commit name: |
| 807 | |
| 808 | fossil diff --from prev |
| 809 | |
| 810 | [devorg]: ./fossil-v-git.wiki#devorg |
| 811 | [LKML]: https://lkml.org/ |
| 812 | |
| 813 | |
| 814 | #### <a id="cmsg"></a> Show a Specific Commit Message |
| 815 | |
| 816 | git show -s COMMIT_ID |
| 817 | |
| 818 | |
| 819 | …is |
| @@ -890,18 +921,18 @@ | |
| 921 | |
| 922 | |
| 923 | ---- |
| 924 | |
| 925 | |
| 926 | ## <a id="cvdate" name="cs1"></a> Case Study 1: Checking Out a Version by Date |
| 927 | |
| 928 | Let’s get into something a bit more complicated: a case study showing |
| 929 | how the concepts lined out above cause Fossil to materially differ in |
| 930 | day-to-day operation from Git. |
| 931 | |
| 932 | Why would you want to check out a version of a project by date? Perhaps |
| 933 | your customer gave you a vague bug report referencing only a |
| 934 | date rather than a version. Or, you may be poking semi-randomly through |
| 935 | history to find a “good” version to anchor the start point of a |
| 936 | [`fossil bisect`][fbis] operation. |
| 937 | |
| 938 | My search engine’s first result for “git checkout by date” is [this |
| @@ -917,12 +948,12 @@ | |
| 948 | means something else. You cannot simplify the cryptic incantation in |
| 949 | the typical use case. |
| 950 | |
| 951 | 2. A date string in Git without a time will be interpreted as |
| 952 | “[at the local wall clock time on the given date][gapxd],” so the |
| 953 | command means something different from one second to the next! This |
| 954 | can be a serious problem if there are multiple commits on that date, because |
| 955 | the command will give different results depending on the time of |
| 956 | day you run it. |
| 957 | |
| 958 | 3. It gives misleading output if there is no close match for the date |
| 959 | in the local [reflog]. It starts out empty after a fresh clone, and |
| @@ -940,11 +971,11 @@ | |
| 971 | date value you give. |
| 972 | |
| 973 | Git tries its best, but because it’s working from a purgeable and |
| 974 | possibly-stale local cache, you cannot trust its results. |
| 975 | |
| 976 | Consequently, we cannot recommend this command at all. It’s unreliable even in the |
| 977 | best case. |
| 978 | |
| 979 | That same Stack Overflow answer therefore goes on to recommend an |
| 980 | entirely different command: |
| 981 | |
| @@ -1020,11 +1051,11 @@ | |
| 1051 | then maintain that index through subsequent commits and syncs. |
| 1052 | |
| 1053 | * Use an indexed SQL `ORDER BY` query to match timestamps to commit |
| 1054 | IDs for a fast and consistent result. |
| 1055 | |
| 1056 | * Round incomplete timestamp strings up using [rules][frud] consistent across |
| 1057 | computers and local time of day. |
| 1058 | |
| 1059 | [frud]: https://fossil-scm.org/home/file/src/name.c?ci=d2a59b03727bc3&ln=122-141 |
| 1060 | [gbash]: https://appuals.com/what-is-git-bash/ |
| 1061 | [gapxd]: https://github.com/git/git/blob/7f7ebe054a/date.c#L1298-L1300 |
| @@ -1195,13 +1226,19 @@ | |
| 1226 | The “Friday afternoon sync-up” case is simpler, too: |
| 1227 | |
| 1228 | fossil remote work |
| 1229 | fossil sync |
| 1230 | |
| 1231 | Back at home, it’s simpler still: we may be able to do away with the second command, |
| 1232 | saying just “`fossil remote home`” because the sync will happen as part |
| 1233 | of the next commit, thanks once again to Fossil’s autosync feature. If |
| 1234 | the working branch now has commits from other developers after syncing |
| 1235 | with the central repository, though, you’ll want to say “`fossil up`” to |
| 1236 | avoid creating an inadvertent fork in the branch. |
| 1237 | |
| 1238 | (Which is easy to fix if it occurs: `fossil merge` without arguments |
| 1239 | means “merge open tips on the current branch.”) |
| 1240 | |
| 1241 | [grsync]: https://stackoverflow.com/q/1398018/142454 |
| 1242 | [qs]: ./quickstart.wiki |
| 1243 | [shwmd]: ./fossil-v-git.wiki#checkouts |
| 1244 | [sn]: https://en.wikipedia.org/wiki/Sneakernet |
| 1245 |