Fossil SCM
In response to [forum:/forumpost/6878c949a5c33551 | a recent forum thread], added a new section to the gitusers doc, "Fossil Never Auto-Commits". The ideas behind this were previously expressed implicitly, but con-fused with others, resulting in the lack of clarity characteristic of alchemical slag. Put the new section before "There Is No Staging Area" as that follows on from these ideas, then calved off the subsequent section "Commit Splitting" because it covers related but separate ideas. Together, these three form a conceptual whole that is considerably clearer than the prior presentation.
Commit
5f5452f110719caf5342bf584d6b3568d7f48a1fb06a358a603595d197f214c5
Parent
50a8a1bb707ba46…
1 file changed
+49
-21
+49
-21
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -457,28 +457,67 @@ | ||
| 457 | 457 | |
| 458 | 458 | [cskin]: ./customskin.md |
| 459 | 459 | [lsl]: https://chris.beams.io/posts/git-commit/#limit-50 |
| 460 | 460 | |
| 461 | 461 | |
| 462 | +<a id="autocommit"></a> | |
| 463 | +## Fossil Never Auto-Commits | |
| 464 | + | |
| 465 | +There are several features in Git besides its `commit` command that | |
| 466 | +produce a new commit to the repository, and by default, they do it | |
| 467 | +without prompting or even asking for a commit message. These include | |
| 468 | +Git’s [`rebase`](#rebase), `merge`, and [`cherrypick`](#cpickrev) | |
| 469 | +commands, plus the [commit splitting](#comsplit) sub-feature | |
| 470 | +“`git commit -p`”. | |
| 471 | + | |
| 472 | +Fossil never does this, on firm philosophical grounds: we wish to be | |
| 473 | +able to test that each potentially repository-changing command does not | |
| 474 | +break anything _before_ freezing it immutably into the [Merkle | |
| 475 | +tree](./blockchain.md). Where Fossil has equivalent commands, they | |
| 476 | +modify the checkout tree alone, requiring a separate `commit` command | |
| 477 | +afterward, withheld until the user has satisfied themselves that the | |
| 478 | +command’s result is correct. | |
| 479 | + | |
| 480 | +We believe this is the main reason Git lacks an [autosync](#autosync) | |
| 481 | +feature: making push a manual step gives the user a chance to rewrite | |
| 482 | +history after triggering one of these autocommits locally, should the | |
| 483 | +automatic commit fail to work out as expected. Fossil chooses the | |
| 484 | +inverse path under the philosophy that commits are *commitments,* not | |
| 485 | +something you’re allowed to go back and rewrite later. | |
| 486 | + | |
| 487 | +This is also why there is no automatic commit message writing feature in | |
| 488 | +Fossil, as in these autocommit-triggering Git commands. The user is | |
| 489 | +meant to write the commit message by hand after they are sure it’s | |
| 490 | +correct, in clear-headed retrospective fashion. Having the tool do it | |
| 491 | +prospectively before one can test the result is simply backwards. | |
| 492 | + | |
| 462 | 493 | |
| 463 | 494 | <a id="staging"></a> |
| 464 | 495 | ## There Is No Staging Area |
| 465 | 496 | |
| 466 | 497 | Fossil omits the "Git index" or "staging area" concept. When you |
| 467 | 498 | type "`fossil commit`" _all_ changes in your check-out are committed, |
| 468 | -automatically. There is no need for the "-a" option as with Git. | |
| 499 | +by default. There is no need for the "-a" option as with Git. | |
| 469 | 500 | |
| 470 | 501 | If you only want to commit _some_ of the changes, list the names |
| 471 | 502 | of the files or directories you want to commit as arguments, like this: |
| 472 | 503 | |
| 473 | 504 | fossil commit src/feature.c doc/feature.md examples/feature |
| 474 | 505 | |
| 475 | 506 | Note that the last element is a directory name, meaning “any changed |
| 476 | 507 | file under the `examples/feature` directory.” |
| 477 | 508 | |
| 478 | -Although there are currently no | |
| 479 | -<a id="csplit"></a>[commit splitting][gcspl] features in Fossil like | |
| 509 | + | |
| 510 | +<a id="comsplit"></a> | |
| 511 | +## Commit Splitting | |
| 512 | + | |
| 513 | +<a id="csplit"></a>[Git’s commit splitting features][gcspl] rely on | |
| 514 | +other features of Git that Fossil purposefully lacks, as covered in the | |
| 515 | +prior two sections: [autocommit](#autocommit) and [the staging | |
| 516 | +area](#staging). | |
| 517 | + | |
| 518 | +While there is no direct Fossil equivalent for | |
| 480 | 519 | `git add -p`, `git commit -p`, or `git rebase -i`, you can get the same |
| 481 | 520 | effect by converting an uncommitted change set to a patch and then |
| 482 | 521 | running it through [Patchouli]. |
| 483 | 522 | |
| 484 | 523 | Rather than use `fossil diff -i` to produce such a patch, a safer and |
| @@ -494,28 +533,17 @@ | ||
| 494 | 533 | hunks already applied. |
| 495 | 534 | |
| 496 | 535 | In this way, the combination of working tree and stash replaces the need |
| 497 | 536 | for Git’s index feature. |
| 498 | 537 | |
| 499 | -This also solves a philosophical problem with `git commit -p`: how can | |
| 500 | -you test that a split commit doesn’t break anything if you do it as part | |
| 501 | -of the commit action? Git’s lack of an autosync feature means you can | |
| 502 | -commit locally and then rewrite history if the commit doesn’t work out, | |
| 503 | -but we’d rather make changes only to the working directory, test the | |
| 504 | -changes there, and only commit once we’re sure it’s right. | |
| 505 | - | |
| 506 | -This also explains why we don’t have anything like `git rebase -i` | |
| 507 | -to split an existing commit: in Fossil, commits are *commitments,* not | |
| 508 | -something you’re allowed to go back and rewrite later. | |
| 509 | - | |
| 510 | -If someone does [contribute][ctrb] a commit splitting feature to Fossil, | |
| 511 | -we’d expect it to be an interactive form of | |
| 512 | -[`fossil stash apply`][stash], rather than follow Git’s ill-considered | |
| 513 | -design leads. | |
| 514 | - | |
| 515 | -Until then, there’s the third-party tool [`fnc`][fnc] and | |
| 516 | -[its interactive `stash` command][fncsta]. | |
| 538 | +We believe we know how to do commit splitting in a way compatible with | |
| 539 | +the Fossil philosophy, without following Git’s ill-considered design | |
| 540 | +leads. It amounts to automating the above process through an interactive | |
| 541 | +variant of [`fossil stash apply`][stash], as currently prototyped in the | |
| 542 | +third-party tool [`fnc`][fnc] and [its interactive `stash` | |
| 543 | +command][fncsta]. We merely await someone’s [contribution][ctrb] of this | |
| 544 | +feature into Fossil proper. | |
| 517 | 545 | |
| 518 | 546 | [ctrb]: https://fossil-scm.org/fossil/doc/trunk/www/contribute.wiki |
| 519 | 547 | [fnc]: https://fnc.bsdbox.org/ |
| 520 | 548 | [fncsta]: https://fnc.bsdbox.org/uv/doc/fnc.1.html#stash |
| 521 | 549 | [gcspl]: https://git-scm.com/docs/git-rebase#_splitting_commits |
| 522 | 550 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -457,28 +457,67 @@ | |
| 457 | |
| 458 | [cskin]: ./customskin.md |
| 459 | [lsl]: https://chris.beams.io/posts/git-commit/#limit-50 |
| 460 | |
| 461 | |
| 462 | |
| 463 | <a id="staging"></a> |
| 464 | ## There Is No Staging Area |
| 465 | |
| 466 | Fossil omits the "Git index" or "staging area" concept. When you |
| 467 | type "`fossil commit`" _all_ changes in your check-out are committed, |
| 468 | automatically. There is no need for the "-a" option as with Git. |
| 469 | |
| 470 | If you only want to commit _some_ of the changes, list the names |
| 471 | of the files or directories you want to commit as arguments, like this: |
| 472 | |
| 473 | fossil commit src/feature.c doc/feature.md examples/feature |
| 474 | |
| 475 | Note that the last element is a directory name, meaning “any changed |
| 476 | file under the `examples/feature` directory.” |
| 477 | |
| 478 | Although there are currently no |
| 479 | <a id="csplit"></a>[commit splitting][gcspl] features in Fossil like |
| 480 | `git add -p`, `git commit -p`, or `git rebase -i`, you can get the same |
| 481 | effect by converting an uncommitted change set to a patch and then |
| 482 | running it through [Patchouli]. |
| 483 | |
| 484 | Rather than use `fossil diff -i` to produce such a patch, a safer and |
| @@ -494,28 +533,17 @@ | |
| 494 | hunks already applied. |
| 495 | |
| 496 | In this way, the combination of working tree and stash replaces the need |
| 497 | for Git’s index feature. |
| 498 | |
| 499 | This also solves a philosophical problem with `git commit -p`: how can |
| 500 | you test that a split commit doesn’t break anything if you do it as part |
| 501 | of the commit action? Git’s lack of an autosync feature means you can |
| 502 | commit locally and then rewrite history if the commit doesn’t work out, |
| 503 | but we’d rather make changes only to the working directory, test the |
| 504 | changes there, and only commit once we’re sure it’s right. |
| 505 | |
| 506 | This also explains why we don’t have anything like `git rebase -i` |
| 507 | to split an existing commit: in Fossil, commits are *commitments,* not |
| 508 | something you’re allowed to go back and rewrite later. |
| 509 | |
| 510 | If someone does [contribute][ctrb] a commit splitting feature to Fossil, |
| 511 | we’d expect it to be an interactive form of |
| 512 | [`fossil stash apply`][stash], rather than follow Git’s ill-considered |
| 513 | design leads. |
| 514 | |
| 515 | Until then, there’s the third-party tool [`fnc`][fnc] and |
| 516 | [its interactive `stash` command][fncsta]. |
| 517 | |
| 518 | [ctrb]: https://fossil-scm.org/fossil/doc/trunk/www/contribute.wiki |
| 519 | [fnc]: https://fnc.bsdbox.org/ |
| 520 | [fncsta]: https://fnc.bsdbox.org/uv/doc/fnc.1.html#stash |
| 521 | [gcspl]: https://git-scm.com/docs/git-rebase#_splitting_commits |
| 522 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -457,28 +457,67 @@ | |
| 457 | |
| 458 | [cskin]: ./customskin.md |
| 459 | [lsl]: https://chris.beams.io/posts/git-commit/#limit-50 |
| 460 | |
| 461 | |
| 462 | <a id="autocommit"></a> |
| 463 | ## Fossil Never Auto-Commits |
| 464 | |
| 465 | There are several features in Git besides its `commit` command that |
| 466 | produce a new commit to the repository, and by default, they do it |
| 467 | without prompting or even asking for a commit message. These include |
| 468 | Git’s [`rebase`](#rebase), `merge`, and [`cherrypick`](#cpickrev) |
| 469 | commands, plus the [commit splitting](#comsplit) sub-feature |
| 470 | “`git commit -p`”. |
| 471 | |
| 472 | Fossil never does this, on firm philosophical grounds: we wish to be |
| 473 | able to test that each potentially repository-changing command does not |
| 474 | break anything _before_ freezing it immutably into the [Merkle |
| 475 | tree](./blockchain.md). Where Fossil has equivalent commands, they |
| 476 | modify the checkout tree alone, requiring a separate `commit` command |
| 477 | afterward, withheld until the user has satisfied themselves that the |
| 478 | command’s result is correct. |
| 479 | |
| 480 | We believe this is the main reason Git lacks an [autosync](#autosync) |
| 481 | feature: making push a manual step gives the user a chance to rewrite |
| 482 | history after triggering one of these autocommits locally, should the |
| 483 | automatic commit fail to work out as expected. Fossil chooses the |
| 484 | inverse path under the philosophy that commits are *commitments,* not |
| 485 | something you’re allowed to go back and rewrite later. |
| 486 | |
| 487 | This is also why there is no automatic commit message writing feature in |
| 488 | Fossil, as in these autocommit-triggering Git commands. The user is |
| 489 | meant to write the commit message by hand after they are sure it’s |
| 490 | correct, in clear-headed retrospective fashion. Having the tool do it |
| 491 | prospectively before one can test the result is simply backwards. |
| 492 | |
| 493 | |
| 494 | <a id="staging"></a> |
| 495 | ## There Is No Staging Area |
| 496 | |
| 497 | Fossil omits the "Git index" or "staging area" concept. When you |
| 498 | type "`fossil commit`" _all_ changes in your check-out are committed, |
| 499 | by default. There is no need for the "-a" option as with Git. |
| 500 | |
| 501 | If you only want to commit _some_ of the changes, list the names |
| 502 | of the files or directories you want to commit as arguments, like this: |
| 503 | |
| 504 | fossil commit src/feature.c doc/feature.md examples/feature |
| 505 | |
| 506 | Note that the last element is a directory name, meaning “any changed |
| 507 | file under the `examples/feature` directory.” |
| 508 | |
| 509 | |
| 510 | <a id="comsplit"></a> |
| 511 | ## Commit Splitting |
| 512 | |
| 513 | <a id="csplit"></a>[Git’s commit splitting features][gcspl] rely on |
| 514 | other features of Git that Fossil purposefully lacks, as covered in the |
| 515 | prior two sections: [autocommit](#autocommit) and [the staging |
| 516 | area](#staging). |
| 517 | |
| 518 | While there is no direct Fossil equivalent for |
| 519 | `git add -p`, `git commit -p`, or `git rebase -i`, you can get the same |
| 520 | effect by converting an uncommitted change set to a patch and then |
| 521 | running it through [Patchouli]. |
| 522 | |
| 523 | Rather than use `fossil diff -i` to produce such a patch, a safer and |
| @@ -494,28 +533,17 @@ | |
| 533 | hunks already applied. |
| 534 | |
| 535 | In this way, the combination of working tree and stash replaces the need |
| 536 | for Git’s index feature. |
| 537 | |
| 538 | We believe we know how to do commit splitting in a way compatible with |
| 539 | the Fossil philosophy, without following Git’s ill-considered design |
| 540 | leads. It amounts to automating the above process through an interactive |
| 541 | variant of [`fossil stash apply`][stash], as currently prototyped in the |
| 542 | third-party tool [`fnc`][fnc] and [its interactive `stash` |
| 543 | command][fncsta]. We merely await someone’s [contribution][ctrb] of this |
| 544 | feature into Fossil proper. |
| 545 | |
| 546 | [ctrb]: https://fossil-scm.org/fossil/doc/trunk/www/contribute.wiki |
| 547 | [fnc]: https://fnc.bsdbox.org/ |
| 548 | [fncsta]: https://fnc.bsdbox.org/uv/doc/fnc.1.html#stash |
| 549 | [gcspl]: https://git-scm.com/docs/git-rebase#_splitting_commits |
| 550 |