Fossil SCM
Expanded on several points in the gitusers doc, added links to other docs, added named anchors to all of the top-level sections, and removed the obsolete section on "no multiple remotes" now that we have the "fossil remote add" feature.
Commit
2306f8164def9e2cbc54cf7f80e5d1c3b580560d50a06b3c97a4221a12c5b395
Parent
331dc0d334f6566…
1 file changed
+84
-45
+84
-45
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -2,10 +2,11 @@ | ||
| 2 | 2 | |
| 3 | 3 | This document is a semi-random collection of hints intended to help |
| 4 | 4 | new users of Fossil who have had prior exposure to Git. In other words, |
| 5 | 5 | this document tries to describe the differences in how Fossil works |
| 6 | 6 | from the perspective of Git users. |
| 7 | + | |
| 7 | 8 | |
| 8 | 9 | ## Help Improve This Document |
| 9 | 10 | |
| 10 | 11 | If you have a lot of prior Git experience, and you are new to Fossil |
| 11 | 12 | and are struggling with some concepts, please ask for help on the |
| @@ -18,10 +19,12 @@ | ||
| 18 | 19 | [1]: https://fossil-scm.org/forum |
| 19 | 20 | |
| 20 | 21 | Specific suggestions on how to improve this document are also welcomed, |
| 21 | 22 | of course. |
| 22 | 23 | |
| 24 | + | |
| 25 | +<a id="mwd"></a> | |
| 23 | 26 | ## Repositories And Checkouts Are Distinct |
| 24 | 27 | |
| 25 | 28 | A repository and a check-out are distinct concepts in Fossil, whereas |
| 26 | 29 | the two are often conflated with Git. A repository is a database in |
| 27 | 30 | which the entire history of a project is stored. A check-out is a |
| @@ -54,10 +57,12 @@ | ||
| 54 | 57 | particular check-out and keeps a pointer to the repository. If you |
| 55 | 58 | move or rename the repository file, the check-outs won't be able to find |
| 56 | 59 | it and will complain. But you can freely move check-outs around without |
| 57 | 60 | causing any problems. |
| 58 | 61 | |
| 62 | + | |
| 63 | +<a id="staging"></a> | |
| 59 | 64 | ## There Is No Staging Area |
| 60 | 65 | |
| 61 | 66 | Fossil omits the "Git index" or "staging area" concept. When you |
| 62 | 67 | type "`fossil commit`" _all_ changes in your check-out are committed, |
| 63 | 68 | automatically. There is no need for the "-a" option as with Git. |
| @@ -65,10 +70,12 @@ | ||
| 65 | 70 | If you only want to commit just some of the changes, you can list the names |
| 66 | 71 | of the files you want to commit as arguments, like this: |
| 67 | 72 | |
| 68 | 73 | fossil commit src/main.c doc/readme.md |
| 69 | 74 | |
| 75 | + | |
| 76 | +<a id="bneed"></a> | |
| 70 | 77 | ## Create Branches At Point Of Need, Rather Than Ahead of Need |
| 71 | 78 | |
| 72 | 79 | Fossil prefers that you create new branches as part of the first commit |
| 73 | 80 | on that branch: |
| 74 | 81 | |
| @@ -102,10 +109,12 @@ | ||
| 102 | 109 | (“current” is one of the [special check-in names][scin] in Fossil. See |
| 103 | 110 | that document for the many other names you can give to “`amend`”.) |
| 104 | 111 | |
| 105 | 112 | [scin]: ./checkin_names.wiki |
| 106 | 113 | |
| 114 | + | |
| 115 | +<a id="autosync"></a> | |
| 107 | 116 | ## Autosync |
| 108 | 117 | |
| 109 | 118 | Fossil has a feature called "[autosync][5]". Autosync defaults on. |
| 110 | 119 | When autosync is enabled, Fossil automatically pushes your changes |
| 111 | 120 | to the remote server whenever you "`fossil commit`". It also automatically |
| @@ -119,17 +128,34 @@ | ||
| 119 | 128 | control. Your work stays synced up with your coworkers at all times. |
| 120 | 129 | If your local machine dies catastrophically, you haven't lost any |
| 121 | 130 | (committed) work. But you can still work and commit while off network, |
| 122 | 131 | with changes resyncing automatically when you get back on-line. |
| 123 | 132 | |
| 133 | + | |
| 134 | +<a id="syncall"></a> | |
| 124 | 135 | ## Syncing Is All-Or-Nothing |
| 125 | 136 | |
| 126 | 137 | Fossil does not support the concept of syncing, pushing, or pulling |
| 127 | 138 | individual branches. When you sync/push/pull in Fossil, you sync/push/pull |
| 128 | -everything - all branches, all wiki, all tickets, all forum posts, | |
| 129 | -all tags, all technotes - everything. | |
| 139 | +everything: all branches, all wiki, all tickets, all forum posts, | |
| 140 | +all tags, all technotes… Everything. | |
| 141 | + | |
| 142 | +Furthermore, branch *names* sync automatically in Fossil, not just the | |
| 143 | +content of those branches. This means this common Git command: | |
| 144 | + | |
| 145 | + git push origin master | |
| 146 | + | |
| 147 | +is simply this in Fossil: | |
| 148 | + | |
| 149 | + fossil push | |
| 150 | + | |
| 151 | +Fossil doesn’t need to be told what to push or where to push it: it just | |
| 152 | +keeps using the same remote server URL and branch name you gave it last, | |
| 153 | +until you tell it to do something different. | |
| 154 | + | |
| 130 | 155 | |
| 156 | +<a id="trunk"></a> | |
| 131 | 157 | ## The Main Branch Is Called "`trunk`" |
| 132 | 158 | |
| 133 | 159 | In Fossil, the traditional name and the default name for the main branch |
| 134 | 160 | is "`trunk`". The "`trunk`" branch in Fossil corresponds to the |
| 135 | 161 | "`master`" branch in stock Git or the "`main`" branch in GitHub. |
| @@ -141,28 +167,40 @@ | ||
| 141 | 167 | [later rename it][ghmain]. |
| 142 | 168 | |
| 143 | 169 | [6]: ./mirrortogithub.md |
| 144 | 170 | [ghmain]: https://github.com/github/renaming |
| 145 | 171 | |
| 172 | + | |
| 173 | +<a id="unmanaged"></a> | |
| 146 | 174 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 147 | 175 | |
| 148 | 176 | The "`fossil status`" command shows you what files in your check-out have |
| 149 | 177 | been edited and scheduled for adding or removing at the next commit. |
| 150 | 178 | But unlike "`git status`", the "`fossil status`" command does not warn |
| 151 | 179 | you about unmanaged files in your local check-out. There is a separate |
| 152 | 180 | "`fossil extras`" command for that. |
| 153 | 181 | |
| 182 | + | |
| 183 | +<a id="rebase"></a> | |
| 154 | 184 | ## There Is No Rebase |
| 155 | 185 | |
| 156 | -Fossil does not support rebase. | |
| 157 | -This is a [deliberate design decision][3] that has been thoroughly, | |
| 158 | -carefully, and throughtfully discussed, many times. If you are fond | |
| 159 | -of rebase, you should read the [Rebase Considered Harmful][3] document | |
| 160 | -carefully before expressing your views. | |
| 186 | +Fossil does not support rebase, [on purpose][3]. | |
| 187 | + | |
| 188 | +This is a deliberate design decision that the Fossil community has | |
| 189 | +thought about carefully and discussed many times, resulting in the | |
| 190 | +linked document. If you are fond of rebase, you should read it carefully | |
| 191 | +before expressing your views: it not only answers many of the common | |
| 192 | +arguments in favor of rebase known at the time the document’s first | |
| 193 | +draft was written, it’s been revised multiple times to address less | |
| 194 | +common objections as well. Chances are not good that you are going to | |
| 195 | +come up with a new objection that we haven’t already considered and | |
| 196 | +addressed there. | |
| 161 | 197 | |
| 162 | 198 | [3]: ./rebaseharm.md |
| 163 | 199 | |
| 200 | + | |
| 201 | +<a id="btnames"></a> | |
| 164 | 202 | ## Branch and Tag Names |
| 165 | 203 | |
| 166 | 204 | Fossil has no special restrictions on the names of tags and branches, |
| 167 | 205 | though you might want to keep [Git's tag and branch name restrictions][4] |
| 168 | 206 | in mind if you plan on mirroring your Fossil repository to GitHub. |
| @@ -169,46 +207,47 @@ | ||
| 169 | 207 | |
| 170 | 208 | [4]: https://git-scm.com/docs/git-check-ref-format |
| 171 | 209 | |
| 172 | 210 | Fossil does not require tag and branch names to be unique. It is |
| 173 | 211 | common, for example, to put a "`release`" tag on every release for a |
| 174 | -Fossil-hosted project. | |
| 175 | - | |
| 176 | -## Only One "origin" At A Time | |
| 177 | - | |
| 178 | -A Fossil repository only keeps track of one "origin" server at a time. | |
| 179 | -If you specify a new "origin" it forgets the previous one. Use the | |
| 180 | -"`fossil remote`" command to see or change the "origin". | |
| 181 | - | |
| 182 | -Fossil uses a very different sync protocol than Git, so it isn't as | |
| 183 | -important for Fossil to keep track of multiple origins as it is with | |
| 184 | -Git. So only having a single origin has never been a big enough problem | |
| 185 | -in Fossil that somebody felt the need to extend it. | |
| 186 | - | |
| 187 | -Maybe we will add multiple origin support to Fossil someday. Patches | |
| 188 | -are welcomed if you want to have a go at it. | |
| 189 | - | |
| 190 | -## Cherry-pick Is An Option To The "merge" Command | |
| 191 | - | |
| 192 | -In Git, "`git cherry-pick`" is a separate command. | |
| 193 | -In Fossil, "`fossil merge --cherrypick`" is an option on the merge | |
| 194 | -command. Otherwise, they work mostly the same. | |
| 195 | - | |
| 196 | -Except, the Fossil file format remembers cherrypicks and actually | |
| 197 | -shows them as dashed lines on the graphical DAG display, whereas | |
| 198 | -there is no provision for recording cherry-picks in the Git file | |
| 199 | -format, so you have to talk about the cherry-pick in the commit | |
| 200 | -comment if you want to remember it. | |
| 201 | - | |
| 202 | -## The "`fossil mv`" and "`fossil rm`" Commands Do Not Actually Rename Or Delete The Files (by default) | |
| 203 | - | |
| 204 | -By default, | |
| 205 | -the "`fossil mv`" and "`fossil rm`" commands work like they do in CVS in | |
| 206 | -that they schedule the changes for the next commit, but do not actually | |
| 207 | -rename or delete the files in your check-out. You can to add the "--hard" | |
| 208 | -option to also changes the files in your check-out. | |
| 209 | -If you run | |
| 212 | +Fossil-hosted project. This does not create a conflict in Fossil, since | |
| 213 | +Fossil resolves such conflicts in a predictable way: the newest match | |
| 214 | +wins. Therefore, “`fossil up release`” always gets you the current | |
| 215 | +release in a project that uses this tagging convention. | |
| 216 | + | |
| 217 | + | |
| 218 | +<a id="cpickrev"></a> | |
| 219 | +## Cherry-Picking and Reverting Commits | |
| 220 | + | |
| 221 | +Git’s separate "`git cherry-pick`" and “`git revert`” commands are | |
| 222 | +options to the [`fossil merge` command][merge]: `--cherrypick` and | |
| 223 | +`--backout`, respectively. | |
| 224 | + | |
| 225 | +Unlike in Git, the Fossil file format remembers cherrypicks and backouts | |
| 226 | +and can later show them as dashed lines on the graphical timeline. | |
| 227 | + | |
| 228 | +[merge]: /help?cmd=merge | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | +<a id="mvrm"></a> | |
| 233 | +## File Moves And Renames Are Soft By Default | |
| 234 | + | |
| 235 | +The "[`fossil mv`][mv]" and "[`fossil rm`][rm]" commands work like they | |
| 236 | +do in CVS in that they schedule the changes for the next commit by | |
| 237 | +default: they do not actually rename or delete the files in your | |
| 238 | +check-out. | |
| 239 | + | |
| 240 | +If you don’t like that default, you can change it globally: | |
| 210 | 241 | |
| 211 | 242 | fossil setting --global mv-rm-files 1 |
| 212 | 243 | |
| 213 | -it makes a notation in your per-user "~/.fossil" settings file so that | |
| 214 | -the "--hard" behavior becomes the new default. | |
| 244 | +Now these commands behave like in Git in any Fossil repository where | |
| 245 | +this setting hasn’t been overridden locally. | |
| 246 | + | |
| 247 | +If you want to keep Fossil’s soft `mv/rm` behavior most of the time, you | |
| 248 | +can cast it away on a per-command basis: | |
| 249 | + | |
| 250 | + fossil mv --hard old-name new-name | |
| 251 | + | |
| 252 | +[mv]: /help?cmd=mv | |
| 253 | +[rm]: /help?cmd=rm | |
| 215 | 254 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -2,10 +2,11 @@ | |
| 2 | |
| 3 | This document is a semi-random collection of hints intended to help |
| 4 | new users of Fossil who have had prior exposure to Git. In other words, |
| 5 | this document tries to describe the differences in how Fossil works |
| 6 | from the perspective of Git users. |
| 7 | |
| 8 | ## Help Improve This Document |
| 9 | |
| 10 | If you have a lot of prior Git experience, and you are new to Fossil |
| 11 | and are struggling with some concepts, please ask for help on the |
| @@ -18,10 +19,12 @@ | |
| 18 | [1]: https://fossil-scm.org/forum |
| 19 | |
| 20 | Specific suggestions on how to improve this document are also welcomed, |
| 21 | of course. |
| 22 | |
| 23 | ## Repositories And Checkouts Are Distinct |
| 24 | |
| 25 | A repository and a check-out are distinct concepts in Fossil, whereas |
| 26 | the two are often conflated with Git. A repository is a database in |
| 27 | which the entire history of a project is stored. A check-out is a |
| @@ -54,10 +57,12 @@ | |
| 54 | particular check-out and keeps a pointer to the repository. If you |
| 55 | move or rename the repository file, the check-outs won't be able to find |
| 56 | it and will complain. But you can freely move check-outs around without |
| 57 | causing any problems. |
| 58 | |
| 59 | ## There Is No Staging Area |
| 60 | |
| 61 | Fossil omits the "Git index" or "staging area" concept. When you |
| 62 | type "`fossil commit`" _all_ changes in your check-out are committed, |
| 63 | automatically. There is no need for the "-a" option as with Git. |
| @@ -65,10 +70,12 @@ | |
| 65 | If you only want to commit just some of the changes, you can list the names |
| 66 | of the files you want to commit as arguments, like this: |
| 67 | |
| 68 | fossil commit src/main.c doc/readme.md |
| 69 | |
| 70 | ## Create Branches At Point Of Need, Rather Than Ahead of Need |
| 71 | |
| 72 | Fossil prefers that you create new branches as part of the first commit |
| 73 | on that branch: |
| 74 | |
| @@ -102,10 +109,12 @@ | |
| 102 | (“current” is one of the [special check-in names][scin] in Fossil. See |
| 103 | that document for the many other names you can give to “`amend`”.) |
| 104 | |
| 105 | [scin]: ./checkin_names.wiki |
| 106 | |
| 107 | ## Autosync |
| 108 | |
| 109 | Fossil has a feature called "[autosync][5]". Autosync defaults on. |
| 110 | When autosync is enabled, Fossil automatically pushes your changes |
| 111 | to the remote server whenever you "`fossil commit`". It also automatically |
| @@ -119,17 +128,34 @@ | |
| 119 | control. Your work stays synced up with your coworkers at all times. |
| 120 | If your local machine dies catastrophically, you haven't lost any |
| 121 | (committed) work. But you can still work and commit while off network, |
| 122 | with changes resyncing automatically when you get back on-line. |
| 123 | |
| 124 | ## Syncing Is All-Or-Nothing |
| 125 | |
| 126 | Fossil does not support the concept of syncing, pushing, or pulling |
| 127 | individual branches. When you sync/push/pull in Fossil, you sync/push/pull |
| 128 | everything - all branches, all wiki, all tickets, all forum posts, |
| 129 | all tags, all technotes - everything. |
| 130 | |
| 131 | ## The Main Branch Is Called "`trunk`" |
| 132 | |
| 133 | In Fossil, the traditional name and the default name for the main branch |
| 134 | is "`trunk`". The "`trunk`" branch in Fossil corresponds to the |
| 135 | "`master`" branch in stock Git or the "`main`" branch in GitHub. |
| @@ -141,28 +167,40 @@ | |
| 141 | [later rename it][ghmain]. |
| 142 | |
| 143 | [6]: ./mirrortogithub.md |
| 144 | [ghmain]: https://github.com/github/renaming |
| 145 | |
| 146 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 147 | |
| 148 | The "`fossil status`" command shows you what files in your check-out have |
| 149 | been edited and scheduled for adding or removing at the next commit. |
| 150 | But unlike "`git status`", the "`fossil status`" command does not warn |
| 151 | you about unmanaged files in your local check-out. There is a separate |
| 152 | "`fossil extras`" command for that. |
| 153 | |
| 154 | ## There Is No Rebase |
| 155 | |
| 156 | Fossil does not support rebase. |
| 157 | This is a [deliberate design decision][3] that has been thoroughly, |
| 158 | carefully, and throughtfully discussed, many times. If you are fond |
| 159 | of rebase, you should read the [Rebase Considered Harmful][3] document |
| 160 | carefully before expressing your views. |
| 161 | |
| 162 | [3]: ./rebaseharm.md |
| 163 | |
| 164 | ## Branch and Tag Names |
| 165 | |
| 166 | Fossil has no special restrictions on the names of tags and branches, |
| 167 | though you might want to keep [Git's tag and branch name restrictions][4] |
| 168 | in mind if you plan on mirroring your Fossil repository to GitHub. |
| @@ -169,46 +207,47 @@ | |
| 169 | |
| 170 | [4]: https://git-scm.com/docs/git-check-ref-format |
| 171 | |
| 172 | Fossil does not require tag and branch names to be unique. It is |
| 173 | common, for example, to put a "`release`" tag on every release for a |
| 174 | Fossil-hosted project. |
| 175 | |
| 176 | ## Only One "origin" At A Time |
| 177 | |
| 178 | A Fossil repository only keeps track of one "origin" server at a time. |
| 179 | If you specify a new "origin" it forgets the previous one. Use the |
| 180 | "`fossil remote`" command to see or change the "origin". |
| 181 | |
| 182 | Fossil uses a very different sync protocol than Git, so it isn't as |
| 183 | important for Fossil to keep track of multiple origins as it is with |
| 184 | Git. So only having a single origin has never been a big enough problem |
| 185 | in Fossil that somebody felt the need to extend it. |
| 186 | |
| 187 | Maybe we will add multiple origin support to Fossil someday. Patches |
| 188 | are welcomed if you want to have a go at it. |
| 189 | |
| 190 | ## Cherry-pick Is An Option To The "merge" Command |
| 191 | |
| 192 | In Git, "`git cherry-pick`" is a separate command. |
| 193 | In Fossil, "`fossil merge --cherrypick`" is an option on the merge |
| 194 | command. Otherwise, they work mostly the same. |
| 195 | |
| 196 | Except, the Fossil file format remembers cherrypicks and actually |
| 197 | shows them as dashed lines on the graphical DAG display, whereas |
| 198 | there is no provision for recording cherry-picks in the Git file |
| 199 | format, so you have to talk about the cherry-pick in the commit |
| 200 | comment if you want to remember it. |
| 201 | |
| 202 | ## The "`fossil mv`" and "`fossil rm`" Commands Do Not Actually Rename Or Delete The Files (by default) |
| 203 | |
| 204 | By default, |
| 205 | the "`fossil mv`" and "`fossil rm`" commands work like they do in CVS in |
| 206 | that they schedule the changes for the next commit, but do not actually |
| 207 | rename or delete the files in your check-out. You can to add the "--hard" |
| 208 | option to also changes the files in your check-out. |
| 209 | If you run |
| 210 | |
| 211 | fossil setting --global mv-rm-files 1 |
| 212 | |
| 213 | it makes a notation in your per-user "~/.fossil" settings file so that |
| 214 | the "--hard" behavior becomes the new default. |
| 215 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -2,10 +2,11 @@ | |
| 2 | |
| 3 | This document is a semi-random collection of hints intended to help |
| 4 | new users of Fossil who have had prior exposure to Git. In other words, |
| 5 | this document tries to describe the differences in how Fossil works |
| 6 | from the perspective of Git users. |
| 7 | |
| 8 | |
| 9 | ## Help Improve This Document |
| 10 | |
| 11 | If you have a lot of prior Git experience, and you are new to Fossil |
| 12 | and are struggling with some concepts, please ask for help on the |
| @@ -18,10 +19,12 @@ | |
| 19 | [1]: https://fossil-scm.org/forum |
| 20 | |
| 21 | Specific suggestions on how to improve this document are also welcomed, |
| 22 | of course. |
| 23 | |
| 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 |
| @@ -54,10 +57,12 @@ | |
| 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 | |
| 66 | Fossil omits the "Git index" or "staging area" concept. When you |
| 67 | type "`fossil commit`" _all_ changes in your check-out are committed, |
| 68 | automatically. There is no need for the "-a" option as with Git. |
| @@ -65,10 +70,12 @@ | |
| 70 | If you only want to commit just some of the changes, you can list the names |
| 71 | of the files you want to commit as arguments, like this: |
| 72 | |
| 73 | fossil commit src/main.c doc/readme.md |
| 74 | |
| 75 | |
| 76 | <a id="bneed"></a> |
| 77 | ## Create Branches At Point Of Need, Rather Than Ahead of Need |
| 78 | |
| 79 | Fossil prefers that you create new branches as part of the first commit |
| 80 | on that branch: |
| 81 | |
| @@ -102,10 +109,12 @@ | |
| 109 | (“current” is one of the [special check-in names][scin] in Fossil. See |
| 110 | that document for the many other names you can give to “`amend`”.) |
| 111 | |
| 112 | [scin]: ./checkin_names.wiki |
| 113 | |
| 114 | |
| 115 | <a id="autosync"></a> |
| 116 | ## Autosync |
| 117 | |
| 118 | Fossil has a feature called "[autosync][5]". Autosync defaults on. |
| 119 | When autosync is enabled, Fossil automatically pushes your changes |
| 120 | to the remote server whenever you "`fossil commit`". It also automatically |
| @@ -119,17 +128,34 @@ | |
| 128 | control. Your work stays synced up with your coworkers at all times. |
| 129 | If your local machine dies catastrophically, you haven't lost any |
| 130 | (committed) work. But you can still work and commit while off network, |
| 131 | with changes resyncing automatically when you get back on-line. |
| 132 | |
| 133 | |
| 134 | <a id="syncall"></a> |
| 135 | ## Syncing Is All-Or-Nothing |
| 136 | |
| 137 | Fossil does not support the concept of syncing, pushing, or pulling |
| 138 | individual branches. When you sync/push/pull in Fossil, you sync/push/pull |
| 139 | everything: all branches, all wiki, all tickets, all forum posts, |
| 140 | all tags, all technotes… Everything. |
| 141 | |
| 142 | Furthermore, branch *names* sync automatically in Fossil, not just the |
| 143 | content of those branches. This means this common Git command: |
| 144 | |
| 145 | git push origin master |
| 146 | |
| 147 | is simply this in Fossil: |
| 148 | |
| 149 | fossil push |
| 150 | |
| 151 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 152 | keeps using the same remote server URL and branch name you gave it last, |
| 153 | until you tell it to do something different. |
| 154 | |
| 155 | |
| 156 | <a id="trunk"></a> |
| 157 | ## The Main Branch Is Called "`trunk`" |
| 158 | |
| 159 | In Fossil, the traditional name and the default name for the main branch |
| 160 | is "`trunk`". The "`trunk`" branch in Fossil corresponds to the |
| 161 | "`master`" branch in stock Git or the "`main`" branch in GitHub. |
| @@ -141,28 +167,40 @@ | |
| 167 | [later rename it][ghmain]. |
| 168 | |
| 169 | [6]: ./mirrortogithub.md |
| 170 | [ghmain]: https://github.com/github/renaming |
| 171 | |
| 172 | |
| 173 | <a id="unmanaged"></a> |
| 174 | ## The "`fossil status`" Command Does Not Show Unmanaged Files |
| 175 | |
| 176 | The "`fossil status`" command shows you what files in your check-out have |
| 177 | been edited and scheduled for adding or removing at the next commit. |
| 178 | But unlike "`git status`", the "`fossil status`" command does not warn |
| 179 | you about unmanaged files in your local check-out. There is a separate |
| 180 | "`fossil extras`" command for that. |
| 181 | |
| 182 | |
| 183 | <a id="rebase"></a> |
| 184 | ## There Is No Rebase |
| 185 | |
| 186 | Fossil does not support rebase, [on purpose][3]. |
| 187 | |
| 188 | This is a deliberate design decision that the Fossil community has |
| 189 | thought about carefully and discussed many times, resulting in the |
| 190 | linked document. If you are fond of rebase, you should read it carefully |
| 191 | before expressing your views: it not only answers many of the common |
| 192 | arguments in favor of rebase known at the time the document’s first |
| 193 | draft was written, it’s been revised multiple times to address less |
| 194 | common objections as well. Chances are not good that you are going to |
| 195 | come up with a new objection that we haven’t already considered and |
| 196 | addressed there. |
| 197 | |
| 198 | [3]: ./rebaseharm.md |
| 199 | |
| 200 | |
| 201 | <a id="btnames"></a> |
| 202 | ## Branch and Tag Names |
| 203 | |
| 204 | Fossil has no special restrictions on the names of tags and branches, |
| 205 | though you might want to keep [Git's tag and branch name restrictions][4] |
| 206 | in mind if you plan on mirroring your Fossil repository to GitHub. |
| @@ -169,46 +207,47 @@ | |
| 207 | |
| 208 | [4]: https://git-scm.com/docs/git-check-ref-format |
| 209 | |
| 210 | Fossil does not require tag and branch names to be unique. It is |
| 211 | common, for example, to put a "`release`" tag on every release for a |
| 212 | Fossil-hosted project. This does not create a conflict in Fossil, since |
| 213 | Fossil resolves such conflicts in a predictable way: the newest match |
| 214 | wins. Therefore, “`fossil up release`” always gets you the current |
| 215 | release in a project that uses this tagging convention. |
| 216 | |
| 217 | |
| 218 | <a id="cpickrev"></a> |
| 219 | ## Cherry-Picking and Reverting Commits |
| 220 | |
| 221 | Git’s separate "`git cherry-pick`" and “`git revert`” commands are |
| 222 | options to the [`fossil merge` command][merge]: `--cherrypick` and |
| 223 | `--backout`, respectively. |
| 224 | |
| 225 | Unlike in Git, the Fossil file format remembers cherrypicks and backouts |
| 226 | and can later show them as dashed lines on the graphical timeline. |
| 227 | |
| 228 | [merge]: /help?cmd=merge |
| 229 | |
| 230 | |
| 231 | |
| 232 | <a id="mvrm"></a> |
| 233 | ## File Moves And Renames Are Soft By Default |
| 234 | |
| 235 | The "[`fossil mv`][mv]" and "[`fossil rm`][rm]" commands work like they |
| 236 | do in CVS in that they schedule the changes for the next commit by |
| 237 | default: they do not actually rename or delete the files in your |
| 238 | check-out. |
| 239 | |
| 240 | If you don’t like that default, you can change it globally: |
| 241 | |
| 242 | fossil setting --global mv-rm-files 1 |
| 243 | |
| 244 | Now these commands behave like in Git in any Fossil repository where |
| 245 | this setting hasn’t been overridden locally. |
| 246 | |
| 247 | If you want to keep Fossil’s soft `mv/rm` behavior most of the time, you |
| 248 | can cast it away on a per-command basis: |
| 249 | |
| 250 | fossil mv --hard old-name new-name |
| 251 | |
| 252 | [mv]: /help?cmd=mv |
| 253 | [rm]: /help?cmd=rm |
| 254 |