Fossil SCM
Edit pass on gituser.md.
Commit
dd3dd23965c4a3241b503cbb5210ed564cae8c8ebaa9cf682401417bd6bdae0a
Parent
a1626b30285d738…
1 file changed
+48
-35
+48
-35
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -210,15 +210,15 @@ | ||
| 210 | 210 | |
| 211 | 211 | fossil clone https://example.com/repo |
| 212 | 212 | |
| 213 | 213 | It’s a shorter command because we deduce `repo.fossil` and the `repo/` |
| 214 | 214 | working directory from the last element of the path in the URI. If you |
| 215 | -wanted to override both inferences, you’d say: | |
| 215 | +wanted to override both deductions, you’d say: | |
| 216 | 216 | |
| 217 | 217 | fossil clone --workdir foo https://example.com/repo/bar |
| 218 | 218 | |
| 219 | -That gets you `bar.fossil` with a `foo/` working directory. | |
| 219 | +That gets you `bar.fossil` with a `foo/` working directory alongside it. | |
| 220 | 220 | |
| 221 | 221 | [mcw]: ./ckout-workflows.md#mcw |
| 222 | 222 | [wsyml]: https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/ |
| 223 | 223 | |
| 224 | 224 | |
| @@ -271,11 +271,11 @@ | ||
| 271 | 271 | [server]: /help?cmd=server |
| 272 | 272 | [stash]: /help?cmd=stash |
| 273 | 273 | [undo]: /help?cmd=undo |
| 274 | 274 | |
| 275 | 275 | |
| 276 | -## <a id="log"></a> Fossil’s Timeline is the “Log” | |
| 276 | +## <a id="log"></a> Fossil’s Timeline Is The “Log” | |
| 277 | 277 | |
| 278 | 278 | Git users often need to use the `git log` command to dig linearly through |
| 279 | 279 | commit histories due to its [weak data model][wdm]. |
| 280 | 280 | |
| 281 | 281 | Fossil parses a huge amount of information out of commits that allow it |
| @@ -367,11 +367,11 @@ | ||
| 367 | 367 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 368 | 368 | adding commits to the tip of that branch. |
| 369 | 369 | |
| 370 | 370 | To switch back to the parent branch, say something like: |
| 371 | 371 | |
| 372 | - fossil update trunk # like “git checkout” | |
| 372 | + fossil update trunk # ≅ git checkout master | |
| 373 | 373 | |
| 374 | 374 | Fossil does also support the Git style, creating the branch ahead of |
| 375 | 375 | need: |
| 376 | 376 | |
| 377 | 377 | fossil branch new my-new-branch |
| @@ -387,13 +387,14 @@ | ||
| 387 | 387 | *after* you commit it, using the "`fossil amend`" command. |
| 388 | 388 | For example: |
| 389 | 389 | |
| 390 | 390 | fossil amend current --branch my-new-branch |
| 391 | 391 | |
| 392 | -(“current” is one of the [special check-in names][scin] in Fossil. See | |
| 392 | +(The version string “current” is one of the [special check-in names][scin] in Fossil. See | |
| 393 | 393 | that document for the many other names you can give to “`amend`”, or |
| 394 | -indeed to any other Fossil command that accepts a “version” string.) | |
| 394 | +indeed to any other Fossil command documented to accept a `VERSION` or | |
| 395 | +`NAME` string.) | |
| 395 | 396 | |
| 396 | 397 | [scin]: ./checkin_names.wiki |
| 397 | 398 | |
| 398 | 399 | |
| 399 | 400 | <a id="autosync"></a> |
| @@ -444,44 +445,49 @@ | ||
| 444 | 445 | |
| 445 | 446 | <a id="syncall"></a> |
| 446 | 447 | ## Sync Is All-Or-Nothing |
| 447 | 448 | |
| 448 | 449 | Fossil does not support the concept of syncing, pushing, or pulling |
| 449 | -individual branches. When you sync/push/pull in Fossil, you | |
| 450 | -sync/push/pull everything stored as artifacts in its hash tree: | |
| 450 | +individual branches. When you sync/push/pull in Fossil, it | |
| 451 | +processes all artifacts in its hash tree: | |
| 451 | 452 | branches, tags, wiki articles, tickets, forum posts, technotes… |
| 452 | -[Almost everything][bu]. | |
| 453 | +This is [not quite “everything,” full stop][bu], but it’s close. | |
| 453 | 454 | |
| 454 | 455 | Furthermore, branch *names* sync automatically in Fossil, not just the |
| 455 | -content of those branches. This means this common Git command: | |
| 456 | +content of those branches. That means this common Git command: | |
| 456 | 457 | |
| 457 | 458 | git push origin master |
| 458 | 459 | |
| 459 | 460 | is simply this in Fossil: |
| 460 | 461 | |
| 461 | 462 | fossil push |
| 462 | 463 | |
| 463 | 464 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 464 | -keeps using the same remote server URL and branch name you gave it last, | |
| 465 | -until you tell it to do something different. | |
| 465 | +keeps using the same remote server URL you gave it last | |
| 466 | +until you [tell it to do something different][rem], and it pushes all | |
| 467 | +branches, not just one named local branch. | |
| 468 | + | |
| 469 | +[rem]: /help?cmd=remote | |
| 466 | 470 | |
| 467 | 471 | |
| 468 | 472 | <a id="trunk"></a> |
| 469 | 473 | ## The Main Branch Is Called "`trunk`" |
| 470 | 474 | |
| 471 | -In Fossil, the traditional name and the default name for the main branch | |
| 475 | +In Fossil, the default name for the main branch | |
| 472 | 476 | is "`trunk`". The "`trunk`" branch in Fossil corresponds to the |
| 473 | -"`master`" branch in stock Git or the "`main`" branch in GitHub. | |
| 477 | +"`master`" branch in stock Git or to [the “`main`” branch in GitHub][mbgh]. | |
| 474 | 478 | |
| 475 | 479 | Because the `fossil git export` command has to work with both stock Git |
| 476 | -and with GitHub, Fossil uses Git’s default: your Fossil repo’s “trunk” | |
| 477 | -branch becomes “master” on GitHub, not “main,” as in new GitHub repos. | |
| 478 | -It is not known what happens on subsequent exports if you | |
| 479 | -[later rename it][ghmain]. | |
| 480 | +and with GitHub, Fossil uses Git’s traditional default rather than | |
| 481 | +GitHub’s new default: your Fossil repo’s “trunk” branch becomes “master” | |
| 482 | +when [mirroring to GitHub][mirgh], not “main.” | |
| 480 | 483 | |
| 481 | -[6]: ./mirrortogithub.md | |
| 482 | -[ghmain]: https://github.com/github/renaming | |
| 484 | +We do not know what happens on subsequent exports if you later rename | |
| 485 | +this branch on the GitHub side. | |
| 486 | + | |
| 487 | +[mbgh]: https://github.com/github/renaming | |
| 488 | +[mirgh]: ./mirrortogithub.md | |
| 483 | 489 | |
| 484 | 490 | |
| 485 | 491 | <a id="unmanaged"></a> |
| 486 | 492 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 487 | 493 | |
| @@ -548,11 +554,11 @@ | ||
| 548 | 554 | |
| 549 | 555 | …is |
| 550 | 556 | |
| 551 | 557 | fossil time -n 1 COMMIT_ID |
| 552 | 558 | |
| 553 | -…or with a shorter, more obvious command, with more verbose output: | |
| 559 | +…or with a shorter, more obvious command with more verbose output: | |
| 554 | 560 | |
| 555 | 561 | fossil info COMMIT_ID |
| 556 | 562 | |
| 557 | 563 | The `fossil info` command isn’t otherwise a good equivalent to |
| 558 | 564 | `git show`. It just overlaps its functionality in some areas. Much of |
| @@ -590,41 +596,49 @@ | ||
| 590 | 596 | |
| 591 | 597 | …which you can approximate in Fossil as: |
| 592 | 598 | |
| 593 | 599 | fossil pull |
| 594 | 600 | fossil diff --from tip |
| 601 | + | |
| 602 | +…plus… | |
| 603 | + | |
| 595 | 604 | fossil timeline after current |
| 596 | 605 | |
| 597 | 606 | Note the use of [human-readable symbolic version names][scin] rather than |
| 598 | -cryptic notations. | |
| 607 | +cryptic notations. (But if you like brief commands, you can abbreviate | |
| 608 | +it as `fossil tim after curr`.) | |
| 599 | 609 | |
| 600 | -To invert the diff direction of the second command, say: | |
| 610 | +To invert the direction of the `diff` command above, say instead: | |
| 601 | 611 | |
| 602 | 612 | fossil diff --from current --to tip |
| 603 | 613 | |
| 604 | -You can abbreviate the last command as `fossil tim after curr`. | |
| 605 | - | |
| 606 | 614 | |
| 607 | 615 | <a id="btnames"></a> |
| 608 | -## Branch and Tag Names | |
| 616 | +## Branch And Tag Names | |
| 609 | 617 | |
| 610 | 618 | Fossil has no special restrictions on the names of tags and branches, |
| 611 | -though you might want to keep [Git's tag and branch name restrictions][4] | |
| 612 | -in mind if you plan on mirroring your Fossil repository to GitHub. | |
| 613 | - | |
| 614 | -[4]: https://git-scm.com/docs/git-check-ref-format | |
| 619 | +though you might want to keep [Git's tag and branch name restrictions][gcrf] | |
| 620 | +in mind if you plan on [mirroring your Fossil repository to GitHub][mirgh]. | |
| 615 | 621 | |
| 616 | 622 | Fossil does not require tag and branch names to be unique. It is |
| 617 | 623 | common, for example, to put a "`release`" tag on every release for a |
| 618 | 624 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 619 | 625 | Fossil resolves such conflicts in a predictable way: the newest match |
| 620 | 626 | wins. Therefore, “`fossil up release`” always gets you the current |
| 621 | 627 | release in a project that uses this tagging convention. |
| 622 | 628 | |
| 629 | +[The `fossil git export` command][fge] squashes repeated tags down to a | |
| 630 | +single instance to avoid confusing Git, exporting only the newest tag. | |
| 631 | + | |
| 632 | +[fge]: /help?cmd=git | |
| 633 | +[gcrf]: https://git-scm.com/docs/git-check-ref-format | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 623 | 637 | |
| 624 | 638 | <a id="cpickrev"></a> |
| 625 | -## Cherry-Picking and Reverting Commits | |
| 639 | +## Cherry-Picking And Reverting Commits | |
| 626 | 640 | |
| 627 | 641 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 628 | 642 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 629 | 643 | `--backout`, respectively. |
| 630 | 644 | |
| @@ -756,20 +770,19 @@ | ||
| 756 | 770 | Now we’re going to do the same thing as above using Fossil. We’ve broken |
| 757 | 771 | the commands up into blocks corresponding to those above for comparison. |
| 758 | 772 | |
| 759 | 773 | We start the same way, cloning the work repo down to the laptop: |
| 760 | 774 | |
| 761 | - mkdir repo | |
| 775 | + fossil clone https://dev-server.example.com/repo | |
| 762 | 776 | cd repo |
| 763 | - fossil open https://dev-server.example.com/repo | |
| 764 | 777 | fossil remote add work https://dev-server.example.com/repo |
| 765 | 778 | |
| 766 | -We’ve chosen the “`fossil open URI`” syntax here rather than separate | |
| 779 | +We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate | |
| 767 | 780 | `clone` and `open` commands to make the parallel with Git clearer. [See |
| 768 | 781 | above](#mwd) for more on that topic. |
| 769 | 782 | |
| 770 | -The final command is longer than the Git equivalent because | |
| 783 | +Fossil’s equivalent [`remote` command][rem] is longer than the Git equivalent because | |
| 771 | 784 | Fossil currently has no short command |
| 772 | 785 | to rename an existing remote. Worse, unlike with Git, we can’t just keep |
| 773 | 786 | using the default remote name because Fossil uses that slot in its |
| 774 | 787 | configuration database to store the *current* remote name, so on |
| 775 | 788 | switching from work to home, the home URL will overwrite the work URL if |
| 776 | 789 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -210,15 +210,15 @@ | |
| 210 | |
| 211 | fossil clone https://example.com/repo |
| 212 | |
| 213 | It’s a shorter command because we deduce `repo.fossil` and the `repo/` |
| 214 | working directory from the last element of the path in the URI. If you |
| 215 | wanted to override both inferences, you’d say: |
| 216 | |
| 217 | fossil clone --workdir foo https://example.com/repo/bar |
| 218 | |
| 219 | That gets you `bar.fossil` with a `foo/` working directory. |
| 220 | |
| 221 | [mcw]: ./ckout-workflows.md#mcw |
| 222 | [wsyml]: https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/ |
| 223 | |
| 224 | |
| @@ -271,11 +271,11 @@ | |
| 271 | [server]: /help?cmd=server |
| 272 | [stash]: /help?cmd=stash |
| 273 | [undo]: /help?cmd=undo |
| 274 | |
| 275 | |
| 276 | ## <a id="log"></a> Fossil’s Timeline is the “Log” |
| 277 | |
| 278 | Git users often need to use the `git log` command to dig linearly through |
| 279 | commit histories due to its [weak data model][wdm]. |
| 280 | |
| 281 | Fossil parses a huge amount of information out of commits that allow it |
| @@ -367,11 +367,11 @@ | |
| 367 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 368 | adding commits to the tip of that branch. |
| 369 | |
| 370 | To switch back to the parent branch, say something like: |
| 371 | |
| 372 | fossil update trunk # like “git checkout” |
| 373 | |
| 374 | Fossil does also support the Git style, creating the branch ahead of |
| 375 | need: |
| 376 | |
| 377 | fossil branch new my-new-branch |
| @@ -387,13 +387,14 @@ | |
| 387 | *after* you commit it, using the "`fossil amend`" command. |
| 388 | For example: |
| 389 | |
| 390 | fossil amend current --branch my-new-branch |
| 391 | |
| 392 | (“current” is one of the [special check-in names][scin] in Fossil. See |
| 393 | that document for the many other names you can give to “`amend`”, or |
| 394 | indeed to any other Fossil command that accepts a “version” string.) |
| 395 | |
| 396 | [scin]: ./checkin_names.wiki |
| 397 | |
| 398 | |
| 399 | <a id="autosync"></a> |
| @@ -444,44 +445,49 @@ | |
| 444 | |
| 445 | <a id="syncall"></a> |
| 446 | ## Sync Is All-Or-Nothing |
| 447 | |
| 448 | Fossil does not support the concept of syncing, pushing, or pulling |
| 449 | individual branches. When you sync/push/pull in Fossil, you |
| 450 | sync/push/pull everything stored as artifacts in its hash tree: |
| 451 | branches, tags, wiki articles, tickets, forum posts, technotes… |
| 452 | [Almost everything][bu]. |
| 453 | |
| 454 | Furthermore, branch *names* sync automatically in Fossil, not just the |
| 455 | content of those branches. This means this common Git command: |
| 456 | |
| 457 | git push origin master |
| 458 | |
| 459 | is simply this in Fossil: |
| 460 | |
| 461 | fossil push |
| 462 | |
| 463 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 464 | keeps using the same remote server URL and branch name you gave it last, |
| 465 | until you tell it to do something different. |
| 466 | |
| 467 | |
| 468 | <a id="trunk"></a> |
| 469 | ## The Main Branch Is Called "`trunk`" |
| 470 | |
| 471 | In Fossil, the traditional name and the default name for the main branch |
| 472 | is "`trunk`". The "`trunk`" branch in Fossil corresponds to the |
| 473 | "`master`" branch in stock Git or the "`main`" branch in GitHub. |
| 474 | |
| 475 | Because the `fossil git export` command has to work with both stock Git |
| 476 | and with GitHub, Fossil uses Git’s default: your Fossil repo’s “trunk” |
| 477 | branch becomes “master” on GitHub, not “main,” as in new GitHub repos. |
| 478 | It is not known what happens on subsequent exports if you |
| 479 | [later rename it][ghmain]. |
| 480 | |
| 481 | [6]: ./mirrortogithub.md |
| 482 | [ghmain]: https://github.com/github/renaming |
| 483 | |
| 484 | |
| 485 | <a id="unmanaged"></a> |
| 486 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 487 | |
| @@ -548,11 +554,11 @@ | |
| 548 | |
| 549 | …is |
| 550 | |
| 551 | fossil time -n 1 COMMIT_ID |
| 552 | |
| 553 | …or with a shorter, more obvious command, with more verbose output: |
| 554 | |
| 555 | fossil info COMMIT_ID |
| 556 | |
| 557 | The `fossil info` command isn’t otherwise a good equivalent to |
| 558 | `git show`. It just overlaps its functionality in some areas. Much of |
| @@ -590,41 +596,49 @@ | |
| 590 | |
| 591 | …which you can approximate in Fossil as: |
| 592 | |
| 593 | fossil pull |
| 594 | fossil diff --from tip |
| 595 | fossil timeline after current |
| 596 | |
| 597 | Note the use of [human-readable symbolic version names][scin] rather than |
| 598 | cryptic notations. |
| 599 | |
| 600 | To invert the diff direction of the second command, say: |
| 601 | |
| 602 | fossil diff --from current --to tip |
| 603 | |
| 604 | You can abbreviate the last command as `fossil tim after curr`. |
| 605 | |
| 606 | |
| 607 | <a id="btnames"></a> |
| 608 | ## Branch and Tag Names |
| 609 | |
| 610 | Fossil has no special restrictions on the names of tags and branches, |
| 611 | though you might want to keep [Git's tag and branch name restrictions][4] |
| 612 | in mind if you plan on mirroring your Fossil repository to GitHub. |
| 613 | |
| 614 | [4]: https://git-scm.com/docs/git-check-ref-format |
| 615 | |
| 616 | Fossil does not require tag and branch names to be unique. It is |
| 617 | common, for example, to put a "`release`" tag on every release for a |
| 618 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 619 | Fossil resolves such conflicts in a predictable way: the newest match |
| 620 | wins. Therefore, “`fossil up release`” always gets you the current |
| 621 | release in a project that uses this tagging convention. |
| 622 | |
| 623 | |
| 624 | <a id="cpickrev"></a> |
| 625 | ## Cherry-Picking and Reverting Commits |
| 626 | |
| 627 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 628 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 629 | `--backout`, respectively. |
| 630 | |
| @@ -756,20 +770,19 @@ | |
| 756 | Now we’re going to do the same thing as above using Fossil. We’ve broken |
| 757 | the commands up into blocks corresponding to those above for comparison. |
| 758 | |
| 759 | We start the same way, cloning the work repo down to the laptop: |
| 760 | |
| 761 | mkdir repo |
| 762 | cd repo |
| 763 | fossil open https://dev-server.example.com/repo |
| 764 | fossil remote add work https://dev-server.example.com/repo |
| 765 | |
| 766 | We’ve chosen the “`fossil open URI`” syntax here rather than separate |
| 767 | `clone` and `open` commands to make the parallel with Git clearer. [See |
| 768 | above](#mwd) for more on that topic. |
| 769 | |
| 770 | The final command is longer than the Git equivalent because |
| 771 | Fossil currently has no short command |
| 772 | to rename an existing remote. Worse, unlike with Git, we can’t just keep |
| 773 | using the default remote name because Fossil uses that slot in its |
| 774 | configuration database to store the *current* remote name, so on |
| 775 | switching from work to home, the home URL will overwrite the work URL if |
| 776 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -210,15 +210,15 @@ | |
| 210 | |
| 211 | fossil clone https://example.com/repo |
| 212 | |
| 213 | It’s a shorter command because we deduce `repo.fossil` and the `repo/` |
| 214 | working directory from the last element of the path in the URI. If you |
| 215 | wanted to override both deductions, you’d say: |
| 216 | |
| 217 | fossil clone --workdir foo https://example.com/repo/bar |
| 218 | |
| 219 | That gets you `bar.fossil` with a `foo/` working directory alongside it. |
| 220 | |
| 221 | [mcw]: ./ckout-workflows.md#mcw |
| 222 | [wsyml]: https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/ |
| 223 | |
| 224 | |
| @@ -271,11 +271,11 @@ | |
| 271 | [server]: /help?cmd=server |
| 272 | [stash]: /help?cmd=stash |
| 273 | [undo]: /help?cmd=undo |
| 274 | |
| 275 | |
| 276 | ## <a id="log"></a> Fossil’s Timeline Is The “Log” |
| 277 | |
| 278 | Git users often need to use the `git log` command to dig linearly through |
| 279 | commit histories due to its [weak data model][wdm]. |
| 280 | |
| 281 | Fossil parses a huge amount of information out of commits that allow it |
| @@ -367,11 +367,11 @@ | |
| 367 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 368 | adding commits to the tip of that branch. |
| 369 | |
| 370 | To switch back to the parent branch, say something like: |
| 371 | |
| 372 | fossil update trunk # ≅ git checkout master |
| 373 | |
| 374 | Fossil does also support the Git style, creating the branch ahead of |
| 375 | need: |
| 376 | |
| 377 | fossil branch new my-new-branch |
| @@ -387,13 +387,14 @@ | |
| 387 | *after* you commit it, using the "`fossil amend`" command. |
| 388 | For example: |
| 389 | |
| 390 | fossil amend current --branch my-new-branch |
| 391 | |
| 392 | (The version string “current” is one of the [special check-in names][scin] in Fossil. See |
| 393 | that document for the many other names you can give to “`amend`”, or |
| 394 | indeed to any other Fossil command documented to accept a `VERSION` or |
| 395 | `NAME` string.) |
| 396 | |
| 397 | [scin]: ./checkin_names.wiki |
| 398 | |
| 399 | |
| 400 | <a id="autosync"></a> |
| @@ -444,44 +445,49 @@ | |
| 445 | |
| 446 | <a id="syncall"></a> |
| 447 | ## Sync Is All-Or-Nothing |
| 448 | |
| 449 | Fossil does not support the concept of syncing, pushing, or pulling |
| 450 | individual branches. When you sync/push/pull in Fossil, it |
| 451 | processes all artifacts in its hash tree: |
| 452 | branches, tags, wiki articles, tickets, forum posts, technotes… |
| 453 | This is [not quite “everything,” full stop][bu], but it’s close. |
| 454 | |
| 455 | Furthermore, branch *names* sync automatically in Fossil, not just the |
| 456 | content of those branches. That means this common Git command: |
| 457 | |
| 458 | git push origin master |
| 459 | |
| 460 | is simply this in Fossil: |
| 461 | |
| 462 | fossil push |
| 463 | |
| 464 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 465 | keeps using the same remote server URL you gave it last |
| 466 | until you [tell it to do something different][rem], and it pushes all |
| 467 | branches, not just one named local branch. |
| 468 | |
| 469 | [rem]: /help?cmd=remote |
| 470 | |
| 471 | |
| 472 | <a id="trunk"></a> |
| 473 | ## The Main Branch Is Called "`trunk`" |
| 474 | |
| 475 | In Fossil, the default name for the main branch |
| 476 | is "`trunk`". The "`trunk`" branch in Fossil corresponds to the |
| 477 | "`master`" branch in stock Git or to [the “`main`” branch in GitHub][mbgh]. |
| 478 | |
| 479 | Because the `fossil git export` command has to work with both stock Git |
| 480 | and with GitHub, Fossil uses Git’s traditional default rather than |
| 481 | GitHub’s new default: your Fossil repo’s “trunk” branch becomes “master” |
| 482 | when [mirroring to GitHub][mirgh], not “main.” |
| 483 | |
| 484 | We do not know what happens on subsequent exports if you later rename |
| 485 | this branch on the GitHub side. |
| 486 | |
| 487 | [mbgh]: https://github.com/github/renaming |
| 488 | [mirgh]: ./mirrortogithub.md |
| 489 | |
| 490 | |
| 491 | <a id="unmanaged"></a> |
| 492 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 493 | |
| @@ -548,11 +554,11 @@ | |
| 554 | |
| 555 | …is |
| 556 | |
| 557 | fossil time -n 1 COMMIT_ID |
| 558 | |
| 559 | …or with a shorter, more obvious command with more verbose output: |
| 560 | |
| 561 | fossil info COMMIT_ID |
| 562 | |
| 563 | The `fossil info` command isn’t otherwise a good equivalent to |
| 564 | `git show`. It just overlaps its functionality in some areas. Much of |
| @@ -590,41 +596,49 @@ | |
| 596 | |
| 597 | …which you can approximate in Fossil as: |
| 598 | |
| 599 | fossil pull |
| 600 | fossil diff --from tip |
| 601 | |
| 602 | …plus… |
| 603 | |
| 604 | fossil timeline after current |
| 605 | |
| 606 | Note the use of [human-readable symbolic version names][scin] rather than |
| 607 | cryptic notations. (But if you like brief commands, you can abbreviate |
| 608 | it as `fossil tim after curr`.) |
| 609 | |
| 610 | To invert the direction of the `diff` command above, say instead: |
| 611 | |
| 612 | fossil diff --from current --to tip |
| 613 | |
| 614 | |
| 615 | <a id="btnames"></a> |
| 616 | ## Branch And Tag Names |
| 617 | |
| 618 | Fossil has no special restrictions on the names of tags and branches, |
| 619 | though you might want to keep [Git's tag and branch name restrictions][gcrf] |
| 620 | in mind if you plan on [mirroring your Fossil repository to GitHub][mirgh]. |
| 621 | |
| 622 | Fossil does not require tag and branch names to be unique. It is |
| 623 | common, for example, to put a "`release`" tag on every release for a |
| 624 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 625 | Fossil resolves such conflicts in a predictable way: the newest match |
| 626 | wins. Therefore, “`fossil up release`” always gets you the current |
| 627 | release in a project that uses this tagging convention. |
| 628 | |
| 629 | [The `fossil git export` command][fge] squashes repeated tags down to a |
| 630 | single instance to avoid confusing Git, exporting only the newest tag. |
| 631 | |
| 632 | [fge]: /help?cmd=git |
| 633 | [gcrf]: https://git-scm.com/docs/git-check-ref-format |
| 634 | |
| 635 | |
| 636 | |
| 637 | |
| 638 | <a id="cpickrev"></a> |
| 639 | ## Cherry-Picking And Reverting Commits |
| 640 | |
| 641 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 642 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 643 | `--backout`, respectively. |
| 644 | |
| @@ -756,20 +770,19 @@ | |
| 770 | Now we’re going to do the same thing as above using Fossil. We’ve broken |
| 771 | the commands up into blocks corresponding to those above for comparison. |
| 772 | |
| 773 | We start the same way, cloning the work repo down to the laptop: |
| 774 | |
| 775 | fossil clone https://dev-server.example.com/repo |
| 776 | cd repo |
| 777 | fossil remote add work https://dev-server.example.com/repo |
| 778 | |
| 779 | We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate |
| 780 | `clone` and `open` commands to make the parallel with Git clearer. [See |
| 781 | above](#mwd) for more on that topic. |
| 782 | |
| 783 | Fossil’s equivalent [`remote` command][rem] is longer than the Git equivalent because |
| 784 | Fossil currently has no short command |
| 785 | to rename an existing remote. Worse, unlike with Git, we can’t just keep |
| 786 | using the default remote name because Fossil uses that slot in its |
| 787 | configuration database to store the *current* remote name, so on |
| 788 | switching from work to home, the home URL will overwrite the work URL if |
| 789 |