Fossil SCM
Greatly expanded the "Repositories And Checkouts Are Distinct" section of the gitusers.md doc.
Commit
386fc49e3f9323ddcfdd8c61ccedf214fce2016b73f994e31bfd25579e3606e6
Parent
ecac7c4ea7dbee1…
1 file changed
+106
-29
+106
-29
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -24,42 +24,120 @@ | ||
| 24 | 24 | |
| 25 | 25 | <a id="mwd"></a> |
| 26 | 26 | ## Repositories And Checkouts Are Distinct |
| 27 | 27 | |
| 28 | 28 | A repository and a check-out are distinct concepts in Fossil, whereas |
| 29 | -the two are often conflated with Git. A repository is a database in | |
| 29 | +the two are collocated by default with Git. | |
| 30 | + | |
| 31 | +A Fossil repository is a SQLite database in | |
| 30 | 32 | which the entire history of a project is stored. A check-out is a |
| 31 | -directory hierarchy that contains a snapshot of your project that you | |
| 32 | -are currently working on. See [detailed definitions][2] for more | |
| 33 | -information. With Git, the repository and check-out are closely | |
| 34 | -related - the repository is the contents of the "`.git`" subdirectory | |
| 35 | -at the root of your check-out. But with Fossil, the repository and | |
| 36 | -the check-out are completely separate. A Fossil repository can reside | |
| 37 | -in the same directory hierarchy with the check-out as with Git, but it | |
| 38 | -is more common to put the repository in a separate directory. | |
| 39 | - | |
| 40 | -[2]: ./whyusefossil.wiki#definitions | |
| 41 | - | |
| 42 | -Fossil repositories are a single file, rather than being a directory | |
| 43 | -hierarchy as with the "`.git`" folder in Git. The repository file | |
| 44 | -can be named anything you want, but it is best to use the "`.fossil`" | |
| 45 | -suffix. Many people choose to gather all of their Fossil repositories | |
| 46 | -in a single directory on their machine, such as "`~/Fossils`" or | |
| 33 | +directory that contains a snapshot of your project that you | |
| 34 | +are currently working on, extracted for you from that database by the | |
| 35 | +`fossil` program. See [the Fossil glossary][gloss] for more information. | |
| 36 | + | |
| 37 | +With Git, cloning a repository gets you what Fossil would call a | |
| 38 | +check-out directory with the repository stored in a `.git` subdirectory | |
| 39 | +of that check-out. There are methods to get more working directories | |
| 40 | +pointing at that same Git repository, but because it’s not designed into | |
| 41 | +the core concept of the tool, Git tutorials usually advocate a | |
| 42 | +switch-in-place working mode instead. | |
| 43 | + | |
| 44 | +Fossil can operate in the Git mode, switching between versions in a | |
| 45 | +single check-out directory: | |
| 46 | + | |
| 47 | + fossil clone https://example.com/repo /path/to/repo.fossil | |
| 48 | + mkdir work-dir | |
| 49 | + cd work-dir | |
| 50 | + fossil open /path/to/repo.fossil | |
| 51 | + ...work on trunk... | |
| 52 | + fossil update my-other-branch # like “git checkout” | |
| 53 | + ...work on your other branch in the same directory... | |
| 54 | + | |
| 55 | +As of Fossil 2.12, it can clone-and-open into a single directory, as Git | |
| 56 | +always has done: | |
| 57 | + | |
| 58 | + mkdir work-dir | |
| 59 | + cd work-dir | |
| 60 | + fossil open https://example.com/repo | |
| 61 | + | |
| 62 | +Now you have “trunk” open in `work-dir`, with the repo file stored as | |
| 63 | +`repo.fossil` in that same directory. | |
| 64 | + | |
| 65 | +(Note that Fossil purposefully does not create the directory for you as | |
| 66 | +Git does, because this feature is an extension of | |
| 67 | +[the “open” command][open], which historically means “open in the | |
| 68 | +current directory” in Fossil. It would be wrong for Fossil to create a | |
| 69 | +subdirectory when passed a URI but not when passed any other parameter.) | |
| 70 | + | |
| 71 | +The repository file can be named anything you want, with a single | |
| 72 | +exception: if you’re going to use the [`fossil server DIRECTORY`][server] | |
| 73 | +feature, the repositories need to have a "`.fossil`" suffix. That aside, | |
| 74 | +you can follow any other convention that makes sense to you. | |
| 75 | + | |
| 76 | +Many people choose to gather all of their Fossil repositories | |
| 77 | +in a single directory on their machine, such as "`~/museum`" or | |
| 47 | 78 | "`C:\Fossils`". This can help humans to keep their repositories |
| 48 | -organized, but Fossil itself doesn't really care. | |
| 79 | +organized, but Fossil itself doesn't really care. (Why “museum”? | |
| 80 | +Because that is where one stores valuable fossils.) | |
| 49 | 81 | |
| 50 | 82 | Because Fossil cleanly separates the repository from the check-out, it |
| 51 | -is routine to have multiple check-outs from the same repository. Each | |
| 52 | -check-out can be on a separate branch, or on the same branch. Each | |
| 53 | -check-out operates independently of the others. | |
| 54 | - | |
| 55 | -Each Fossil check-out contains a file (usually named "`.fslckout`" on | |
| 56 | -unix or "`_FOSSIL_`" on Windows) that keeps track of the status of that | |
| 57 | -particular check-out and keeps a pointer to the repository. If you | |
| 58 | -move or rename the repository file, the check-outs won't be able to find | |
| 59 | -it and will complain. But you can freely move check-outs around without | |
| 60 | -causing any problems. | |
| 83 | +is routine to have multiple check-outs from the same repository: | |
| 84 | + | |
| 85 | + mkdir -p ~/src/my-project/trunk | |
| 86 | + cd ~/src/my-project/trunk | |
| 87 | + fossil open /path/to/repo.fossil # implicitly opens “trunk” | |
| 88 | + mkdir ../my-other-branch | |
| 89 | + cd ../my-other-branch | |
| 90 | + fossil open /path/to/repo.fossil my-other-branch | |
| 91 | + mkdir ../release | |
| 92 | + cd ../release | |
| 93 | + fossil open /path/to/repo.fossil release | |
| 94 | + mkdir ../scratch | |
| 95 | + cd ../scratch | |
| 96 | + fossil open /path/to/repo.fossil abcd1234 | |
| 97 | + mkdir ../test | |
| 98 | + cd ../test | |
| 99 | + fossil open /path/to/repo.fossil 2019-04-01 | |
| 100 | + | |
| 101 | +Now you have five separate check-out directories: one each for trunk, an | |
| 102 | +alternate branch you’re working on, the latest tagged public release, a | |
| 103 | +“scratch” directory for experiments or brief bits of work you don’t want | |
| 104 | +to do in the other check-out directories, and a directory for testing a | |
| 105 | +user report of a bug in the trunk version as of last April Fool’s Day. | |
| 106 | +Each check-out operates independently of the others. | |
| 107 | + | |
| 108 | +This working style is especially useful when programming in languages | |
| 109 | +where there is a “build” step that transforms source files into files | |
| 110 | +you actually run or distribute. With Git, switching versions in a single | |
| 111 | +working tree means you have to rebuild all outputs from the source files | |
| 112 | +that differ between those versions. In the above Fossil working model, | |
| 113 | +you switch versions with a “`cd`” command instead, so that you only have | |
| 114 | +to rebuild outputs from files you yourself change. | |
| 115 | + | |
| 116 | +This style is also useful when a check-out directory may be tied up with | |
| 117 | +some long-running process, as with the “test” example above, where you | |
| 118 | +might need to run an hours-long brute-force replication script to tickle | |
| 119 | +a [Heisenbug][hb]. While that runs, you can “`cd ../trunk`” and get back | |
| 120 | +to work. | |
| 121 | + | |
| 122 | +Git users may be initially confused by the `.fslckout` file at the root | |
| 123 | +of a check-out directory. (Or with native Windows builds of Fossil, the | |
| 124 | +`_FOSSIL_` file, which is the same thing, so-named to get around the | |
| 125 | +historical 3-character extension limit with certain legacy filesystems.) | |
| 126 | +This is not the same thing as `.git`. It’s a per-checkout SQLite | |
| 127 | +database that keeps track of local state such as what version you have | |
| 128 | +checked out, the contents of the stash for that working directory, the | |
| 129 | +[undo] buffers, per-checkout settings, and so forth. Largely what Fossil | |
| 130 | +does when you ask it to [close] a check-out is to remove this file after | |
| 131 | +making certain safety checks. | |
| 132 | + | |
| 133 | +[close]: /help?cmd=close | |
| 134 | +[gloss]: ./whyusefossil.wiki#definitions | |
| 135 | +[hb]: https://en.wikipedia.org/wiki/Heisenbug | |
| 136 | +[open]: /help?cmd=open | |
| 137 | +[server]: /help?cmd=server | |
| 138 | +[undo]: /help?cmd=undo | |
| 61 | 139 | |
| 62 | 140 | |
| 63 | 141 | <a id="staging"></a> |
| 64 | 142 | ## There Is No Staging Area |
| 65 | 143 | |
| @@ -423,9 +501,8 @@ | ||
| 423 | 501 | Back at home, it’s even simpler: we can do away with the second command, |
| 424 | 502 | saying just “`fossil remote home`” because the sync will happen as part |
| 425 | 503 | of the next commit, thanks once again to Fossil’s autosync feature. |
| 426 | 504 | |
| 427 | 505 | [grsync]: https://stackoverflow.com/q/1398018/142454 |
| 428 | -[open]: /help?cmd=open | |
| 429 | 506 | [qs]: ./quickstart.wiki |
| 430 | 507 | [shwmd]: ./fossil-v-git.wiki#checkouts |
| 431 | 508 | [sn]: https://en.wikipedia.org/wiki/Sneakernet |
| 432 | 509 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -24,42 +24,120 @@ | |
| 24 | |
| 25 | <a id="mwd"></a> |
| 26 | ## Repositories And Checkouts Are Distinct |
| 27 | |
| 28 | A repository and a check-out are distinct concepts in Fossil, whereas |
| 29 | the two are often conflated with Git. A repository is a database in |
| 30 | which the entire history of a project is stored. A check-out is a |
| 31 | directory hierarchy that contains a snapshot of your project that you |
| 32 | are currently working on. See [detailed definitions][2] for more |
| 33 | information. With Git, the repository and check-out are closely |
| 34 | related - the repository is the contents of the "`.git`" subdirectory |
| 35 | at the root of your check-out. But with Fossil, the repository and |
| 36 | the check-out are completely separate. A Fossil repository can reside |
| 37 | in the same directory hierarchy with the check-out as with Git, but it |
| 38 | is more common to put the repository in a separate directory. |
| 39 | |
| 40 | [2]: ./whyusefossil.wiki#definitions |
| 41 | |
| 42 | Fossil repositories are a single file, rather than being a directory |
| 43 | hierarchy as with the "`.git`" folder in Git. The repository file |
| 44 | can be named anything you want, but it is best to use the "`.fossil`" |
| 45 | suffix. Many people choose to gather all of their Fossil repositories |
| 46 | in a single directory on their machine, such as "`~/Fossils`" or |
| 47 | "`C:\Fossils`". This can help humans to keep their repositories |
| 48 | organized, but Fossil itself doesn't really care. |
| 49 | |
| 50 | Because Fossil cleanly separates the repository from the check-out, it |
| 51 | is routine to have multiple check-outs from the same repository. Each |
| 52 | check-out can be on a separate branch, or on the same branch. Each |
| 53 | check-out operates independently of the others. |
| 54 | |
| 55 | Each Fossil check-out contains a file (usually named "`.fslckout`" on |
| 56 | unix or "`_FOSSIL_`" on Windows) that keeps track of the status of that |
| 57 | particular check-out and keeps a pointer to the repository. If you |
| 58 | move or rename the repository file, the check-outs won't be able to find |
| 59 | it and will complain. But you can freely move check-outs around without |
| 60 | causing any problems. |
| 61 | |
| 62 | |
| 63 | <a id="staging"></a> |
| 64 | ## There Is No Staging Area |
| 65 | |
| @@ -423,9 +501,8 @@ | |
| 423 | Back at home, it’s even simpler: we can do away with the second command, |
| 424 | saying just “`fossil remote home`” because the sync will happen as part |
| 425 | of the next commit, thanks once again to Fossil’s autosync feature. |
| 426 | |
| 427 | [grsync]: https://stackoverflow.com/q/1398018/142454 |
| 428 | [open]: /help?cmd=open |
| 429 | [qs]: ./quickstart.wiki |
| 430 | [shwmd]: ./fossil-v-git.wiki#checkouts |
| 431 | [sn]: https://en.wikipedia.org/wiki/Sneakernet |
| 432 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -24,42 +24,120 @@ | |
| 24 | |
| 25 | <a id="mwd"></a> |
| 26 | ## Repositories And Checkouts Are Distinct |
| 27 | |
| 28 | A repository and a check-out are distinct concepts in Fossil, whereas |
| 29 | the two are collocated by default with Git. |
| 30 | |
| 31 | A Fossil repository is a SQLite database in |
| 32 | which the entire history of a project is stored. A check-out is a |
| 33 | directory that contains a snapshot of your project that you |
| 34 | are currently working on, extracted for you from that database by the |
| 35 | `fossil` program. See [the Fossil glossary][gloss] for more information. |
| 36 | |
| 37 | With Git, cloning a repository gets you what Fossil would call a |
| 38 | check-out directory with the repository stored in a `.git` subdirectory |
| 39 | of that check-out. There are methods to get more working directories |
| 40 | pointing at that same Git repository, but because it’s not designed into |
| 41 | the core concept of the tool, Git tutorials usually advocate a |
| 42 | switch-in-place working mode instead. |
| 43 | |
| 44 | Fossil can operate in the Git mode, switching between versions in a |
| 45 | single check-out directory: |
| 46 | |
| 47 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 48 | mkdir work-dir |
| 49 | cd work-dir |
| 50 | fossil open /path/to/repo.fossil |
| 51 | ...work on trunk... |
| 52 | fossil update my-other-branch # like “git checkout” |
| 53 | ...work on your other branch in the same directory... |
| 54 | |
| 55 | As of Fossil 2.12, it can clone-and-open into a single directory, as Git |
| 56 | always has done: |
| 57 | |
| 58 | mkdir work-dir |
| 59 | cd work-dir |
| 60 | fossil open https://example.com/repo |
| 61 | |
| 62 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 63 | `repo.fossil` in that same directory. |
| 64 | |
| 65 | (Note that Fossil purposefully does not create the directory for you as |
| 66 | Git does, because this feature is an extension of |
| 67 | [the “open” command][open], which historically means “open in the |
| 68 | current directory” in Fossil. It would be wrong for Fossil to create a |
| 69 | subdirectory when passed a URI but not when passed any other parameter.) |
| 70 | |
| 71 | The repository file can be named anything you want, with a single |
| 72 | exception: if you’re going to use the [`fossil server DIRECTORY`][server] |
| 73 | feature, the repositories need to have a "`.fossil`" suffix. That aside, |
| 74 | you can follow any other convention that makes sense to you. |
| 75 | |
| 76 | Many people choose to gather all of their Fossil repositories |
| 77 | in a single directory on their machine, such as "`~/museum`" or |
| 78 | "`C:\Fossils`". This can help humans to keep their repositories |
| 79 | organized, but Fossil itself doesn't really care. (Why “museum”? |
| 80 | Because that is where one stores valuable fossils.) |
| 81 | |
| 82 | Because Fossil cleanly separates the repository from the check-out, it |
| 83 | is routine to have multiple check-outs from the same repository: |
| 84 | |
| 85 | mkdir -p ~/src/my-project/trunk |
| 86 | cd ~/src/my-project/trunk |
| 87 | fossil open /path/to/repo.fossil # implicitly opens “trunk” |
| 88 | mkdir ../my-other-branch |
| 89 | cd ../my-other-branch |
| 90 | fossil open /path/to/repo.fossil my-other-branch |
| 91 | mkdir ../release |
| 92 | cd ../release |
| 93 | fossil open /path/to/repo.fossil release |
| 94 | mkdir ../scratch |
| 95 | cd ../scratch |
| 96 | fossil open /path/to/repo.fossil abcd1234 |
| 97 | mkdir ../test |
| 98 | cd ../test |
| 99 | fossil open /path/to/repo.fossil 2019-04-01 |
| 100 | |
| 101 | Now you have five separate check-out directories: one each for trunk, an |
| 102 | alternate branch you’re working on, the latest tagged public release, a |
| 103 | “scratch” directory for experiments or brief bits of work you don’t want |
| 104 | to do in the other check-out directories, and a directory for testing a |
| 105 | user report of a bug in the trunk version as of last April Fool’s Day. |
| 106 | Each check-out operates independently of the others. |
| 107 | |
| 108 | This working style is especially useful when programming in languages |
| 109 | where there is a “build” step that transforms source files into files |
| 110 | you actually run or distribute. With Git, switching versions in a single |
| 111 | working tree means you have to rebuild all outputs from the source files |
| 112 | that differ between those versions. In the above Fossil working model, |
| 113 | you switch versions with a “`cd`” command instead, so that you only have |
| 114 | to rebuild outputs from files you yourself change. |
| 115 | |
| 116 | This style is also useful when a check-out directory may be tied up with |
| 117 | some long-running process, as with the “test” example above, where you |
| 118 | might need to run an hours-long brute-force replication script to tickle |
| 119 | a [Heisenbug][hb]. While that runs, you can “`cd ../trunk`” and get back |
| 120 | to work. |
| 121 | |
| 122 | Git users may be initially confused by the `.fslckout` file at the root |
| 123 | of a check-out directory. (Or with native Windows builds of Fossil, the |
| 124 | `_FOSSIL_` file, which is the same thing, so-named to get around the |
| 125 | historical 3-character extension limit with certain legacy filesystems.) |
| 126 | This is not the same thing as `.git`. It’s a per-checkout SQLite |
| 127 | database that keeps track of local state such as what version you have |
| 128 | checked out, the contents of the stash for that working directory, the |
| 129 | [undo] buffers, per-checkout settings, and so forth. Largely what Fossil |
| 130 | does when you ask it to [close] a check-out is to remove this file after |
| 131 | making certain safety checks. |
| 132 | |
| 133 | [close]: /help?cmd=close |
| 134 | [gloss]: ./whyusefossil.wiki#definitions |
| 135 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 136 | [open]: /help?cmd=open |
| 137 | [server]: /help?cmd=server |
| 138 | [undo]: /help?cmd=undo |
| 139 | |
| 140 | |
| 141 | <a id="staging"></a> |
| 142 | ## There Is No Staging Area |
| 143 | |
| @@ -423,9 +501,8 @@ | |
| 501 | Back at home, it’s even simpler: we can do away with the second command, |
| 502 | saying just “`fossil remote home`” because the sync will happen as part |
| 503 | of the next commit, thanks once again to Fossil’s autosync feature. |
| 504 | |
| 505 | [grsync]: https://stackoverflow.com/q/1398018/142454 |
| 506 | [qs]: ./quickstart.wiki |
| 507 | [shwmd]: ./fossil-v-git.wiki#checkouts |
| 508 | [sn]: https://en.wikipedia.org/wiki/Sneakernet |
| 509 |