Fossil SCM
Continued the edit pass on the main body of the gitusers doc, shy of the case studies, mainly doing minor style tweaks. Biggest substantial change is to rewrite the colorized diff section to cover the changes in Fossil 2.17, and to present the alternatives in a more logical order.
Commit
c026fb9ad9af53948b15997a5f5224989d961ce2781a50353c2d3d7f46508d3c
Parent
e3f9584e3ff6b0d…
1 file changed
+70
-52
+70
-52
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -40,29 +40,30 @@ | ||
| 40 | 40 | [ffor]: https://fossil-scm.org/forum |
| 41 | 41 | [fvg]: ./fossil-v-git.wiki |
| 42 | 42 | |
| 43 | 43 | |
| 44 | 44 | <a id="mwd"></a> |
| 45 | -## Repositories And Checkouts Are Distinct | |
| 45 | +## Repositories and Checkouts Are Distinct | |
| 46 | 46 | |
| 47 | -A repository and a check-out are distinct concepts in Fossil, whereas | |
| 48 | -the two are collocated by default with Git. This difference shows up in | |
| 49 | -several separate places when it comes to moving from Git to Fossil. | |
| 47 | +A repository and a check-out are distinct in Fossil, allowing them to be | |
| 48 | +stored in separate directory trees, whereas the two are commingled by | |
| 49 | +default with Git, with the repository stored in a `.git` subdirectory | |
| 50 | +underneath your working directory. This difference shows up in several | |
| 51 | +separate places when it comes to moving from Git to Fossil. | |
| 50 | 52 | |
| 51 | 53 | |
| 52 | 54 | |
| 53 | 55 | #### <a id="cwork" name="scw"></a> Checkout Workflows |
| 54 | 56 | |
| 55 | 57 | A Fossil repository is a SQLite database storing the entire history of a |
| 56 | 58 | project. It is not normally stored inside the working tree. |
| 57 | -A Fossil working tree — also called a check-out — is a directory | |
| 59 | +A Fossil working tree — [also called a check-out](./glossary.md#check-out) — is a directory | |
| 58 | 60 | that contains a snapshot of your project that you are currently working |
| 59 | 61 | on, extracted for you from the repository database file by the `fossil` |
| 60 | 62 | program. |
| 61 | 63 | |
| 62 | -Git commingles these two by default, with the repository stored in a | |
| 63 | -`.git` subdirectory underneath your working directory. There are ways to | |
| 64 | +There are ways to | |
| 64 | 65 | [emulate the Fossil working style in Git](#worktree), but because they’re not |
| 65 | 66 | designed into the core concept of the tool, Git tutorials usually |
| 66 | 67 | advocate a switch-in-place working mode instead, so that is how most |
| 67 | 68 | users end up working with Git. Contrast [Fossil’s check-out workflow |
| 68 | 69 | document][ckwf] to see the practical differences. |
| @@ -113,11 +114,11 @@ | ||
| 113 | 114 | |
| 114 | 115 | Someone coming from the Git perspective may perceive that `fossil up` |
| 115 | 116 | has two purposes: |
| 116 | 117 | |
| 117 | 118 | * Without the optional `VERSION` argument, it updates the working |
| 118 | - checkout to the tip of the current branch, as `git pull` does. | |
| 119 | + check-out to the tip of the current branch, as `git pull` does. | |
| 119 | 120 | |
| 120 | 121 | * Given a `VERSION` argument, it updates to the named version. If that’s the |
| 121 | 122 | name of a branch, it updates to the *tip* of that branch, as |
| 122 | 123 | `git checkout BRANCH` does. |
| 123 | 124 | |
| @@ -196,14 +197,16 @@ | ||
| 196 | 197 | mkdir ../foo-branch |
| 197 | 198 | cd ../foo-branch |
| 198 | 199 | fossil open /path/to/repo.fossil foo-branch |
| 199 | 200 | |
| 200 | 201 | The Fossil alternative is wordier, but this tends to be one-time setup, |
| 201 | -not something you do everyday. This author keeps a “scratch” checkout | |
| 202 | -for cases where is isn’t appropriate to reuse the “trunk” checkout. The | |
| 203 | -other peer checkouts therefore tend to track long-lived branches, so | |
| 204 | -they rarely change once a development machine is set up. | |
| 202 | +not something you do everyday. This author keeps a “scratch” check-out | |
| 203 | +for cases where is isn’t appropriate to reuse the “trunk” check-out, | |
| 204 | +isolating all of my expedient switch-in-place actions to that one | |
| 205 | +working directory. Since the other peer check-out track long-lived | |
| 206 | +branches, and that set rarely changes once a development machine is set | |
| 207 | +up, I rarely pay the cost of these wordier commands. | |
| 205 | 208 | |
| 206 | 209 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 207 | 210 | check-out](#close): |
| 208 | 211 | |
| 209 | 212 | git worktree remove . |
| @@ -298,11 +301,13 @@ | ||
| 298 | 301 | to produce its [timeline CLI][tlc] and [its `/timeline` web view][tlw] |
| 299 | 302 | using indexed SQL lookups, which generally have the info you would have |
| 300 | 303 | to manually extract from `git log`, produced much more quickly than Git |
| 301 | 304 | can, all else being equal: operations over [SQLite’s B-tree data structures][btree] |
| 302 | 305 | generally run in O(log n) time, faster than O(n) for equal *n* when the |
| 303 | -constants are equal. Yet the constants are *not* equal because Fossil | |
| 306 | +constants are equal. | |
| 307 | + | |
| 308 | +Yet the constants are *not* equal because Fossil | |
| 304 | 309 | reads from a single disk file rather than visit potentially many |
| 305 | 310 | files in sequence as Git must, so the OS’s buffer cache can result in |
| 306 | 311 | [still better performance][35pct]. |
| 307 | 312 | |
| 308 | 313 | Unlike Git’s log, Fossil’s timeline shows info across branches by |
| @@ -430,18 +435,18 @@ | ||
| 430 | 435 | [wdm]: ./fossil-v-git.wiki#durable |
| 431 | 436 | |
| 432 | 437 | |
| 433 | 438 | ## <a id="dhead"></a> Detached HEAD State |
| 434 | 439 | |
| 435 | -The SQL indexes in Fossil which we brought up above have a very useful | |
| 440 | +The SQL indexes in Fossil which we brought up above have a useful | |
| 436 | 441 | side benefit: you cannot have a [detached HEAD state][gdh] in Fossil, |
| 437 | 442 | the source of untold pain and data loss in Git. It simply cannot be done |
| 438 | 443 | in Fossil, because the indexes always let us find our way back into the |
| 439 | 444 | hash tree. |
| 440 | 445 | |
| 441 | 446 | |
| 442 | -## <a id="slcom"></a> Summary Line Convention In Commit Comments | |
| 447 | +## <a id="slcom"></a> Summary Line Convention in Commit Comments | |
| 443 | 448 | |
| 444 | 449 | The Git convention of a [length-limited summary line][lsl] at the start |
| 445 | 450 | of commit comments is not enforced or obeyed by default in Fossil. |
| 446 | 451 | However, there is a setting under Admin → Timeline → “Truncate comment |
| 447 | 452 | at first blank line (Git-style)” to change this for `/timeline` |
| @@ -506,11 +511,11 @@ | ||
| 506 | 511 | but we’d rather make changes only to the working directory, test the |
| 507 | 512 | changes there, and only commit once we’re sure it’s right. |
| 508 | 513 | |
| 509 | 514 | This also explains why we don’t have anything like `git rebase -i` |
| 510 | 515 | to split an existing commit: in Fossil, commits are *commitments,* not |
| 511 | -something you want to go back and rewrite later. | |
| 516 | +something you’re allowed to go back and rewrite later. | |
| 512 | 517 | |
| 513 | 518 | If someone does [contribute][ctrb] a commit splitting feature to Fossil, |
| 514 | 519 | we’d expect it to be an interactive form of |
| 515 | 520 | [`fossil stash apply`][stash], rather than follow Git’s ill-considered |
| 516 | 521 | design leads. |
| @@ -603,22 +608,20 @@ | ||
| 603 | 608 | 2. It provides immediate off-machine backup of your commits. Unlike |
| 604 | 609 | centralized version control, though, you can still work while |
| 605 | 610 | disconnected; your changes will sync up with the remote once you get |
| 606 | 611 | back online. |
| 607 | 612 | |
| 608 | -3. Because there is little distinction between the clones in the Fossil | |
| 613 | +3. Because there is [little distinction][bu] between the clones in the Fossil | |
| 609 | 614 | model — unlike in Git, where clones often quickly diverge from each |
| 610 | 615 | other, quite possibly on purpose — the backup advantage applies in inverse |
| 611 | 616 | as well: if the remote server falls over dead, one of those with a |
| 612 | 617 | clone of that repository can stand it back up, and everyone can get |
| 613 | 618 | back to work simply by re-pointing their local repo at the new |
| 614 | 619 | remote. If the failed remote comes back later, it can sync with the |
| 615 | 620 | new central version, then perhaps take over as the primary source of |
| 616 | 621 | truth once again. |
| 617 | 622 | |
| 618 | - (There are caveats to this, [covered elsewhere][bu].) | |
| 619 | - | |
| 620 | 623 | [bu]: ./backup.md |
| 621 | 624 | [setup]: ./caps/admin-v-setup.md#apsu |
| 622 | 625 | [wflow]: ./concepts.wiki#workflow |
| 623 | 626 | |
| 624 | 627 | |
| @@ -667,11 +670,11 @@ | ||
| 667 | 670 | [mbgh]: https://github.com/github/renaming |
| 668 | 671 | [mirgh]: ./mirrortogithub.md |
| 669 | 672 | |
| 670 | 673 | |
| 671 | 674 | <a id="unmanaged"></a> |
| 672 | -## The "`fossil status`" Command Does Not Show Unmanaged Files | |
| 675 | +## Status Does Not Show Unmanaged Files | |
| 673 | 676 | |
| 674 | 677 | The "`fossil status`" command shows you what files in your check-out have |
| 675 | 678 | been edited and scheduled for adding or removing at the next commit. |
| 676 | 679 | But unlike "`git status`", the "`fossil status`" command does not warn |
| 677 | 680 | you about unmanaged files in your local check-out. There is a separate |
| @@ -700,38 +703,52 @@ | ||
| 700 | 703 | [3]: ./rebaseharm.md |
| 701 | 704 | |
| 702 | 705 | |
| 703 | 706 | ## <a id="cdiff"></a> Colorized Diffs |
| 704 | 707 | |
| 705 | -The graphical diffs in the Fossil web UI and `fossil diff --tk` use | |
| 706 | -color to distinguish insertions, deletions, and replacements, but unlike | |
| 707 | -with `git diff` when the output is to an ANSI X3.64 capable terminal, | |
| 708 | -`fossil diff` does not. | |
| 709 | - | |
| 710 | -There are a few easy ways to add this feature to Fossil, though. | |
| 711 | - | |
| 712 | -One is to install | |
| 713 | -[`colordiff`][cdiff], which is included in [many package systems][cdpkg], | |
| 714 | -then say: | |
| 715 | - | |
| 716 | - fossil set --global diff-command 'colordiff -wu' | |
| 717 | - | |
| 718 | -Because this is unconditional, unlike `git diff --color=auto`, you will | |
| 719 | -then have to remember to add the `-i` option to `fossil diff` commands | |
| 720 | -when you want color disabled, such as when producing `patch(1)` files | |
| 721 | -or piping diff output to another | |
| 722 | -command that doesn’t understand ANSI escape sequences. There’s an | |
| 723 | -example of this [below](#dstat). | |
| 724 | - | |
| 725 | -Another way, which avoids this problem, is to say instead: | |
| 726 | - | |
| 727 | - fossil set --global diff-command 'git diff --no-index' | |
| 728 | - | |
| 729 | -This delegates `fossil diff` to `git diff` by using the latter’s | |
| 730 | -ability to run on files not inside any repository. | |
| 708 | +When you run `git diff` on an ANSI X3.64 capable terminal, it uses color | |
| 709 | +to distinguish insertions, deletions, and replacements, but as of this | |
| 710 | +writing, `fossil diff` produces traditional uncolored [unified diff | |
| 711 | +format][udiff] output, suitable for producing a [patch file][pfile]. | |
| 712 | + | |
| 713 | +Nevertheless, there are multiple ways to get colorized diff output from | |
| 714 | +Fossil: | |
| 715 | + | |
| 716 | +* The most direct method is to delegate diff behavior back to Git: | |
| 717 | + | |
| 718 | + fossil set --global diff-command 'git diff --no-index' | |
| 719 | + | |
| 720 | + The flag permits it to diff files that aren’t inside a Git repository. | |
| 721 | + | |
| 722 | +* Another method is to install [`colordiff`][cdiff] — included in | |
| 723 | + [many package systems][cdpkg] — then say: | |
| 724 | + | |
| 725 | + fossil set --global diff-command 'colordiff -wu' | |
| 726 | + | |
| 727 | + Because this is unconditional, unlike `git diff --color=auto`, you | |
| 728 | + will then have to remember to add the `-i` option to `fossil diff` | |
| 729 | + commands when you want color disabled, such as when producing | |
| 730 | + `patch(1)` files or piping diff output to another command that | |
| 731 | + doesn’t understand ANSI escape sequences. There’s an example of this | |
| 732 | + [below](#dstat). | |
| 733 | + | |
| 734 | +* Use the Fossil web UI to diff existing commits. | |
| 735 | + | |
| 736 | +* To diff the current working directory contents against some parent | |
| 737 | + instead, Fossil 2.17 expanded the diff command so it can produce | |
| 738 | + colorized HTML output and open it in the OS’s default web browser. | |
| 739 | + For example, `fossil diff -by` will show side-by-side diffs. | |
| 740 | + | |
| 741 | +* Use the older `fossil diff --tk` option to do much the same using | |
| 742 | + Tcl/Tk instead of a browser. | |
| 743 | + | |
| 744 | +Viewed this way, Fossil doesn’t lack colorized diffs, it simply has | |
| 745 | +*one* method where they *aren’t* colorized. | |
| 731 | 746 | |
| 732 | 747 | [cdpkg]: https://repology.org/project/colordiff/versions |
| 748 | +[pfile]: https://en.wikipedia.org/wiki/Patch_(Unix) | |
| 749 | +[udiff]: https://en.wikipedia.org/wiki/Diff#Unified_format | |
| 733 | 750 | |
| 734 | 751 | |
| 735 | 752 | ## <a id="show"></a> Showing Information About Commits |
| 736 | 753 | |
| 737 | 754 | While there is no direct equivalent to Git’s “`show`” command, similar |
| @@ -746,11 +763,11 @@ | ||
| 746 | 763 | |
| 747 | 764 | fossil diff --checkin COMMIT_ID |
| 748 | 765 | |
| 749 | 766 | …only without the patch email header. Git comes out of the [LKML] world, |
| 750 | 767 | where emailing a patch is a normal thing to do. Fossil is [designed for |
| 751 | -cohesive teams][devorg] where such drive-by patches are rarer. | |
| 768 | +cohesive teams][devorg] where drive-by patches are rarer. | |
| 752 | 769 | |
| 753 | 770 | You can use any of [Fossil’s special check-in names][scin] in place of |
| 754 | 771 | the `COMMIT_ID` in this and later examples. Fossil docs usually say |
| 755 | 772 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 756 | 773 | or name might not refer to a commit ID, but instead to a forum post, a |
| @@ -812,18 +829,18 @@ | ||
| 812 | 829 | [dcset]: https://fossil-scm.org/home/help?cmd=diff-command |
| 813 | 830 | [dst]: https://invisible-island.net/diffstat/diffstat.html |
| 814 | 831 | |
| 815 | 832 | |
| 816 | 833 | <a id="btnames"></a> |
| 817 | -## Branch And Tag Names | |
| 834 | +## Branch and Tag Names | |
| 818 | 835 | |
| 819 | 836 | Fossil has no special restrictions on the names of tags and branches, |
| 820 | 837 | though you might want to keep [Git's tag and branch name restrictions][gcrf] |
| 821 | 838 | in mind if you plan on [mirroring your Fossil repository to GitHub][mirgh]. |
| 822 | 839 | |
| 823 | 840 | Fossil does not require tag and branch names to be unique. It is |
| 824 | -common, for example, to put a "`release`" tag on every release for a | |
| 841 | +common, for example, to put a “`release`” tag on every release for a | |
| 825 | 842 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 826 | 843 | Fossil resolves the ambiguity in a predictable way: the newest match |
| 827 | 844 | wins. Therefore, “`fossil up release`” always gets you the current |
| 828 | 845 | release in a project that uses this tagging convention. |
| 829 | 846 | |
| @@ -837,25 +854,26 @@ | ||
| 837 | 854 | |
| 838 | 855 | |
| 839 | 856 | |
| 840 | 857 | |
| 841 | 858 | <a id="cpickrev"></a> |
| 842 | -## Cherry-Picking And Reverting Commits | |
| 859 | +## Cherry-Picking and Reverting Commits | |
| 843 | 860 | |
| 844 | 861 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 845 | 862 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 846 | -`--backout`, respectively. | |
| 863 | +`--backout`, respectively. We view this as sensible, since these are | |
| 864 | +both merge operations, and the two actions differ only in direction. | |
| 847 | 865 | |
| 848 | 866 | Unlike in Git, the Fossil file format remembers cherrypicks and backouts |
| 849 | 867 | and can later show them as dashed lines on the graphical timeline. |
| 850 | 868 | |
| 851 | 869 | [merge]: /help?cmd=merge |
| 852 | 870 | |
| 853 | 871 | |
| 854 | 872 | |
| 855 | 873 | <a id="mvrm"></a> |
| 856 | -## File Moves And Renames Are Soft By Default | |
| 874 | +## File Moves and Renames Are Soft by Default | |
| 857 | 875 | |
| 858 | 876 | The "[`fossil mv`][mv]" and "[`fossil rm`][rm]" commands work like they |
| 859 | 877 | do in CVS in that they schedule the changes for the next commit by |
| 860 | 878 | default: they do not actually rename or delete the files in your |
| 861 | 879 | check-out. |
| 862 | 880 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -40,29 +40,30 @@ | |
| 40 | [ffor]: https://fossil-scm.org/forum |
| 41 | [fvg]: ./fossil-v-git.wiki |
| 42 | |
| 43 | |
| 44 | <a id="mwd"></a> |
| 45 | ## Repositories And Checkouts Are Distinct |
| 46 | |
| 47 | A repository and a check-out are distinct concepts in Fossil, whereas |
| 48 | the two are collocated by default with Git. This difference shows up in |
| 49 | several separate places when it comes to moving from Git to Fossil. |
| 50 | |
| 51 | |
| 52 | |
| 53 | #### <a id="cwork" name="scw"></a> Checkout Workflows |
| 54 | |
| 55 | A Fossil repository is a SQLite database storing the entire history of a |
| 56 | project. It is not normally stored inside the working tree. |
| 57 | A Fossil working tree — also called a check-out — is a directory |
| 58 | that contains a snapshot of your project that you are currently working |
| 59 | on, extracted for you from the repository database file by the `fossil` |
| 60 | program. |
| 61 | |
| 62 | Git commingles these two by default, with the repository stored in a |
| 63 | `.git` subdirectory underneath your working directory. There are ways to |
| 64 | [emulate the Fossil working style in Git](#worktree), but because they’re not |
| 65 | designed into the core concept of the tool, Git tutorials usually |
| 66 | advocate a switch-in-place working mode instead, so that is how most |
| 67 | users end up working with Git. Contrast [Fossil’s check-out workflow |
| 68 | document][ckwf] to see the practical differences. |
| @@ -113,11 +114,11 @@ | |
| 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 | |
| @@ -196,14 +197,16 @@ | |
| 196 | mkdir ../foo-branch |
| 197 | cd ../foo-branch |
| 198 | fossil open /path/to/repo.fossil foo-branch |
| 199 | |
| 200 | The Fossil alternative is wordier, but this tends to be one-time setup, |
| 201 | not something you do everyday. This author keeps a “scratch” checkout |
| 202 | for cases where is isn’t appropriate to reuse the “trunk” checkout. The |
| 203 | other peer checkouts therefore tend to track long-lived branches, so |
| 204 | they rarely change once a development machine is set up. |
| 205 | |
| 206 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 207 | check-out](#close): |
| 208 | |
| 209 | git worktree remove . |
| @@ -298,11 +301,13 @@ | |
| 298 | to produce its [timeline CLI][tlc] and [its `/timeline` web view][tlw] |
| 299 | using indexed SQL lookups, which generally have the info you would have |
| 300 | to manually extract from `git log`, produced much more quickly than Git |
| 301 | can, all else being equal: operations over [SQLite’s B-tree data structures][btree] |
| 302 | generally run in O(log n) time, faster than O(n) for equal *n* when the |
| 303 | constants are equal. Yet the constants are *not* equal because Fossil |
| 304 | reads from a single disk file rather than visit potentially many |
| 305 | files in sequence as Git must, so the OS’s buffer cache can result in |
| 306 | [still better performance][35pct]. |
| 307 | |
| 308 | Unlike Git’s log, Fossil’s timeline shows info across branches by |
| @@ -430,18 +435,18 @@ | |
| 430 | [wdm]: ./fossil-v-git.wiki#durable |
| 431 | |
| 432 | |
| 433 | ## <a id="dhead"></a> Detached HEAD State |
| 434 | |
| 435 | The SQL indexes in Fossil which we brought up above have a very useful |
| 436 | side benefit: you cannot have a [detached HEAD state][gdh] in Fossil, |
| 437 | the source of untold pain and data loss in Git. It simply cannot be done |
| 438 | in Fossil, because the indexes always let us find our way back into the |
| 439 | hash tree. |
| 440 | |
| 441 | |
| 442 | ## <a id="slcom"></a> Summary Line Convention In Commit Comments |
| 443 | |
| 444 | The Git convention of a [length-limited summary line][lsl] at the start |
| 445 | of commit comments is not enforced or obeyed by default in Fossil. |
| 446 | However, there is a setting under Admin → Timeline → “Truncate comment |
| 447 | at first blank line (Git-style)” to change this for `/timeline` |
| @@ -506,11 +511,11 @@ | |
| 506 | but we’d rather make changes only to the working directory, test the |
| 507 | changes there, and only commit once we’re sure it’s right. |
| 508 | |
| 509 | This also explains why we don’t have anything like `git rebase -i` |
| 510 | to split an existing commit: in Fossil, commits are *commitments,* not |
| 511 | something you want to go back and rewrite later. |
| 512 | |
| 513 | If someone does [contribute][ctrb] a commit splitting feature to Fossil, |
| 514 | we’d expect it to be an interactive form of |
| 515 | [`fossil stash apply`][stash], rather than follow Git’s ill-considered |
| 516 | design leads. |
| @@ -603,22 +608,20 @@ | |
| 603 | 2. It provides immediate off-machine backup of your commits. Unlike |
| 604 | centralized version control, though, you can still work while |
| 605 | disconnected; your changes will sync up with the remote once you get |
| 606 | back online. |
| 607 | |
| 608 | 3. Because there is little distinction between the clones in the Fossil |
| 609 | model — unlike in Git, where clones often quickly diverge from each |
| 610 | other, quite possibly on purpose — the backup advantage applies in inverse |
| 611 | as well: if the remote server falls over dead, one of those with a |
| 612 | clone of that repository can stand it back up, and everyone can get |
| 613 | back to work simply by re-pointing their local repo at the new |
| 614 | remote. If the failed remote comes back later, it can sync with the |
| 615 | new central version, then perhaps take over as the primary source of |
| 616 | truth once again. |
| 617 | |
| 618 | (There are caveats to this, [covered elsewhere][bu].) |
| 619 | |
| 620 | [bu]: ./backup.md |
| 621 | [setup]: ./caps/admin-v-setup.md#apsu |
| 622 | [wflow]: ./concepts.wiki#workflow |
| 623 | |
| 624 | |
| @@ -667,11 +670,11 @@ | |
| 667 | [mbgh]: https://github.com/github/renaming |
| 668 | [mirgh]: ./mirrortogithub.md |
| 669 | |
| 670 | |
| 671 | <a id="unmanaged"></a> |
| 672 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 673 | |
| 674 | The "`fossil status`" command shows you what files in your check-out have |
| 675 | been edited and scheduled for adding or removing at the next commit. |
| 676 | But unlike "`git status`", the "`fossil status`" command does not warn |
| 677 | you about unmanaged files in your local check-out. There is a separate |
| @@ -700,38 +703,52 @@ | |
| 700 | [3]: ./rebaseharm.md |
| 701 | |
| 702 | |
| 703 | ## <a id="cdiff"></a> Colorized Diffs |
| 704 | |
| 705 | The graphical diffs in the Fossil web UI and `fossil diff --tk` use |
| 706 | color to distinguish insertions, deletions, and replacements, but unlike |
| 707 | with `git diff` when the output is to an ANSI X3.64 capable terminal, |
| 708 | `fossil diff` does not. |
| 709 | |
| 710 | There are a few easy ways to add this feature to Fossil, though. |
| 711 | |
| 712 | One is to install |
| 713 | [`colordiff`][cdiff], which is included in [many package systems][cdpkg], |
| 714 | then say: |
| 715 | |
| 716 | fossil set --global diff-command 'colordiff -wu' |
| 717 | |
| 718 | Because this is unconditional, unlike `git diff --color=auto`, you will |
| 719 | then have to remember to add the `-i` option to `fossil diff` commands |
| 720 | when you want color disabled, such as when producing `patch(1)` files |
| 721 | or piping diff output to another |
| 722 | command that doesn’t understand ANSI escape sequences. There’s an |
| 723 | example of this [below](#dstat). |
| 724 | |
| 725 | Another way, which avoids this problem, is to say instead: |
| 726 | |
| 727 | fossil set --global diff-command 'git diff --no-index' |
| 728 | |
| 729 | This delegates `fossil diff` to `git diff` by using the latter’s |
| 730 | ability to run on files not inside any repository. |
| 731 | |
| 732 | [cdpkg]: https://repology.org/project/colordiff/versions |
| 733 | |
| 734 | |
| 735 | ## <a id="show"></a> Showing Information About Commits |
| 736 | |
| 737 | While there is no direct equivalent to Git’s “`show`” command, similar |
| @@ -746,11 +763,11 @@ | |
| 746 | |
| 747 | fossil diff --checkin COMMIT_ID |
| 748 | |
| 749 | …only without the patch email header. Git comes out of the [LKML] world, |
| 750 | where emailing a patch is a normal thing to do. Fossil is [designed for |
| 751 | cohesive teams][devorg] where such drive-by patches are rarer. |
| 752 | |
| 753 | You can use any of [Fossil’s special check-in names][scin] in place of |
| 754 | the `COMMIT_ID` in this and later examples. Fossil docs usually say |
| 755 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 756 | or name might not refer to a commit ID, but instead to a forum post, a |
| @@ -812,18 +829,18 @@ | |
| 812 | [dcset]: https://fossil-scm.org/home/help?cmd=diff-command |
| 813 | [dst]: https://invisible-island.net/diffstat/diffstat.html |
| 814 | |
| 815 | |
| 816 | <a id="btnames"></a> |
| 817 | ## Branch And Tag Names |
| 818 | |
| 819 | Fossil has no special restrictions on the names of tags and branches, |
| 820 | though you might want to keep [Git's tag and branch name restrictions][gcrf] |
| 821 | in mind if you plan on [mirroring your Fossil repository to GitHub][mirgh]. |
| 822 | |
| 823 | Fossil does not require tag and branch names to be unique. It is |
| 824 | common, for example, to put a "`release`" tag on every release for a |
| 825 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 826 | Fossil resolves the ambiguity in a predictable way: the newest match |
| 827 | wins. Therefore, “`fossil up release`” always gets you the current |
| 828 | release in a project that uses this tagging convention. |
| 829 | |
| @@ -837,25 +854,26 @@ | |
| 837 | |
| 838 | |
| 839 | |
| 840 | |
| 841 | <a id="cpickrev"></a> |
| 842 | ## Cherry-Picking And Reverting Commits |
| 843 | |
| 844 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 845 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 846 | `--backout`, respectively. |
| 847 | |
| 848 | Unlike in Git, the Fossil file format remembers cherrypicks and backouts |
| 849 | and can later show them as dashed lines on the graphical timeline. |
| 850 | |
| 851 | [merge]: /help?cmd=merge |
| 852 | |
| 853 | |
| 854 | |
| 855 | <a id="mvrm"></a> |
| 856 | ## File Moves And Renames Are Soft By Default |
| 857 | |
| 858 | The "[`fossil mv`][mv]" and "[`fossil rm`][rm]" commands work like they |
| 859 | do in CVS in that they schedule the changes for the next commit by |
| 860 | default: they do not actually rename or delete the files in your |
| 861 | check-out. |
| 862 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -40,29 +40,30 @@ | |
| 40 | [ffor]: https://fossil-scm.org/forum |
| 41 | [fvg]: ./fossil-v-git.wiki |
| 42 | |
| 43 | |
| 44 | <a id="mwd"></a> |
| 45 | ## Repositories and Checkouts Are Distinct |
| 46 | |
| 47 | A repository and a check-out are distinct in Fossil, allowing them to be |
| 48 | stored in separate directory trees, whereas the two are commingled by |
| 49 | default with Git, with the repository stored in a `.git` subdirectory |
| 50 | underneath your working directory. This difference shows up in several |
| 51 | separate places when it comes to moving from Git to Fossil. |
| 52 | |
| 53 | |
| 54 | |
| 55 | #### <a id="cwork" name="scw"></a> Checkout Workflows |
| 56 | |
| 57 | A Fossil repository is a SQLite database storing the entire history of a |
| 58 | project. It is not normally stored inside the working tree. |
| 59 | A Fossil working tree — [also called a check-out](./glossary.md#check-out) — is a directory |
| 60 | that contains a snapshot of your project that you are currently working |
| 61 | on, extracted for you from the repository database file by the `fossil` |
| 62 | program. |
| 63 | |
| 64 | There are ways to |
| 65 | [emulate the Fossil working style in Git](#worktree), but because they’re not |
| 66 | designed into the core concept of the tool, Git tutorials usually |
| 67 | advocate a switch-in-place working mode instead, so that is how most |
| 68 | users end up working with Git. Contrast [Fossil’s check-out workflow |
| 69 | document][ckwf] to see the practical differences. |
| @@ -113,11 +114,11 @@ | |
| 114 | |
| 115 | Someone coming from the Git perspective may perceive that `fossil up` |
| 116 | has two purposes: |
| 117 | |
| 118 | * Without the optional `VERSION` argument, it updates the working |
| 119 | check-out to the tip of the current branch, as `git pull` does. |
| 120 | |
| 121 | * Given a `VERSION` argument, it updates to the named version. If that’s the |
| 122 | name of a branch, it updates to the *tip* of that branch, as |
| 123 | `git checkout BRANCH` does. |
| 124 | |
| @@ -196,14 +197,16 @@ | |
| 197 | mkdir ../foo-branch |
| 198 | cd ../foo-branch |
| 199 | fossil open /path/to/repo.fossil foo-branch |
| 200 | |
| 201 | The Fossil alternative is wordier, but this tends to be one-time setup, |
| 202 | not something you do everyday. This author keeps a “scratch” check-out |
| 203 | for cases where is isn’t appropriate to reuse the “trunk” check-out, |
| 204 | isolating all of my expedient switch-in-place actions to that one |
| 205 | working directory. Since the other peer check-out track long-lived |
| 206 | branches, and that set rarely changes once a development machine is set |
| 207 | up, I rarely pay the cost of these wordier commands. |
| 208 | |
| 209 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 210 | check-out](#close): |
| 211 | |
| 212 | git worktree remove . |
| @@ -298,11 +301,13 @@ | |
| 301 | to produce its [timeline CLI][tlc] and [its `/timeline` web view][tlw] |
| 302 | using indexed SQL lookups, which generally have the info you would have |
| 303 | to manually extract from `git log`, produced much more quickly than Git |
| 304 | can, all else being equal: operations over [SQLite’s B-tree data structures][btree] |
| 305 | generally run in O(log n) time, faster than O(n) for equal *n* when the |
| 306 | constants are equal. |
| 307 | |
| 308 | Yet the constants are *not* equal because Fossil |
| 309 | reads from a single disk file rather than visit potentially many |
| 310 | files in sequence as Git must, so the OS’s buffer cache can result in |
| 311 | [still better performance][35pct]. |
| 312 | |
| 313 | Unlike Git’s log, Fossil’s timeline shows info across branches by |
| @@ -430,18 +435,18 @@ | |
| 435 | [wdm]: ./fossil-v-git.wiki#durable |
| 436 | |
| 437 | |
| 438 | ## <a id="dhead"></a> Detached HEAD State |
| 439 | |
| 440 | The SQL indexes in Fossil which we brought up above have a useful |
| 441 | side benefit: you cannot have a [detached HEAD state][gdh] in Fossil, |
| 442 | the source of untold pain and data loss in Git. It simply cannot be done |
| 443 | in Fossil, because the indexes always let us find our way back into the |
| 444 | hash tree. |
| 445 | |
| 446 | |
| 447 | ## <a id="slcom"></a> Summary Line Convention in Commit Comments |
| 448 | |
| 449 | The Git convention of a [length-limited summary line][lsl] at the start |
| 450 | of commit comments is not enforced or obeyed by default in Fossil. |
| 451 | However, there is a setting under Admin → Timeline → “Truncate comment |
| 452 | at first blank line (Git-style)” to change this for `/timeline` |
| @@ -506,11 +511,11 @@ | |
| 511 | but we’d rather make changes only to the working directory, test the |
| 512 | changes there, and only commit once we’re sure it’s right. |
| 513 | |
| 514 | This also explains why we don’t have anything like `git rebase -i` |
| 515 | to split an existing commit: in Fossil, commits are *commitments,* not |
| 516 | something you’re allowed to go back and rewrite later. |
| 517 | |
| 518 | If someone does [contribute][ctrb] a commit splitting feature to Fossil, |
| 519 | we’d expect it to be an interactive form of |
| 520 | [`fossil stash apply`][stash], rather than follow Git’s ill-considered |
| 521 | design leads. |
| @@ -603,22 +608,20 @@ | |
| 608 | 2. It provides immediate off-machine backup of your commits. Unlike |
| 609 | centralized version control, though, you can still work while |
| 610 | disconnected; your changes will sync up with the remote once you get |
| 611 | back online. |
| 612 | |
| 613 | 3. Because there is [little distinction][bu] between the clones in the Fossil |
| 614 | model — unlike in Git, where clones often quickly diverge from each |
| 615 | other, quite possibly on purpose — the backup advantage applies in inverse |
| 616 | as well: if the remote server falls over dead, one of those with a |
| 617 | clone of that repository can stand it back up, and everyone can get |
| 618 | back to work simply by re-pointing their local repo at the new |
| 619 | remote. If the failed remote comes back later, it can sync with the |
| 620 | new central version, then perhaps take over as the primary source of |
| 621 | truth once again. |
| 622 | |
| 623 | [bu]: ./backup.md |
| 624 | [setup]: ./caps/admin-v-setup.md#apsu |
| 625 | [wflow]: ./concepts.wiki#workflow |
| 626 | |
| 627 | |
| @@ -667,11 +670,11 @@ | |
| 670 | [mbgh]: https://github.com/github/renaming |
| 671 | [mirgh]: ./mirrortogithub.md |
| 672 | |
| 673 | |
| 674 | <a id="unmanaged"></a> |
| 675 | ## Status Does Not Show Unmanaged Files |
| 676 | |
| 677 | The "`fossil status`" command shows you what files in your check-out have |
| 678 | been edited and scheduled for adding or removing at the next commit. |
| 679 | But unlike "`git status`", the "`fossil status`" command does not warn |
| 680 | you about unmanaged files in your local check-out. There is a separate |
| @@ -700,38 +703,52 @@ | |
| 703 | [3]: ./rebaseharm.md |
| 704 | |
| 705 | |
| 706 | ## <a id="cdiff"></a> Colorized Diffs |
| 707 | |
| 708 | When you run `git diff` on an ANSI X3.64 capable terminal, it uses color |
| 709 | to distinguish insertions, deletions, and replacements, but as of this |
| 710 | writing, `fossil diff` produces traditional uncolored [unified diff |
| 711 | format][udiff] output, suitable for producing a [patch file][pfile]. |
| 712 | |
| 713 | Nevertheless, there are multiple ways to get colorized diff output from |
| 714 | Fossil: |
| 715 | |
| 716 | * The most direct method is to delegate diff behavior back to Git: |
| 717 | |
| 718 | fossil set --global diff-command 'git diff --no-index' |
| 719 | |
| 720 | The flag permits it to diff files that aren’t inside a Git repository. |
| 721 | |
| 722 | * Another method is to install [`colordiff`][cdiff] — included in |
| 723 | [many package systems][cdpkg] — then say: |
| 724 | |
| 725 | fossil set --global diff-command 'colordiff -wu' |
| 726 | |
| 727 | Because this is unconditional, unlike `git diff --color=auto`, you |
| 728 | will then have to remember to add the `-i` option to `fossil diff` |
| 729 | commands when you want color disabled, such as when producing |
| 730 | `patch(1)` files or piping diff output to another command that |
| 731 | doesn’t understand ANSI escape sequences. There’s an example of this |
| 732 | [below](#dstat). |
| 733 | |
| 734 | * Use the Fossil web UI to diff existing commits. |
| 735 | |
| 736 | * To diff the current working directory contents against some parent |
| 737 | instead, Fossil 2.17 expanded the diff command so it can produce |
| 738 | colorized HTML output and open it in the OS’s default web browser. |
| 739 | For example, `fossil diff -by` will show side-by-side diffs. |
| 740 | |
| 741 | * Use the older `fossil diff --tk` option to do much the same using |
| 742 | Tcl/Tk instead of a browser. |
| 743 | |
| 744 | Viewed this way, Fossil doesn’t lack colorized diffs, it simply has |
| 745 | *one* method where they *aren’t* colorized. |
| 746 | |
| 747 | [cdpkg]: https://repology.org/project/colordiff/versions |
| 748 | [pfile]: https://en.wikipedia.org/wiki/Patch_(Unix) |
| 749 | [udiff]: https://en.wikipedia.org/wiki/Diff#Unified_format |
| 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 |
| @@ -746,11 +763,11 @@ | |
| 763 | |
| 764 | fossil diff --checkin COMMIT_ID |
| 765 | |
| 766 | …only without the patch email header. Git comes out of the [LKML] world, |
| 767 | where emailing a patch is a normal thing to do. Fossil is [designed for |
| 768 | cohesive teams][devorg] where drive-by patches are rarer. |
| 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 |
| @@ -812,18 +829,18 @@ | |
| 829 | [dcset]: https://fossil-scm.org/home/help?cmd=diff-command |
| 830 | [dst]: https://invisible-island.net/diffstat/diffstat.html |
| 831 | |
| 832 | |
| 833 | <a id="btnames"></a> |
| 834 | ## Branch and Tag Names |
| 835 | |
| 836 | Fossil has no special restrictions on the names of tags and branches, |
| 837 | though you might want to keep [Git's tag and branch name restrictions][gcrf] |
| 838 | in mind if you plan on [mirroring your Fossil repository to GitHub][mirgh]. |
| 839 | |
| 840 | Fossil does not require tag and branch names to be unique. It is |
| 841 | common, for example, to put a “`release`” tag on every release for a |
| 842 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 843 | Fossil resolves the ambiguity in a predictable way: the newest match |
| 844 | wins. Therefore, “`fossil up release`” always gets you the current |
| 845 | release in a project that uses this tagging convention. |
| 846 | |
| @@ -837,25 +854,26 @@ | |
| 854 | |
| 855 | |
| 856 | |
| 857 | |
| 858 | <a id="cpickrev"></a> |
| 859 | ## Cherry-Picking and Reverting Commits |
| 860 | |
| 861 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 862 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 863 | `--backout`, respectively. We view this as sensible, since these are |
| 864 | both merge operations, and the two actions differ only in direction. |
| 865 | |
| 866 | Unlike in Git, the Fossil file format remembers cherrypicks and backouts |
| 867 | and can later show them as dashed lines on the graphical timeline. |
| 868 | |
| 869 | [merge]: /help?cmd=merge |
| 870 | |
| 871 | |
| 872 | |
| 873 | <a id="mvrm"></a> |
| 874 | ## File Moves and Renames Are Soft by Default |
| 875 | |
| 876 | The "[`fossil mv`][mv]" and "[`fossil rm`][rm]" commands work like they |
| 877 | do in CVS in that they schedule the changes for the next commit by |
| 878 | default: they do not actually rename or delete the files in your |
| 879 | check-out. |
| 880 |