Fossil SCM
Remove indentation from the quickstart document, to make it more mobile-friendly.
Commit
3ff09684873cb5759a5a5d0b57dc3749214342c01b56fbd5d9f33258a52984d4
Parent
390bb86563e403a…
1 file changed
+504
-504
+504
-504
| --- www/quickstart.wiki | ||
| +++ www/quickstart.wiki | ||
| @@ -4,552 +4,552 @@ | ||
| 4 | 4 | <p>This is a guide to help you get started using the Fossil [https://en.wikipedia.org/wiki/Distributed_version_control|Distributed Version Control System] quickly |
| 5 | 5 | and painlessly.</p> |
| 6 | 6 | |
| 7 | 7 | <h2 id="install">Installing</h2> |
| 8 | 8 | |
| 9 | - <p>Fossil is a single self-contained C program. You need to | |
| 10 | - either download a | |
| 11 | - [https://www.fossil-scm.org/fossil/uv/download.html|precompiled | |
| 12 | - binary] | |
| 13 | - or <a href="build.wiki">compile it yourself</a> from sources. | |
| 14 | - Install Fossil by putting the fossil binary | |
| 15 | - someplace on your $PATH.</p> | |
| 16 | - You can test that Fossil is present and working like this: | |
| 17 | - | |
| 18 | - <blockquote> | |
| 19 | - <b> | |
| 20 | - fossil version<br> | |
| 21 | - <tt>This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC</tt><br> | |
| 22 | - </b> | |
| 23 | - </blockquote> | |
| 9 | +<p>Fossil is a single self-contained C program. You need to | |
| 10 | +either download a | |
| 11 | +[https://www.fossil-scm.org/fossil/uv/download.html|precompiled | |
| 12 | +binary] | |
| 13 | +or <a href="build.wiki">compile it yourself</a> from sources. | |
| 14 | +Install Fossil by putting the fossil binary | |
| 15 | +someplace on your $PATH.</p> | |
| 16 | +You can test that Fossil is present and working like this: | |
| 17 | + | |
| 18 | +<blockquote> | |
| 19 | +<b> | |
| 20 | +fossil version<br> | |
| 21 | +<tt>This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC</tt><br> | |
| 22 | +</b> | |
| 23 | +</blockquote> | |
| 24 | 24 | |
| 25 | 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | 26 | |
| 27 | - <p>Fossil works with repository files (a database in a single file with the project's | |
| 28 | - complete history) and with checked-out local trees (the working directory | |
| 29 | - you use to do your work). | |
| 30 | - (See [./whyusefossil.wiki#definitions | definitions] for more background.) | |
| 31 | - The workflow looks like this:</p> | |
| 32 | - | |
| 33 | - <ul> | |
| 34 | - <li>Create or clone a repository file. ([/help/init|fossil init] or | |
| 35 | - [/help/clone | fossil clone]) | |
| 36 | - <li>Check out a local tree. ([/help/open | fossil open]) | |
| 37 | - <li>Perform operations on the repository (including repository | |
| 38 | - configuration). | |
| 39 | - </ul> | |
| 40 | - | |
| 41 | - Fossil can be entirely driven from the command line. Many features | |
| 42 | - can also be conveniently accessed from the build-in web interface. | |
| 43 | - | |
| 44 | - <p>The following sections give a brief overview of these | |
| 45 | - operations.</p> | |
| 27 | +<p>Fossil works with repository files (a database in a single file with the project's | |
| 28 | +complete history) and with checked-out local trees (the working directory | |
| 29 | +you use to do your work). | |
| 30 | +(See [./whyusefossil.wiki#definitions | definitions] for more background.) | |
| 31 | +The workflow looks like this:</p> | |
| 32 | + | |
| 33 | +<ul> | |
| 34 | + <li>Create or clone a repository file. ([/help/init|fossil init] or | |
| 35 | + [/help/clone | fossil clone]) | |
| 36 | + <li>Check out a local tree. ([/help/open | fossil open]) | |
| 37 | + <li>Perform operations on the repository (including repository | |
| 38 | + configuration). | |
| 39 | +</ul> | |
| 40 | + | |
| 41 | +Fossil can be entirely driven from the command line. Many features | |
| 42 | +can also be conveniently accessed from the build-in web interface. | |
| 43 | + | |
| 44 | +<p>The following sections give a brief overview of these | |
| 45 | +operations.</p> | |
| 46 | 46 | |
| 47 | 47 | <h2 id="new">Starting A New Project</h2> |
| 48 | 48 | |
| 49 | - <p>To start a new project with fossil create a new empty repository | |
| 50 | - this way: ([/help/init | more info]) </p> | |
| 51 | - | |
| 52 | - <blockquote> | |
| 53 | - <b>fossil init </b><i> repository-filename</i> | |
| 54 | - </blockquote> | |
| 55 | - | |
| 56 | - You can name the database anything you like, and you can place it anywhere in the filesystem. | |
| 57 | - The <tt>.fossil</tt> extension is traditional but only required if you are going to use the | |
| 58 | - <tt>[./help?cmd=/server | fossil server DIRECTORY]</tt> feature.” | |
| 49 | +<p>To start a new project with fossil create a new empty repository | |
| 50 | +this way: ([/help/init | more info]) </p> | |
| 51 | + | |
| 52 | +<blockquote> | |
| 53 | +<b>fossil init </b><i> repository-filename</i> | |
| 54 | +</blockquote> | |
| 55 | + | |
| 56 | +You can name the database anything you like, and you can place it anywhere in the filesystem. | |
| 57 | +The <tt>.fossil</tt> extension is traditional but only required if you are going to use the | |
| 58 | +<tt>[./help?cmd=/server | fossil server DIRECTORY]</tt> feature.” | |
| 59 | 59 | |
| 60 | 60 | <h2 id="clone">Cloning An Existing Repository</h2> |
| 61 | 61 | |
| 62 | - <p>Most fossil operations interact with a repository that is on the | |
| 63 | - local disk drive, not on a remote system. Hence, before accessing | |
| 64 | - a remote repository it is necessary to make a local copy of that | |
| 65 | - repository. Making a local copy of a remote repository is called | |
| 66 | - "cloning".</p> | |
| 67 | - | |
| 68 | - <p>Clone a remote repository as follows: ([/help/clone | more info])</p> | |
| 69 | - | |
| 70 | - <blockquote> | |
| 71 | - <b>fossil clone</b> <i>URL repository-filename</i> | |
| 72 | - </blockquote> | |
| 73 | - | |
| 74 | - <p>The <i>URL</i> specifies the fossil repository | |
| 75 | - you want to clone. The <i>repository-filename</i> is the new local | |
| 76 | - filename into which the cloned repository will be written. For | |
| 77 | - example, to clone the source code of Fossil itself: | |
| 78 | - | |
| 79 | - <blockquote> | |
| 80 | - <b>fossil clone https://www.fossil-scm.org/ myclone.fossil</b> | |
| 81 | - </blockquote> | |
| 82 | - | |
| 83 | - If your logged-in username is 'exampleuser', you should see output something like this: | |
| 84 | - | |
| 85 | - <blockquote> | |
| 86 | - <b><tt> | |
| 87 | - Round-trips: 8 Artifacts sent: 0 received: 39421<br> | |
| 88 | - Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0<br> | |
| 89 | - Rebuilding repository meta-data...<br> | |
| 90 | - 100% complete...<br> | |
| 91 | - Extra delta compression... <br> | |
| 92 | - Vacuuming the database... <br> | |
| 93 | - project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333<br> | |
| 94 | - server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> | |
| 95 | - admin-user: exampleuser (password is "yoWgDR42iv")><br> | |
| 96 | - </tt></b> | |
| 97 | - </blockquote> | |
| 98 | - | |
| 99 | - <p>If the remote repository requires a login, include a | |
| 100 | - userid in the URL like this: | |
| 101 | - | |
| 102 | - <blockquote> | |
| 103 | - <b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> | |
| 104 | - </blockquote> | |
| 105 | - | |
| 106 | - <p>You will be prompted separately for the password. | |
| 107 | - Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. | |
| 108 | - For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") </p> | |
| 109 | - | |
| 110 | - <p>If you are behind a restrictive firewall, you might need | |
| 111 | - to <a href="#proxy">specify an HTTP proxy</a>.</p> | |
| 112 | - | |
| 113 | - <p>A Fossil repository is a single disk file. Instead of cloning, | |
| 114 | - you can just make a copy of the repository file (for example, using | |
| 115 | - "scp"). Note, however, that the repository file contains auxiliary | |
| 116 | - information above and beyond the versioned files, including some | |
| 117 | - sensitive information such as password hashes and email addresses. If you | |
| 118 | - want to share Fossil repositories directly by copying, consider running the | |
| 119 | - [/help/scrub|fossil scrub] command to remove sensitive information | |
| 120 | - before transmitting the file. | |
| 62 | +<p>Most fossil operations interact with a repository that is on the | |
| 63 | +local disk drive, not on a remote system. Hence, before accessing | |
| 64 | +a remote repository it is necessary to make a local copy of that | |
| 65 | +repository. Making a local copy of a remote repository is called | |
| 66 | +"cloning".</p> | |
| 67 | + | |
| 68 | +<p>Clone a remote repository as follows: ([/help/clone | more info])</p> | |
| 69 | + | |
| 70 | +<blockquote> | |
| 71 | +<b>fossil clone</b> <i>URL repository-filename</i> | |
| 72 | +</blockquote> | |
| 73 | + | |
| 74 | +<p>The <i>URL</i> specifies the fossil repository | |
| 75 | +you want to clone. The <i>repository-filename</i> is the new local | |
| 76 | +filename into which the cloned repository will be written. For | |
| 77 | +example, to clone the source code of Fossil itself: | |
| 78 | + | |
| 79 | +<blockquote> | |
| 80 | +<b>fossil clone https://www.fossil-scm.org/ myclone.fossil</b> | |
| 81 | +</blockquote> | |
| 82 | + | |
| 83 | +If your logged-in username is 'exampleuser', you should see output something like this: | |
| 84 | + | |
| 85 | +<blockquote> | |
| 86 | +<b><tt> | |
| 87 | + Round-trips: 8 Artifacts sent: 0 received: 39421<br> | |
| 88 | + Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0<br> | |
| 89 | + Rebuilding repository meta-data...<br> | |
| 90 | + 100% complete...<br> | |
| 91 | + Extra delta compression... <br> | |
| 92 | + Vacuuming the database... <br> | |
| 93 | + project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333<br> | |
| 94 | + server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> | |
| 95 | + admin-user: exampleuser (password is "yoWgDR42iv")><br> | |
| 96 | +</tt></b> | |
| 97 | +</blockquote> | |
| 98 | + | |
| 99 | +<p>If the remote repository requires a login, include a | |
| 100 | +userid in the URL like this: | |
| 101 | + | |
| 102 | +<blockquote> | |
| 103 | +<b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> | |
| 104 | +</blockquote> | |
| 105 | + | |
| 106 | +<p>You will be prompted separately for the password. | |
| 107 | + Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. | |
| 108 | + For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") </p> | |
| 109 | + | |
| 110 | +<p>If you are behind a restrictive firewall, you might need | |
| 111 | +to <a href="#proxy">specify an HTTP proxy</a>.</p> | |
| 112 | + | |
| 113 | +<p>A Fossil repository is a single disk file. Instead of cloning, | |
| 114 | +you can just make a copy of the repository file (for example, using | |
| 115 | +"scp"). Note, however, that the repository file contains auxiliary | |
| 116 | +information above and beyond the versioned files, including some | |
| 117 | +sensitive information such as password hashes and email addresses. If you | |
| 118 | +want to share Fossil repositories directly by copying, consider running the | |
| 119 | +[/help/scrub|fossil scrub] command to remove sensitive information | |
| 120 | +before transmitting the file. | |
| 121 | 121 | |
| 122 | 122 | <h2 id="import">Importing From Another Version Control System</h2> |
| 123 | 123 | |
| 124 | - <p>Rather than start a new project, or clone an existing Fossil project, | |
| 125 | - you might prefer to | |
| 126 | - <a href="./inout.wiki">import an existing Git project</a> | |
| 127 | - into Fossil using the [/help/import | fossil import] command. | |
| 128 | - | |
| 129 | - You can even decide to export your project back into git using the | |
| 130 | - [/help/git | fossil git] command, which is how the Fossil project maintains | |
| 131 | - [https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There | |
| 132 | - is no limit to the number of times a tree can be imported and exported between | |
| 133 | - Fossil and git. | |
| 134 | - | |
| 135 | - The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become | |
| 136 | - a popular way to move files between version management systems, including from | |
| 137 | - [https://www.mercurial-scm.org/|Mercurial]. | |
| 138 | - Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. | |
| 124 | +<p>Rather than start a new project, or clone an existing Fossil project, | |
| 125 | +you might prefer to | |
| 126 | +<a href="./inout.wiki">import an existing Git project</a> | |
| 127 | +into Fossil using the [/help/import | fossil import] command. | |
| 128 | + | |
| 129 | +You can even decide to export your project back into git using the | |
| 130 | +[/help/git | fossil git] command, which is how the Fossil project maintains | |
| 131 | +[https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There | |
| 132 | +is no limit to the number of times a tree can be imported and exported between | |
| 133 | +Fossil and git. | |
| 134 | + | |
| 135 | +The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become | |
| 136 | +a popular way to move files between version management systems, including from | |
| 137 | +[https://www.mercurial-scm.org/|Mercurial]. | |
| 138 | +Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. | |
| 139 | 139 | |
| 140 | 140 | <h2 id="checkout">Checking Out A Local Tree</h2> |
| 141 | 141 | |
| 142 | - <p>To work on a project in fossil, you need to check out a local | |
| 143 | - copy of the source tree. Create the directory you want to be | |
| 144 | - the root of your tree and cd into that directory. Then | |
| 145 | - do this: ([/help/open | more info])</p> | |
| 146 | - | |
| 147 | - <blockquote> | |
| 148 | - <b>fossil open </b><i> repository-filename</i> | |
| 149 | - </blockquote> | |
| 150 | - | |
| 151 | - for example: | |
| 152 | - | |
| 153 | - <blockquote> | |
| 154 | - <b><tt> | |
| 155 | - fossil open ../myclone.fossil<br> | |
| 156 | - BUILD.txt<br> | |
| 157 | - COPYRIGHT-BSD2.txt<br> | |
| 158 | - README.md<br> | |
| 159 | - ︙<br> | |
| 160 | - </tt></b> | |
| 161 | - </blockquote> | |
| 162 | - | |
| 163 | - (or "fossil open ..\myclone.fossil" on Windows). | |
| 164 | - | |
| 165 | - <p>This leaves you with the newest version of the tree | |
| 166 | - checked out. | |
| 167 | - From anywhere underneath the root of your local tree, you | |
| 168 | - can type commands like the following to find out the status of | |
| 169 | - your local tree:</p> | |
| 170 | - | |
| 171 | - <blockquote> | |
| 172 | - <b>[/help/info | fossil info]</b><br> | |
| 173 | - <b>[/help/status | fossil status]</b><br> | |
| 174 | - <b>[/help/changes | fossil changes]</b><br> | |
| 175 | - <b>[/help/diff | fossil diff]</b><br> | |
| 176 | - <b>[/help/timeline | fossil timeline]</b><br> | |
| 177 | - <b>[/help/ls | fossil ls]</b><br> | |
| 178 | - <b>[/help/branch | fossil branch]</b><br> | |
| 179 | - </blockquote> | |
| 180 | - | |
| 181 | - <p>If you created a new respository using "fossil init" some commands will not | |
| 182 | - produce much output.</p> | |
| 183 | - | |
| 184 | - <p>Note that Fossil allows you to make multiple check-outs in | |
| 185 | - separate directories from the same repository. This enables you, | |
| 186 | - for example, to do builds from multiple branches or versions at | |
| 187 | - the same time without having to generate extra clones.</p> | |
| 188 | - | |
| 189 | - <p>To switch a checkout between different versions and branches, | |
| 190 | - use:</p> | |
| 191 | - | |
| 192 | - <blockquote> | |
| 193 | - <b>[/help/update | fossil update]</b><br> | |
| 194 | - <b>[/help/checkout | fossil checkout]</b><br> | |
| 195 | - </blockquote> | |
| 196 | - | |
| 197 | - <p>[/help/update | update] honors the "autosync" option and | |
| 198 | - does a "soft" switch, merging any local changes into the target | |
| 199 | - version, whereas [/help/checkout | checkout] does not | |
| 200 | - automatically sync and does a "hard" switch, overwriting local | |
| 201 | - changes if told to do so.</p> | |
| 142 | +<p>To work on a project in fossil, you need to check out a local | |
| 143 | +copy of the source tree. Create the directory you want to be | |
| 144 | +the root of your tree and cd into that directory. Then | |
| 145 | +do this: ([/help/open | more info])</p> | |
| 146 | + | |
| 147 | +<blockquote> | |
| 148 | +<b>fossil open </b><i> repository-filename</i> | |
| 149 | +</blockquote> | |
| 150 | + | |
| 151 | +for example: | |
| 152 | + | |
| 153 | +<blockquote> | |
| 154 | +<b><tt> | |
| 155 | + fossil open ../myclone.fossil<br> | |
| 156 | + BUILD.txt<br> | |
| 157 | + COPYRIGHT-BSD2.txt<br> | |
| 158 | + README.md<br> | |
| 159 | + ︙<br> | |
| 160 | +</tt></b> | |
| 161 | +</blockquote> | |
| 162 | + | |
| 163 | +(or "fossil open ..\myclone.fossil" on Windows). | |
| 164 | + | |
| 165 | +<p>This leaves you with the newest version of the tree | |
| 166 | +checked out. | |
| 167 | +From anywhere underneath the root of your local tree, you | |
| 168 | +can type commands like the following to find out the status of | |
| 169 | +your local tree:</p> | |
| 170 | + | |
| 171 | +<blockquote> | |
| 172 | +<b>[/help/info | fossil info]</b><br> | |
| 173 | +<b>[/help/status | fossil status]</b><br> | |
| 174 | +<b>[/help/changes | fossil changes]</b><br> | |
| 175 | +<b>[/help/diff | fossil diff]</b><br> | |
| 176 | +<b>[/help/timeline | fossil timeline]</b><br> | |
| 177 | +<b>[/help/ls | fossil ls]</b><br> | |
| 178 | +<b>[/help/branch | fossil branch]</b><br> | |
| 179 | +</blockquote> | |
| 180 | + | |
| 181 | +<p>If you created a new respository using "fossil init" some commands will not | |
| 182 | +produce much output.</p> | |
| 183 | + | |
| 184 | +<p>Note that Fossil allows you to make multiple check-outs in | |
| 185 | +separate directories from the same repository. This enables you, | |
| 186 | +for example, to do builds from multiple branches or versions at | |
| 187 | +the same time without having to generate extra clones.</p> | |
| 188 | + | |
| 189 | +<p>To switch a checkout between different versions and branches, | |
| 190 | +use:</p> | |
| 191 | + | |
| 192 | +<blockquote> | |
| 193 | +<b>[/help/update | fossil update]</b><br> | |
| 194 | +<b>[/help/checkout | fossil checkout]</b><br> | |
| 195 | +</blockquote> | |
| 196 | + | |
| 197 | +<p>[/help/update | update] honors the "autosync" option and | |
| 198 | +does a "soft" switch, merging any local changes into the target | |
| 199 | +version, whereas [/help/checkout | checkout] does not | |
| 200 | +automatically sync and does a "hard" switch, overwriting local | |
| 201 | +changes if told to do so.</p> | |
| 202 | 202 | |
| 203 | 203 | <h2 id="changes">Making and Commiting Changes</h2> |
| 204 | 204 | |
| 205 | - <p>To add new files to your project or remove existing ones, use these | |
| 206 | - commands:</p> | |
| 207 | - | |
| 208 | - <blockquote> | |
| 209 | - <b>[/help/add | fossil add]</b> <i>file...</i><br> | |
| 210 | - <b>[/help/rm | fossil rm]</b> <i>file...</i><br> | |
| 211 | - <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> | |
| 212 | - </blockquote> | |
| 213 | - | |
| 214 | - <p>The command:</p> | |
| 215 | - <blockquote> | |
| 216 | - <b> | |
| 217 | - [/help/changes | fossil changes]</b> | |
| 218 | - </blockquote> | |
| 219 | - <p>lists files that have changed since the last commit to the repository. For | |
| 220 | - example, if you edit the file "README.md":</p> | |
| 221 | - | |
| 222 | - <blockquote> | |
| 223 | - <b> | |
| 224 | - fossil changes<br> | |
| 225 | - EDITED README.md | |
| 226 | - </b> | |
| 227 | - </blockquote> | |
| 228 | - | |
| 229 | - <p>To see exactly what change was made you can use the command</p> | |
| 230 | - [/help/diff | fossil diff]: | |
| 231 | - <blockquote> | |
| 232 | - <b> | |
| 233 | - fossil diff <br><tt> | |
| 234 | - Index: README.md<br> | |
| 235 | - ============================================================<br> | |
| 236 | - --- README.md<br> | |
| 237 | - +++ README.md<br> | |
| 238 | - @@ -1,5 +1,6 @@<br> | |
| 239 | - +Made some changes to the project<br> | |
| 240 | - # Original text<br> | |
| 241 | - </tt></b> | |
| 242 | - </blockquote> | |
| 243 | - | |
| 244 | - <p>"fossil diff" is the difference between your tree on disk now and as the tree was | |
| 245 | - when you did "fossil open". An open is the first checkout from a repository | |
| 246 | - into a new directory. </p> | |
| 247 | - | |
| 248 | - <p>To commit your changes to a local-only repository:</p> | |
| 249 | - <blockquote> | |
| 250 | - <b> | |
| 251 | - fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> | |
| 252 | - # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> | |
| 253 | - #<br> | |
| 254 | - # user: exampleuser<br> | |
| 255 | - # tags: trunk<br> | |
| 256 | - #<br> | |
| 257 | - # EDITED README.md<br> | |
| 258 | - Edited file to add description of code changes<br> | |
| 259 | - New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> | |
| 260 | - </tt></b> | |
| 261 | - </blockquote> | |
| 262 | - | |
| 263 | - <p>You will be prompted for check-in comments using whatever editor | |
| 264 | - is specified by your VISUAL or EDITOR environment variable. If none is | |
| 265 | - specified Fossil uses line-editing in the terminal.</p> | |
| 266 | - | |
| 267 | - <p>To commit your changes to a repository that was cloned from remote you | |
| 268 | - perform the same actions but the results are different. Fossil | |
| 269 | - defaults to 'autosync' mode, a single-stage commit that sends all changes | |
| 270 | - committed to the local repository immediately on to the remote parent repository. This | |
| 271 | - only works if you have write permission to the remote respository.</p> | |
| 205 | +<p>To add new files to your project or remove existing ones, use these | |
| 206 | +commands:</p> | |
| 207 | + | |
| 208 | +<blockquote> | |
| 209 | +<b>[/help/add | fossil add]</b> <i>file...</i><br> | |
| 210 | +<b>[/help/rm | fossil rm]</b> <i>file...</i><br> | |
| 211 | +<b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> | |
| 212 | +</blockquote> | |
| 213 | + | |
| 214 | +<p>The command:</p> | |
| 215 | +<blockquote> | |
| 216 | +<b> | |
| 217 | + [/help/changes | fossil changes]</b> | |
| 218 | +</blockquote> | |
| 219 | +<p>lists files that have changed since the last commit to the repository. For | |
| 220 | +example, if you edit the file "README.md":</p> | |
| 221 | + | |
| 222 | +<blockquote> | |
| 223 | +<b> | |
| 224 | + fossil changes<br> | |
| 225 | + EDITED README.md | |
| 226 | +</b> | |
| 227 | +</blockquote> | |
| 228 | + | |
| 229 | +<p>To see exactly what change was made you can use the command</p> | |
| 230 | +[/help/diff | fossil diff]: | |
| 231 | +<blockquote> | |
| 232 | +<b> | |
| 233 | + fossil diff <br><tt> | |
| 234 | + Index: README.md<br> | |
| 235 | + ============================================================<br> | |
| 236 | + --- README.md<br> | |
| 237 | + +++ README.md<br> | |
| 238 | + @@ -1,5 +1,6 @@<br> | |
| 239 | + +Made some changes to the project<br> | |
| 240 | + # Original text<br> | |
| 241 | + </tt></b> | |
| 242 | +</blockquote> | |
| 243 | + | |
| 244 | +<p>"fossil diff" is the difference between your tree on disk now and as the tree was | |
| 245 | +when you did "fossil open". An open is the first checkout from a repository | |
| 246 | +into a new directory. </p> | |
| 247 | + | |
| 248 | +<p>To commit your changes to a local-only repository:</p> | |
| 249 | +<blockquote> | |
| 250 | +<b> | |
| 251 | +fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> | |
| 252 | +# Enter a commit message for this check-in. Lines beginning with # are ignored.<br> | |
| 253 | +#<br> | |
| 254 | +# user: exampleuser<br> | |
| 255 | +# tags: trunk<br> | |
| 256 | +#<br> | |
| 257 | +# EDITED README.md<br> | |
| 258 | +Edited file to add description of code changes<br> | |
| 259 | +New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> | |
| 260 | +</tt></b> | |
| 261 | +</blockquote> | |
| 262 | + | |
| 263 | +<p>You will be prompted for check-in comments using whatever editor | |
| 264 | +is specified by your VISUAL or EDITOR environment variable. If none is | |
| 265 | +specified Fossil uses line-editing in the terminal.</p> | |
| 266 | + | |
| 267 | +<p>To commit your changes to a repository that was cloned from remote you | |
| 268 | +perform the same actions but the results are different. Fossil | |
| 269 | +defaults to 'autosync' mode, a single-stage commit that sends all changes | |
| 270 | +committed to the local repository immediately on to the remote parent repository. This | |
| 271 | +only works if you have write permission to the remote respository.</p> | |
| 272 | 272 | |
| 273 | 273 | <h2 id="naming">Naming of Files, Checkins, and Branches</h2> |
| 274 | 274 | |
| 275 | - <p>Fossil deals with information artifacts. This Quickstart document only deals | |
| 276 | - with files and collections of files, but be aware there are also tickets, wiki pages and more. | |
| 277 | - Every artifact in Fossil has a universally-unique hash id, and may also have a | |
| 278 | - human-readable name.</p> | |
| 279 | - | |
| 280 | - <p>The following are all equivalent ways of identifying a Fossil file, | |
| 281 | - checkin or branch artifact:</p> | |
| 282 | - | |
| 283 | - <ul> | |
| 284 | - <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a | |
| 285 | - <li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters | |
| 286 | - <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash | |
| 287 | - </ul> | |
| 288 | - | |
| 289 | - <p>A special convenience branch is "trunk", which is Fossil's default branch name for | |
| 290 | - the first checkin, and the default for any time a branch name is needed but not | |
| 291 | - specified.</p> | |
| 292 | - | |
| 293 | - This will get you started on identifying checkins. The | |
| 294 | - <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including | |
| 295 | - how timestamps can also be used. | |
| 275 | +<p>Fossil deals with information artifacts. This Quickstart document only deals | |
| 276 | +with files and collections of files, but be aware there are also tickets, wiki pages and more. | |
| 277 | +Every artifact in Fossil has a universally-unique hash id, and may also have a | |
| 278 | +human-readable name.</p> | |
| 279 | + | |
| 280 | +<p>The following are all equivalent ways of identifying a Fossil file, | |
| 281 | +checkin or branch artifact:</p> | |
| 282 | + | |
| 283 | +<ul> | |
| 284 | +<li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a | |
| 285 | +<li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters | |
| 286 | +<li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash | |
| 287 | +</ul> | |
| 288 | + | |
| 289 | +<p>A special convenience branch is "trunk", which is Fossil's default branch name for | |
| 290 | +the first checkin, and the default for any time a branch name is needed but not | |
| 291 | +specified.</p> | |
| 292 | + | |
| 293 | +This will get you started on identifying checkins. The | |
| 294 | +<a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including | |
| 295 | +how timestamps can also be used. | |
| 296 | 296 | |
| 297 | 297 | <h2 id="config">Configuring Your Local Repository</h2> |
| 298 | 298 | |
| 299 | - <p>When you create a new repository, either by cloning an existing | |
| 300 | - project or create a new project of your own, you usually want to do some | |
| 301 | - local configuration. This is easily accomplished using the web-server | |
| 302 | - that is built into fossil. Start the fossil web server like this: | |
| 303 | - ([/help/ui | more info])</p> | |
| 304 | - | |
| 305 | - <blockquote> | |
| 306 | - <b>fossil ui </b><i> repository-filename</i> | |
| 307 | - </blockquote> | |
| 308 | - | |
| 309 | - <p>You can omit the <i>repository-filename</i> from the command above | |
| 310 | - if you are inside a checked-out local tree.</p> | |
| 311 | - | |
| 312 | - <p>This starts a web server then automatically launches your | |
| 313 | - web browser and makes it point to this web server. If your system | |
| 314 | - has an unusual configuration, fossil might not be able to figure out | |
| 315 | - how to start your web browser. In that case, first tell fossil | |
| 316 | - where to find your web browser using a command like this:</p> | |
| 317 | - | |
| 318 | - <blockquote> | |
| 319 | - <b>fossil setting web-browser </b><i> path-to-web-browser</i> | |
| 320 | - </blockquote> | |
| 321 | - | |
| 322 | - <p>By default, fossil does not require a login for HTTP connections | |
| 323 | - coming in from the IP loopback address 127.0.0.1. You can, and perhaps | |
| 324 | - should, change this after you create a few users.</p> | |
| 325 | - | |
| 326 | - <p>When you are finished configuring, just press Control-C or use | |
| 327 | - the <b>kill</b> command to shut down the mini-server.</p> | |
| 299 | +<p>When you create a new repository, either by cloning an existing | |
| 300 | +project or create a new project of your own, you usually want to do some | |
| 301 | +local configuration. This is easily accomplished using the web-server | |
| 302 | +that is built into fossil. Start the fossil web server like this: | |
| 303 | +([/help/ui | more info])</p> | |
| 304 | + | |
| 305 | +<blockquote> | |
| 306 | +<b>fossil ui </b><i> repository-filename</i> | |
| 307 | +</blockquote> | |
| 308 | + | |
| 309 | +<p>You can omit the <i>repository-filename</i> from the command above | |
| 310 | +if you are inside a checked-out local tree.</p> | |
| 311 | + | |
| 312 | +<p>This starts a web server then automatically launches your | |
| 313 | +web browser and makes it point to this web server. If your system | |
| 314 | +has an unusual configuration, fossil might not be able to figure out | |
| 315 | +how to start your web browser. In that case, first tell fossil | |
| 316 | +where to find your web browser using a command like this:</p> | |
| 317 | + | |
| 318 | +<blockquote> | |
| 319 | +<b>fossil setting web-browser </b><i> path-to-web-browser</i> | |
| 320 | +</blockquote> | |
| 321 | + | |
| 322 | +<p>By default, fossil does not require a login for HTTP connections | |
| 323 | +coming in from the IP loopback address 127.0.0.1. You can, and perhaps | |
| 324 | +should, change this after you create a few users.</p> | |
| 325 | + | |
| 326 | +<p>When you are finished configuring, just press Control-C or use | |
| 327 | +the <b>kill</b> command to shut down the mini-server.</p> | |
| 328 | 328 | |
| 329 | 329 | <h2 id="changes">Making Changes</h2> |
| 330 | 330 | |
| 331 | - <p>To add new files to your project, or remove old files, use these | |
| 332 | - commands:</p> | |
| 333 | - | |
| 334 | - <blockquote> | |
| 335 | - <b>[/help/add | fossil add]</b> <i>file...</i><br> | |
| 336 | - <b>[/help/rm | fossil rm]</b> <i>file...</i><br> | |
| 337 | - <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> | |
| 338 | - </blockquote> | |
| 339 | - | |
| 340 | - <p>You can also edit files freely. Once you are ready to commit | |
| 341 | - your changes, type:</p> | |
| 342 | - | |
| 343 | - <blockquote> | |
| 344 | - <b>[/help/commit | fossil commit]</b> | |
| 345 | - </blockquote> | |
| 346 | - | |
| 347 | - <p>You will be prompted for check-in comments using whatever editor | |
| 348 | - is specified by your VISUAL or EDITOR environment variable.</p> | |
| 349 | - | |
| 350 | - In the default configuration, the [/help/commit|commit] | |
| 351 | - command will also automatically [/help/push|push] your changes, but that | |
| 352 | - feature can be disabled. (More information about | |
| 353 | - [./concepts.wiki#workflow|autosync] and how to disable it.) | |
| 354 | - Remember that your coworkers can not see your changes until you | |
| 355 | - commit and push them.</p> | |
| 331 | +<p>To add new files to your project, or remove old files, use these | |
| 332 | +commands:</p> | |
| 333 | + | |
| 334 | +<blockquote> | |
| 335 | +<b>[/help/add | fossil add]</b> <i>file...</i><br> | |
| 336 | +<b>[/help/rm | fossil rm]</b> <i>file...</i><br> | |
| 337 | +<b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> | |
| 338 | +</blockquote> | |
| 339 | + | |
| 340 | +<p>You can also edit files freely. Once you are ready to commit | |
| 341 | +your changes, type:</p> | |
| 342 | + | |
| 343 | +<blockquote> | |
| 344 | +<b>[/help/commit | fossil commit]</b> | |
| 345 | +</blockquote> | |
| 346 | + | |
| 347 | +<p>You will be prompted for check-in comments using whatever editor | |
| 348 | +is specified by your VISUAL or EDITOR environment variable.</p> | |
| 349 | + | |
| 350 | +In the default configuration, the [/help/commit|commit] | |
| 351 | +command will also automatically [/help/push|push] your changes, but that | |
| 352 | +feature can be disabled. (More information about | |
| 353 | +[./concepts.wiki#workflow|autosync] and how to disable it.) | |
| 354 | +Remember that your coworkers can not see your changes until you | |
| 355 | +commit and push them.</p> | |
| 356 | 356 | |
| 357 | 357 | <h2 id="sharing">Sharing Changes</h2> |
| 358 | 358 | |
| 359 | - <p>When [./concepts.wiki#workflow|autosync] is turned off, | |
| 360 | - the changes you [/help/commit | commit] are only | |
| 361 | - on your local repository. | |
| 362 | - To share those changes with other repositories, do:</p> | |
| 363 | - | |
| 364 | - <blockquote> | |
| 365 | - <b>[/help/push | fossil push]</b> <i>URL</i> | |
| 366 | - </blockquote> | |
| 367 | - | |
| 368 | - <p>Where <i>URL</i> is the http: URL of the server repository you | |
| 369 | - want to share your changes with. If you omit the <i>URL</i> argument, | |
| 370 | - fossil will use whatever server you most recently synced with.</p> | |
| 371 | - | |
| 372 | - <p>The [/help/push | push] command only sends your changes to others. To | |
| 373 | - Receive changes from others, use [/help/pull | pull]. Or go both ways at | |
| 374 | - once using [/help/sync | sync]:</p> | |
| 375 | - | |
| 376 | - <blockquote> | |
| 377 | - <b>[/help/pull | fossil pull]</b> <i>URL</i><br> | |
| 378 | - <b>[/help/sync | fossil sync]</b> <i>URL</i> | |
| 379 | - </blockquote> | |
| 380 | - | |
| 381 | - <p>When you pull in changes from others, they go into your repository, | |
| 382 | - not into your checked-out local tree. To get the changes into your | |
| 383 | - local tree, use [/help/update | update]:</p> | |
| 384 | - | |
| 385 | - <blockquote> | |
| 386 | - <b>[/help/update | fossil update]</b> <i>VERSION</i> | |
| 387 | - </blockquote> | |
| 388 | - | |
| 389 | - <p>The <i>VERSION</i> can be the name of a branch or tag or any | |
| 390 | - abbreviation to the 40-character | |
| 391 | - artifact identifier for a particular check-in, or it can be a | |
| 392 | - date/time stamp. ([./checkin_names.wiki | more info]) | |
| 393 | - If you omit | |
| 394 | - the <i>VERSION</i>, then fossil moves you to the | |
| 395 | - latest version of the branch your are currently on.</p> | |
| 396 | - | |
| 397 | - <p>The default behavior is for [./concepts.wiki#workflow|autosync] to | |
| 398 | - be turned on. That means that a [/help/pull|pull] automatically occurs | |
| 399 | - when you run [/help/update|update] and a [/help/push|push] happens | |
| 400 | - automatically after you [/help/commit|commit]. So in normal practice, | |
| 401 | - the push, pull, and sync commands are rarely used. But it is important | |
| 402 | - to know about them, all the same.</p> | |
| 403 | - | |
| 404 | - <blockquote> | |
| 405 | - <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> | |
| 406 | - </blockquote> | |
| 407 | - | |
| 408 | - <p>Is similar to update except that it does not honor the autosync | |
| 409 | - setting, nor does it merge in local changes - it prefers to overwrite | |
| 410 | - them and fails if local changes exist unless the <tt>--force</tt> | |
| 411 | - flag is used.</p> | |
| 359 | +<p>When [./concepts.wiki#workflow|autosync] is turned off, | |
| 360 | +the changes you [/help/commit | commit] are only | |
| 361 | +on your local repository. | |
| 362 | +To share those changes with other repositories, do:</p> | |
| 363 | + | |
| 364 | +<blockquote> | |
| 365 | +<b>[/help/push | fossil push]</b> <i>URL</i> | |
| 366 | +</blockquote> | |
| 367 | + | |
| 368 | +<p>Where <i>URL</i> is the http: URL of the server repository you | |
| 369 | +want to share your changes with. If you omit the <i>URL</i> argument, | |
| 370 | +fossil will use whatever server you most recently synced with.</p> | |
| 371 | + | |
| 372 | +<p>The [/help/push | push] command only sends your changes to others. To | |
| 373 | +Receive changes from others, use [/help/pull | pull]. Or go both ways at | |
| 374 | +once using [/help/sync | sync]:</p> | |
| 375 | + | |
| 376 | +<blockquote> | |
| 377 | +<b>[/help/pull | fossil pull]</b> <i>URL</i><br> | |
| 378 | +<b>[/help/sync | fossil sync]</b> <i>URL</i> | |
| 379 | +</blockquote> | |
| 380 | + | |
| 381 | +<p>When you pull in changes from others, they go into your repository, | |
| 382 | +not into your checked-out local tree. To get the changes into your | |
| 383 | +local tree, use [/help/update | update]:</p> | |
| 384 | + | |
| 385 | +<blockquote> | |
| 386 | +<b>[/help/update | fossil update]</b> <i>VERSION</i> | |
| 387 | +</blockquote> | |
| 388 | + | |
| 389 | +<p>The <i>VERSION</i> can be the name of a branch or tag or any | |
| 390 | +abbreviation to the 40-character | |
| 391 | +artifact identifier for a particular check-in, or it can be a | |
| 392 | +date/time stamp. ([./checkin_names.wiki | more info]) | |
| 393 | +If you omit | |
| 394 | +the <i>VERSION</i>, then fossil moves you to the | |
| 395 | +latest version of the branch your are currently on.</p> | |
| 396 | + | |
| 397 | +<p>The default behavior is for [./concepts.wiki#workflow|autosync] to | |
| 398 | +be turned on. That means that a [/help/pull|pull] automatically occurs | |
| 399 | +when you run [/help/update|update] and a [/help/push|push] happens | |
| 400 | +automatically after you [/help/commit|commit]. So in normal practice, | |
| 401 | +the push, pull, and sync commands are rarely used. But it is important | |
| 402 | +to know about them, all the same.</p> | |
| 403 | + | |
| 404 | +<blockquote> | |
| 405 | +<b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> | |
| 406 | +</blockquote> | |
| 407 | + | |
| 408 | +<p>Is similar to update except that it does not honor the autosync | |
| 409 | +setting, nor does it merge in local changes - it prefers to overwrite | |
| 410 | +them and fails if local changes exist unless the <tt>--force</tt> | |
| 411 | +flag is used.</p> | |
| 412 | 412 | |
| 413 | 413 | <h2 id="branch" name="merge">Branching And Merging</h2> |
| 414 | 414 | |
| 415 | - <p>Use the --branch option to the [/help/commit | commit] command | |
| 416 | - to start a new branch. Note that in Fossil, branches are normally | |
| 417 | - created when you commit, not before you start editing. You can | |
| 418 | - use the [/help/branch | branch new] command to create a new branch | |
| 419 | - before you start editing, if you want, but most people just wait | |
| 420 | - until they are ready to commit. | |
| 421 | - | |
| 422 | - To merge two branches back together, first | |
| 423 | - [/help/update | update] to the branch you want to merge into. | |
| 424 | - Then do a [/help/merge|merge] of the other branch that you want to incorporate | |
| 425 | - the changes from. For example, to merge "featureX" changes into "trunk" | |
| 426 | - do this:</p> | |
| 427 | - | |
| 428 | - <blockquote> | |
| 429 | - <b>fossil [/help/update|update] trunk</b><br> | |
| 430 | - <b>fossil [/help/merge|merge] featureX</b><br> | |
| 431 | - <i># make sure the merge didn't break anything...</i><br> | |
| 432 | - <b>fossil [/help/commit|commit] | |
| 433 | - </blockquote> | |
| 434 | - | |
| 435 | - <p>The argument to the [/help/merge|merge] command can be any of the | |
| 436 | - version identifier forms that work for [/help/update|update]. | |
| 437 | - ([./checkin_names.wiki|more info].) | |
| 438 | - The merge command has options to cherry-pick individual | |
| 439 | - changes, or to back out individual changes, if you don't want to | |
| 440 | - do a full merge.</p> | |
| 441 | - | |
| 442 | - The merge command puts all changes in your working check-out. | |
| 443 | - No changes are made to the repository. | |
| 444 | - You must run [/help/commit|commit] separately | |
| 445 | - to add the merge changes into your repository to make them persistent | |
| 446 | - and so that your coworkers can see them. | |
| 447 | - But before you do that, you will normally want to run a few tests | |
| 448 | - to verify that the merge didn't cause logic breaks in your code. | |
| 449 | - | |
| 450 | - The same branch can be merged multiple times without trouble. Fossil | |
| 451 | - automatically keeps up with things and avoids conflicts when doing | |
| 452 | - multiple merges. So even if you have merged the featureX branch | |
| 453 | - into trunk previously, you can do so again and Fossil will automatically | |
| 454 | - know to pull in only those changes that have occurred since the previous | |
| 455 | - merge. | |
| 456 | - | |
| 457 | - <p>If a merge or update doesn't work out (perhaps something breaks or | |
| 458 | - there are many merge conflicts) then you back up using:</p> | |
| 459 | - | |
| 460 | - <blockquote> | |
| 461 | - <b>[/help/undo | fossil undo]</b> | |
| 462 | - </blockquote> | |
| 463 | - | |
| 464 | - <p>This will back out the changes that the merge or update made to the | |
| 465 | - working checkout. There is also a [/help/redo|redo] command if you undo by | |
| 466 | - mistake. Undo and redo only work for changes that have | |
| 467 | - not yet been checked in using commit and there is only a single | |
| 468 | - level of undo/redo.</p> | |
| 415 | +<p>Use the --branch option to the [/help/commit | commit] command | |
| 416 | +to start a new branch. Note that in Fossil, branches are normally | |
| 417 | +created when you commit, not before you start editing. You can | |
| 418 | +use the [/help/branch | branch new] command to create a new branch | |
| 419 | +before you start editing, if you want, but most people just wait | |
| 420 | +until they are ready to commit. | |
| 421 | + | |
| 422 | +To merge two branches back together, first | |
| 423 | +[/help/update | update] to the branch you want to merge into. | |
| 424 | +Then do a [/help/merge|merge] of the other branch that you want to incorporate | |
| 425 | +the changes from. For example, to merge "featureX" changes into "trunk" | |
| 426 | +do this:</p> | |
| 427 | + | |
| 428 | +<blockquote> | |
| 429 | +<b>fossil [/help/update|update] trunk</b><br> | |
| 430 | +<b>fossil [/help/merge|merge] featureX</b><br> | |
| 431 | +<i># make sure the merge didn't break anything...</i><br> | |
| 432 | +<b>fossil [/help/commit|commit] | |
| 433 | +</blockquote> | |
| 434 | + | |
| 435 | +<p>The argument to the [/help/merge|merge] command can be any of the | |
| 436 | +version identifier forms that work for [/help/update|update]. | |
| 437 | +([./checkin_names.wiki|more info].) | |
| 438 | +The merge command has options to cherry-pick individual | |
| 439 | +changes, or to back out individual changes, if you don't want to | |
| 440 | +do a full merge.</p> | |
| 441 | + | |
| 442 | +The merge command puts all changes in your working check-out. | |
| 443 | +No changes are made to the repository. | |
| 444 | +You must run [/help/commit|commit] separately | |
| 445 | +to add the merge changes into your repository to make them persistent | |
| 446 | +and so that your coworkers can see them. | |
| 447 | +But before you do that, you will normally want to run a few tests | |
| 448 | +to verify that the merge didn't cause logic breaks in your code. | |
| 449 | + | |
| 450 | +The same branch can be merged multiple times without trouble. Fossil | |
| 451 | +automatically keeps up with things and avoids conflicts when doing | |
| 452 | +multiple merges. So even if you have merged the featureX branch | |
| 453 | +into trunk previously, you can do so again and Fossil will automatically | |
| 454 | +know to pull in only those changes that have occurred since the previous | |
| 455 | +merge. | |
| 456 | + | |
| 457 | +<p>If a merge or update doesn't work out (perhaps something breaks or | |
| 458 | +there are many merge conflicts) then you back up using:</p> | |
| 459 | + | |
| 460 | +<blockquote> | |
| 461 | +<b>[/help/undo | fossil undo]</b> | |
| 462 | +</blockquote> | |
| 463 | + | |
| 464 | +<p>This will back out the changes that the merge or update made to the | |
| 465 | +working checkout. There is also a [/help/redo|redo] command if you undo by | |
| 466 | +mistake. Undo and redo only work for changes that have | |
| 467 | +not yet been checked in using commit and there is only a single | |
| 468 | +level of undo/redo.</p> | |
| 469 | 469 | |
| 470 | 470 | |
| 471 | 471 | <h2 id="server">Setting Up A Server</h2> |
| 472 | 472 | |
| 473 | - <p>Fossil can act as a stand-alone web server using one of these | |
| 474 | - commands:</p> | |
| 475 | - | |
| 476 | - <blockquote> | |
| 477 | - <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> | |
| 478 | - <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> | |
| 479 | - </blockquote> | |
| 480 | - | |
| 481 | - <p>The <i>repository-filename</i> can be omitted when these commands | |
| 482 | - are run from within an open check-out, which a particularly useful | |
| 483 | - shortcut for the <b>fossil ui</b> command. | |
| 484 | - | |
| 485 | - <p>The <b>ui</b> command is intended for accessing the web interface | |
| 486 | - from a local desktop. The <b>ui</b> command binds to the loopback IP | |
| 487 | - address only (and thus makes the web interface visible only on the | |
| 488 | - local machine) and it automatically start your web browser pointing at the | |
| 489 | - server. For cross-machine collaboration, use the <b>server</b> command, | |
| 490 | - which binds on all IP addresses and does not try to start a web browser.</p> | |
| 491 | - | |
| 492 | - <p>Servers are also easily configured as: | |
| 493 | - <ul> | |
| 494 | - <li>[./server/any/inetd.md|inetd] | |
| 495 | - <li>[./server/debian/service.md|systemd] | |
| 496 | - <li>[./server/any/cgi.md|CGI] | |
| 497 | - <li>[./server/any/scgi.md|SCGI] | |
| 498 | - </ul> | |
| 499 | - | |
| 500 | - <p>The [./selfhost.wiki | self-hosting fossil repositories] use | |
| 501 | - CGI. | |
| 473 | +<p>Fossil can act as a stand-alone web server using one of these | |
| 474 | +commands:</p> | |
| 475 | + | |
| 476 | +<blockquote> | |
| 477 | +<b>[/help/server | fossil server]</b> <i>repository-filename</i><br> | |
| 478 | +<b>[/help/ui | fossil ui]</b> <i>repository-filename</i> | |
| 479 | +</blockquote> | |
| 480 | + | |
| 481 | +<p>The <i>repository-filename</i> can be omitted when these commands | |
| 482 | +are run from within an open check-out, which a particularly useful | |
| 483 | +shortcut for the <b>fossil ui</b> command. | |
| 484 | + | |
| 485 | +<p>The <b>ui</b> command is intended for accessing the web interface | |
| 486 | +from a local desktop. The <b>ui</b> command binds to the loopback IP | |
| 487 | +address only (and thus makes the web interface visible only on the | |
| 488 | +local machine) and it automatically start your web browser pointing at the | |
| 489 | +server. For cross-machine collaboration, use the <b>server</b> command, | |
| 490 | +which binds on all IP addresses and does not try to start a web browser.</p> | |
| 491 | + | |
| 492 | +<p>Servers are also easily configured as: | |
| 493 | +<ul> | |
| 494 | +<li>[./server/any/inetd.md|inetd] | |
| 495 | +<li>[./server/debian/service.md|systemd] | |
| 496 | +<li>[./server/any/cgi.md|CGI] | |
| 497 | +<li>[./server/any/scgi.md|SCGI] | |
| 498 | +</ul> | |
| 499 | + | |
| 500 | +<p>The [./selfhost.wiki | self-hosting fossil repositories] use | |
| 501 | +CGI. | |
| 502 | 502 | |
| 503 | 503 | <h2 id="proxy">HTTP Proxies</h2> |
| 504 | 504 | |
| 505 | - <p>If you are behind a restrictive firewall that requires you to use | |
| 506 | - an HTTP proxy to reach the internet, then you can configure the proxy | |
| 507 | - in three different ways. You can tell fossil about your proxy using | |
| 508 | - a command-line option on commands that use the network, | |
| 509 | - <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> | |
| 510 | - | |
| 511 | - <blockquote> | |
| 512 | - <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> | |
| 513 | - </blockquote> | |
| 514 | - | |
| 515 | - <p>It is annoying to have to type in the proxy URL every time you | |
| 516 | - sync your project, though, so you can make the proxy configuration | |
| 517 | - persistent using the [/help/setting | setting] command:</p> | |
| 518 | - | |
| 519 | - <blockquote> | |
| 520 | - <b>fossil setting proxy </b><i>Proxy-URL</i> | |
| 521 | - </blockquote> | |
| 522 | - | |
| 523 | - <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> | |
| 524 | - | |
| 525 | - <blockquote> | |
| 526 | - <b>export http_proxy=</b><i>Proxy-URL</i> | |
| 527 | - </blockquote> | |
| 528 | - | |
| 529 | - <p>To stop using the proxy, do:</p> | |
| 530 | - | |
| 531 | - <blockquote> | |
| 532 | - <b>fossil setting proxy off</b> | |
| 533 | - </blockquote> | |
| 534 | - | |
| 535 | - <p>Or unset the environment variable. The fossil setting for the | |
| 536 | - HTTP proxy takes precedence over the environment variable and the | |
| 537 | - command-line option overrides both. If you have an persistent | |
| 538 | - proxy setting that you want to override for a one-time sync, that | |
| 539 | - is easily done on the command-line. For example, to sync with | |
| 540 | - a co-workers repository on your LAN, you might type:</p> | |
| 541 | - | |
| 542 | - <blockquote> | |
| 543 | - <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> | |
| 544 | - </blockquote> | |
| 505 | +<p>If you are behind a restrictive firewall that requires you to use | |
| 506 | +an HTTP proxy to reach the internet, then you can configure the proxy | |
| 507 | +in three different ways. You can tell fossil about your proxy using | |
| 508 | +a command-line option on commands that use the network, | |
| 509 | +<b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> | |
| 510 | + | |
| 511 | +<blockquote> | |
| 512 | +<b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> | |
| 513 | +</blockquote> | |
| 514 | + | |
| 515 | +<p>It is annoying to have to type in the proxy URL every time you | |
| 516 | +sync your project, though, so you can make the proxy configuration | |
| 517 | +persistent using the [/help/setting | setting] command:</p> | |
| 518 | + | |
| 519 | +<blockquote> | |
| 520 | +<b>fossil setting proxy </b><i>Proxy-URL</i> | |
| 521 | +</blockquote> | |
| 522 | + | |
| 523 | +<p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> | |
| 524 | + | |
| 525 | +<blockquote> | |
| 526 | +<b>export http_proxy=</b><i>Proxy-URL</i> | |
| 527 | +</blockquote> | |
| 528 | + | |
| 529 | +<p>To stop using the proxy, do:</p> | |
| 530 | + | |
| 531 | +<blockquote> | |
| 532 | +<b>fossil setting proxy off</b> | |
| 533 | +</blockquote> | |
| 534 | + | |
| 535 | +<p>Or unset the environment variable. The fossil setting for the | |
| 536 | +HTTP proxy takes precedence over the environment variable and the | |
| 537 | +command-line option overrides both. If you have an persistent | |
| 538 | +proxy setting that you want to override for a one-time sync, that | |
| 539 | +is easily done on the command-line. For example, to sync with | |
| 540 | +a co-workers repository on your LAN, you might type:</p> | |
| 541 | + | |
| 542 | +<blockquote> | |
| 543 | +<b>fossil sync http://192.168.1.36:8080/ --proxy off</b> | |
| 544 | +</blockquote> | |
| 545 | 545 | |
| 546 | 546 | <h2 id="links">Other Resources</h2> |
| 547 | 547 | |
| 548 | - <ul> | |
| 549 | - <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> | |
| 550 | - <li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a> | |
| 551 | - <li> <a href="./history.md">The History and Purpose of Fossil</a> | |
| 552 | - <li> <a href="./branching.wiki">Branching, Forking, and Tagging</a> | |
| 553 | - <li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a> | |
| 554 | - <li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a> | |
| 555 | - </ul> | |
| 548 | +<ul> | |
| 549 | +<li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> | |
| 550 | +<li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a> | |
| 551 | +<li> <a href="./history.md">The History and Purpose of Fossil</a> | |
| 552 | +<li> <a href="./branching.wiki">Branching, Forking, and Tagging</a> | |
| 553 | +<li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a> | |
| 554 | +<li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a> | |
| 555 | +</ul> | |
| 556 | 556 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -4,552 +4,552 @@ | |
| 4 | <p>This is a guide to help you get started using the Fossil [https://en.wikipedia.org/wiki/Distributed_version_control|Distributed Version Control System] quickly |
| 5 | and painlessly.</p> |
| 6 | |
| 7 | <h2 id="install">Installing</h2> |
| 8 | |
| 9 | <p>Fossil is a single self-contained C program. You need to |
| 10 | either download a |
| 11 | [https://www.fossil-scm.org/fossil/uv/download.html|precompiled |
| 12 | binary] |
| 13 | or <a href="build.wiki">compile it yourself</a> from sources. |
| 14 | Install Fossil by putting the fossil binary |
| 15 | someplace on your $PATH.</p> |
| 16 | You can test that Fossil is present and working like this: |
| 17 | |
| 18 | <blockquote> |
| 19 | <b> |
| 20 | fossil version<br> |
| 21 | <tt>This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC</tt><br> |
| 22 | </b> |
| 23 | </blockquote> |
| 24 | |
| 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | |
| 27 | <p>Fossil works with repository files (a database in a single file with the project's |
| 28 | complete history) and with checked-out local trees (the working directory |
| 29 | you use to do your work). |
| 30 | (See [./whyusefossil.wiki#definitions | definitions] for more background.) |
| 31 | The workflow looks like this:</p> |
| 32 | |
| 33 | <ul> |
| 34 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | [/help/clone | fossil clone]) |
| 36 | <li>Check out a local tree. ([/help/open | fossil open]) |
| 37 | <li>Perform operations on the repository (including repository |
| 38 | configuration). |
| 39 | </ul> |
| 40 | |
| 41 | Fossil can be entirely driven from the command line. Many features |
| 42 | can also be conveniently accessed from the build-in web interface. |
| 43 | |
| 44 | <p>The following sections give a brief overview of these |
| 45 | operations.</p> |
| 46 | |
| 47 | <h2 id="new">Starting A New Project</h2> |
| 48 | |
| 49 | <p>To start a new project with fossil create a new empty repository |
| 50 | this way: ([/help/init | more info]) </p> |
| 51 | |
| 52 | <blockquote> |
| 53 | <b>fossil init </b><i> repository-filename</i> |
| 54 | </blockquote> |
| 55 | |
| 56 | You can name the database anything you like, and you can place it anywhere in the filesystem. |
| 57 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 58 | <tt>[./help?cmd=/server | fossil server DIRECTORY]</tt> feature.” |
| 59 | |
| 60 | <h2 id="clone">Cloning An Existing Repository</h2> |
| 61 | |
| 62 | <p>Most fossil operations interact with a repository that is on the |
| 63 | local disk drive, not on a remote system. Hence, before accessing |
| 64 | a remote repository it is necessary to make a local copy of that |
| 65 | repository. Making a local copy of a remote repository is called |
| 66 | "cloning".</p> |
| 67 | |
| 68 | <p>Clone a remote repository as follows: ([/help/clone | more info])</p> |
| 69 | |
| 70 | <blockquote> |
| 71 | <b>fossil clone</b> <i>URL repository-filename</i> |
| 72 | </blockquote> |
| 73 | |
| 74 | <p>The <i>URL</i> specifies the fossil repository |
| 75 | you want to clone. The <i>repository-filename</i> is the new local |
| 76 | filename into which the cloned repository will be written. For |
| 77 | example, to clone the source code of Fossil itself: |
| 78 | |
| 79 | <blockquote> |
| 80 | <b>fossil clone https://www.fossil-scm.org/ myclone.fossil</b> |
| 81 | </blockquote> |
| 82 | |
| 83 | If your logged-in username is 'exampleuser', you should see output something like this: |
| 84 | |
| 85 | <blockquote> |
| 86 | <b><tt> |
| 87 | Round-trips: 8 Artifacts sent: 0 received: 39421<br> |
| 88 | Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0<br> |
| 89 | Rebuilding repository meta-data...<br> |
| 90 | 100% complete...<br> |
| 91 | Extra delta compression... <br> |
| 92 | Vacuuming the database... <br> |
| 93 | project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333<br> |
| 94 | server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> |
| 95 | admin-user: exampleuser (password is "yoWgDR42iv")><br> |
| 96 | </tt></b> |
| 97 | </blockquote> |
| 98 | |
| 99 | <p>If the remote repository requires a login, include a |
| 100 | userid in the URL like this: |
| 101 | |
| 102 | <blockquote> |
| 103 | <b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> |
| 104 | </blockquote> |
| 105 | |
| 106 | <p>You will be prompted separately for the password. |
| 107 | Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. |
| 108 | For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") </p> |
| 109 | |
| 110 | <p>If you are behind a restrictive firewall, you might need |
| 111 | to <a href="#proxy">specify an HTTP proxy</a>.</p> |
| 112 | |
| 113 | <p>A Fossil repository is a single disk file. Instead of cloning, |
| 114 | you can just make a copy of the repository file (for example, using |
| 115 | "scp"). Note, however, that the repository file contains auxiliary |
| 116 | information above and beyond the versioned files, including some |
| 117 | sensitive information such as password hashes and email addresses. If you |
| 118 | want to share Fossil repositories directly by copying, consider running the |
| 119 | [/help/scrub|fossil scrub] command to remove sensitive information |
| 120 | before transmitting the file. |
| 121 | |
| 122 | <h2 id="import">Importing From Another Version Control System</h2> |
| 123 | |
| 124 | <p>Rather than start a new project, or clone an existing Fossil project, |
| 125 | you might prefer to |
| 126 | <a href="./inout.wiki">import an existing Git project</a> |
| 127 | into Fossil using the [/help/import | fossil import] command. |
| 128 | |
| 129 | You can even decide to export your project back into git using the |
| 130 | [/help/git | fossil git] command, which is how the Fossil project maintains |
| 131 | [https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There |
| 132 | is no limit to the number of times a tree can be imported and exported between |
| 133 | Fossil and git. |
| 134 | |
| 135 | The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become |
| 136 | a popular way to move files between version management systems, including from |
| 137 | [https://www.mercurial-scm.org/|Mercurial]. |
| 138 | Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. |
| 139 | |
| 140 | <h2 id="checkout">Checking Out A Local Tree</h2> |
| 141 | |
| 142 | <p>To work on a project in fossil, you need to check out a local |
| 143 | copy of the source tree. Create the directory you want to be |
| 144 | the root of your tree and cd into that directory. Then |
| 145 | do this: ([/help/open | more info])</p> |
| 146 | |
| 147 | <blockquote> |
| 148 | <b>fossil open </b><i> repository-filename</i> |
| 149 | </blockquote> |
| 150 | |
| 151 | for example: |
| 152 | |
| 153 | <blockquote> |
| 154 | <b><tt> |
| 155 | fossil open ../myclone.fossil<br> |
| 156 | BUILD.txt<br> |
| 157 | COPYRIGHT-BSD2.txt<br> |
| 158 | README.md<br> |
| 159 | ︙<br> |
| 160 | </tt></b> |
| 161 | </blockquote> |
| 162 | |
| 163 | (or "fossil open ..\myclone.fossil" on Windows). |
| 164 | |
| 165 | <p>This leaves you with the newest version of the tree |
| 166 | checked out. |
| 167 | From anywhere underneath the root of your local tree, you |
| 168 | can type commands like the following to find out the status of |
| 169 | your local tree:</p> |
| 170 | |
| 171 | <blockquote> |
| 172 | <b>[/help/info | fossil info]</b><br> |
| 173 | <b>[/help/status | fossil status]</b><br> |
| 174 | <b>[/help/changes | fossil changes]</b><br> |
| 175 | <b>[/help/diff | fossil diff]</b><br> |
| 176 | <b>[/help/timeline | fossil timeline]</b><br> |
| 177 | <b>[/help/ls | fossil ls]</b><br> |
| 178 | <b>[/help/branch | fossil branch]</b><br> |
| 179 | </blockquote> |
| 180 | |
| 181 | <p>If you created a new respository using "fossil init" some commands will not |
| 182 | produce much output.</p> |
| 183 | |
| 184 | <p>Note that Fossil allows you to make multiple check-outs in |
| 185 | separate directories from the same repository. This enables you, |
| 186 | for example, to do builds from multiple branches or versions at |
| 187 | the same time without having to generate extra clones.</p> |
| 188 | |
| 189 | <p>To switch a checkout between different versions and branches, |
| 190 | use:</p> |
| 191 | |
| 192 | <blockquote> |
| 193 | <b>[/help/update | fossil update]</b><br> |
| 194 | <b>[/help/checkout | fossil checkout]</b><br> |
| 195 | </blockquote> |
| 196 | |
| 197 | <p>[/help/update | update] honors the "autosync" option and |
| 198 | does a "soft" switch, merging any local changes into the target |
| 199 | version, whereas [/help/checkout | checkout] does not |
| 200 | automatically sync and does a "hard" switch, overwriting local |
| 201 | changes if told to do so.</p> |
| 202 | |
| 203 | <h2 id="changes">Making and Commiting Changes</h2> |
| 204 | |
| 205 | <p>To add new files to your project or remove existing ones, use these |
| 206 | commands:</p> |
| 207 | |
| 208 | <blockquote> |
| 209 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 210 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 211 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 212 | </blockquote> |
| 213 | |
| 214 | <p>The command:</p> |
| 215 | <blockquote> |
| 216 | <b> |
| 217 | [/help/changes | fossil changes]</b> |
| 218 | </blockquote> |
| 219 | <p>lists files that have changed since the last commit to the repository. For |
| 220 | example, if you edit the file "README.md":</p> |
| 221 | |
| 222 | <blockquote> |
| 223 | <b> |
| 224 | fossil changes<br> |
| 225 | EDITED README.md |
| 226 | </b> |
| 227 | </blockquote> |
| 228 | |
| 229 | <p>To see exactly what change was made you can use the command</p> |
| 230 | [/help/diff | fossil diff]: |
| 231 | <blockquote> |
| 232 | <b> |
| 233 | fossil diff <br><tt> |
| 234 | Index: README.md<br> |
| 235 | ============================================================<br> |
| 236 | --- README.md<br> |
| 237 | +++ README.md<br> |
| 238 | @@ -1,5 +1,6 @@<br> |
| 239 | +Made some changes to the project<br> |
| 240 | # Original text<br> |
| 241 | </tt></b> |
| 242 | </blockquote> |
| 243 | |
| 244 | <p>"fossil diff" is the difference between your tree on disk now and as the tree was |
| 245 | when you did "fossil open". An open is the first checkout from a repository |
| 246 | into a new directory. </p> |
| 247 | |
| 248 | <p>To commit your changes to a local-only repository:</p> |
| 249 | <blockquote> |
| 250 | <b> |
| 251 | fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> |
| 252 | # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> |
| 253 | #<br> |
| 254 | # user: exampleuser<br> |
| 255 | # tags: trunk<br> |
| 256 | #<br> |
| 257 | # EDITED README.md<br> |
| 258 | Edited file to add description of code changes<br> |
| 259 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> |
| 260 | </tt></b> |
| 261 | </blockquote> |
| 262 | |
| 263 | <p>You will be prompted for check-in comments using whatever editor |
| 264 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 265 | specified Fossil uses line-editing in the terminal.</p> |
| 266 | |
| 267 | <p>To commit your changes to a repository that was cloned from remote you |
| 268 | perform the same actions but the results are different. Fossil |
| 269 | defaults to 'autosync' mode, a single-stage commit that sends all changes |
| 270 | committed to the local repository immediately on to the remote parent repository. This |
| 271 | only works if you have write permission to the remote respository.</p> |
| 272 | |
| 273 | <h2 id="naming">Naming of Files, Checkins, and Branches</h2> |
| 274 | |
| 275 | <p>Fossil deals with information artifacts. This Quickstart document only deals |
| 276 | with files and collections of files, but be aware there are also tickets, wiki pages and more. |
| 277 | Every artifact in Fossil has a universally-unique hash id, and may also have a |
| 278 | human-readable name.</p> |
| 279 | |
| 280 | <p>The following are all equivalent ways of identifying a Fossil file, |
| 281 | checkin or branch artifact:</p> |
| 282 | |
| 283 | <ul> |
| 284 | <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a |
| 285 | <li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters |
| 286 | <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash |
| 287 | </ul> |
| 288 | |
| 289 | <p>A special convenience branch is "trunk", which is Fossil's default branch name for |
| 290 | the first checkin, and the default for any time a branch name is needed but not |
| 291 | specified.</p> |
| 292 | |
| 293 | This will get you started on identifying checkins. The |
| 294 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 295 | how timestamps can also be used. |
| 296 | |
| 297 | <h2 id="config">Configuring Your Local Repository</h2> |
| 298 | |
| 299 | <p>When you create a new repository, either by cloning an existing |
| 300 | project or create a new project of your own, you usually want to do some |
| 301 | local configuration. This is easily accomplished using the web-server |
| 302 | that is built into fossil. Start the fossil web server like this: |
| 303 | ([/help/ui | more info])</p> |
| 304 | |
| 305 | <blockquote> |
| 306 | <b>fossil ui </b><i> repository-filename</i> |
| 307 | </blockquote> |
| 308 | |
| 309 | <p>You can omit the <i>repository-filename</i> from the command above |
| 310 | if you are inside a checked-out local tree.</p> |
| 311 | |
| 312 | <p>This starts a web server then automatically launches your |
| 313 | web browser and makes it point to this web server. If your system |
| 314 | has an unusual configuration, fossil might not be able to figure out |
| 315 | how to start your web browser. In that case, first tell fossil |
| 316 | where to find your web browser using a command like this:</p> |
| 317 | |
| 318 | <blockquote> |
| 319 | <b>fossil setting web-browser </b><i> path-to-web-browser</i> |
| 320 | </blockquote> |
| 321 | |
| 322 | <p>By default, fossil does not require a login for HTTP connections |
| 323 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 324 | should, change this after you create a few users.</p> |
| 325 | |
| 326 | <p>When you are finished configuring, just press Control-C or use |
| 327 | the <b>kill</b> command to shut down the mini-server.</p> |
| 328 | |
| 329 | <h2 id="changes">Making Changes</h2> |
| 330 | |
| 331 | <p>To add new files to your project, or remove old files, use these |
| 332 | commands:</p> |
| 333 | |
| 334 | <blockquote> |
| 335 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 336 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 337 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 338 | </blockquote> |
| 339 | |
| 340 | <p>You can also edit files freely. Once you are ready to commit |
| 341 | your changes, type:</p> |
| 342 | |
| 343 | <blockquote> |
| 344 | <b>[/help/commit | fossil commit]</b> |
| 345 | </blockquote> |
| 346 | |
| 347 | <p>You will be prompted for check-in comments using whatever editor |
| 348 | is specified by your VISUAL or EDITOR environment variable.</p> |
| 349 | |
| 350 | In the default configuration, the [/help/commit|commit] |
| 351 | command will also automatically [/help/push|push] your changes, but that |
| 352 | feature can be disabled. (More information about |
| 353 | [./concepts.wiki#workflow|autosync] and how to disable it.) |
| 354 | Remember that your coworkers can not see your changes until you |
| 355 | commit and push them.</p> |
| 356 | |
| 357 | <h2 id="sharing">Sharing Changes</h2> |
| 358 | |
| 359 | <p>When [./concepts.wiki#workflow|autosync] is turned off, |
| 360 | the changes you [/help/commit | commit] are only |
| 361 | on your local repository. |
| 362 | To share those changes with other repositories, do:</p> |
| 363 | |
| 364 | <blockquote> |
| 365 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 366 | </blockquote> |
| 367 | |
| 368 | <p>Where <i>URL</i> is the http: URL of the server repository you |
| 369 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 370 | fossil will use whatever server you most recently synced with.</p> |
| 371 | |
| 372 | <p>The [/help/push | push] command only sends your changes to others. To |
| 373 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 374 | once using [/help/sync | sync]:</p> |
| 375 | |
| 376 | <blockquote> |
| 377 | <b>[/help/pull | fossil pull]</b> <i>URL</i><br> |
| 378 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 379 | </blockquote> |
| 380 | |
| 381 | <p>When you pull in changes from others, they go into your repository, |
| 382 | not into your checked-out local tree. To get the changes into your |
| 383 | local tree, use [/help/update | update]:</p> |
| 384 | |
| 385 | <blockquote> |
| 386 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 387 | </blockquote> |
| 388 | |
| 389 | <p>The <i>VERSION</i> can be the name of a branch or tag or any |
| 390 | abbreviation to the 40-character |
| 391 | artifact identifier for a particular check-in, or it can be a |
| 392 | date/time stamp. ([./checkin_names.wiki | more info]) |
| 393 | If you omit |
| 394 | the <i>VERSION</i>, then fossil moves you to the |
| 395 | latest version of the branch your are currently on.</p> |
| 396 | |
| 397 | <p>The default behavior is for [./concepts.wiki#workflow|autosync] to |
| 398 | be turned on. That means that a [/help/pull|pull] automatically occurs |
| 399 | when you run [/help/update|update] and a [/help/push|push] happens |
| 400 | automatically after you [/help/commit|commit]. So in normal practice, |
| 401 | the push, pull, and sync commands are rarely used. But it is important |
| 402 | to know about them, all the same.</p> |
| 403 | |
| 404 | <blockquote> |
| 405 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 406 | </blockquote> |
| 407 | |
| 408 | <p>Is similar to update except that it does not honor the autosync |
| 409 | setting, nor does it merge in local changes - it prefers to overwrite |
| 410 | them and fails if local changes exist unless the <tt>--force</tt> |
| 411 | flag is used.</p> |
| 412 | |
| 413 | <h2 id="branch" name="merge">Branching And Merging</h2> |
| 414 | |
| 415 | <p>Use the --branch option to the [/help/commit | commit] command |
| 416 | to start a new branch. Note that in Fossil, branches are normally |
| 417 | created when you commit, not before you start editing. You can |
| 418 | use the [/help/branch | branch new] command to create a new branch |
| 419 | before you start editing, if you want, but most people just wait |
| 420 | until they are ready to commit. |
| 421 | |
| 422 | To merge two branches back together, first |
| 423 | [/help/update | update] to the branch you want to merge into. |
| 424 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 425 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 426 | do this:</p> |
| 427 | |
| 428 | <blockquote> |
| 429 | <b>fossil [/help/update|update] trunk</b><br> |
| 430 | <b>fossil [/help/merge|merge] featureX</b><br> |
| 431 | <i># make sure the merge didn't break anything...</i><br> |
| 432 | <b>fossil [/help/commit|commit] |
| 433 | </blockquote> |
| 434 | |
| 435 | <p>The argument to the [/help/merge|merge] command can be any of the |
| 436 | version identifier forms that work for [/help/update|update]. |
| 437 | ([./checkin_names.wiki|more info].) |
| 438 | The merge command has options to cherry-pick individual |
| 439 | changes, or to back out individual changes, if you don't want to |
| 440 | do a full merge.</p> |
| 441 | |
| 442 | The merge command puts all changes in your working check-out. |
| 443 | No changes are made to the repository. |
| 444 | You must run [/help/commit|commit] separately |
| 445 | to add the merge changes into your repository to make them persistent |
| 446 | and so that your coworkers can see them. |
| 447 | But before you do that, you will normally want to run a few tests |
| 448 | to verify that the merge didn't cause logic breaks in your code. |
| 449 | |
| 450 | The same branch can be merged multiple times without trouble. Fossil |
| 451 | automatically keeps up with things and avoids conflicts when doing |
| 452 | multiple merges. So even if you have merged the featureX branch |
| 453 | into trunk previously, you can do so again and Fossil will automatically |
| 454 | know to pull in only those changes that have occurred since the previous |
| 455 | merge. |
| 456 | |
| 457 | <p>If a merge or update doesn't work out (perhaps something breaks or |
| 458 | there are many merge conflicts) then you back up using:</p> |
| 459 | |
| 460 | <blockquote> |
| 461 | <b>[/help/undo | fossil undo]</b> |
| 462 | </blockquote> |
| 463 | |
| 464 | <p>This will back out the changes that the merge or update made to the |
| 465 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 466 | mistake. Undo and redo only work for changes that have |
| 467 | not yet been checked in using commit and there is only a single |
| 468 | level of undo/redo.</p> |
| 469 | |
| 470 | |
| 471 | <h2 id="server">Setting Up A Server</h2> |
| 472 | |
| 473 | <p>Fossil can act as a stand-alone web server using one of these |
| 474 | commands:</p> |
| 475 | |
| 476 | <blockquote> |
| 477 | <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> |
| 478 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 479 | </blockquote> |
| 480 | |
| 481 | <p>The <i>repository-filename</i> can be omitted when these commands |
| 482 | are run from within an open check-out, which a particularly useful |
| 483 | shortcut for the <b>fossil ui</b> command. |
| 484 | |
| 485 | <p>The <b>ui</b> command is intended for accessing the web interface |
| 486 | from a local desktop. The <b>ui</b> command binds to the loopback IP |
| 487 | address only (and thus makes the web interface visible only on the |
| 488 | local machine) and it automatically start your web browser pointing at the |
| 489 | server. For cross-machine collaboration, use the <b>server</b> command, |
| 490 | which binds on all IP addresses and does not try to start a web browser.</p> |
| 491 | |
| 492 | <p>Servers are also easily configured as: |
| 493 | <ul> |
| 494 | <li>[./server/any/inetd.md|inetd] |
| 495 | <li>[./server/debian/service.md|systemd] |
| 496 | <li>[./server/any/cgi.md|CGI] |
| 497 | <li>[./server/any/scgi.md|SCGI] |
| 498 | </ul> |
| 499 | |
| 500 | <p>The [./selfhost.wiki | self-hosting fossil repositories] use |
| 501 | CGI. |
| 502 | |
| 503 | <h2 id="proxy">HTTP Proxies</h2> |
| 504 | |
| 505 | <p>If you are behind a restrictive firewall that requires you to use |
| 506 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 507 | in three different ways. You can tell fossil about your proxy using |
| 508 | a command-line option on commands that use the network, |
| 509 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> |
| 510 | |
| 511 | <blockquote> |
| 512 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 513 | </blockquote> |
| 514 | |
| 515 | <p>It is annoying to have to type in the proxy URL every time you |
| 516 | sync your project, though, so you can make the proxy configuration |
| 517 | persistent using the [/help/setting | setting] command:</p> |
| 518 | |
| 519 | <blockquote> |
| 520 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 521 | </blockquote> |
| 522 | |
| 523 | <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> |
| 524 | |
| 525 | <blockquote> |
| 526 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 527 | </blockquote> |
| 528 | |
| 529 | <p>To stop using the proxy, do:</p> |
| 530 | |
| 531 | <blockquote> |
| 532 | <b>fossil setting proxy off</b> |
| 533 | </blockquote> |
| 534 | |
| 535 | <p>Or unset the environment variable. The fossil setting for the |
| 536 | HTTP proxy takes precedence over the environment variable and the |
| 537 | command-line option overrides both. If you have an persistent |
| 538 | proxy setting that you want to override for a one-time sync, that |
| 539 | is easily done on the command-line. For example, to sync with |
| 540 | a co-workers repository on your LAN, you might type:</p> |
| 541 | |
| 542 | <blockquote> |
| 543 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 544 | </blockquote> |
| 545 | |
| 546 | <h2 id="links">Other Resources</h2> |
| 547 | |
| 548 | <ul> |
| 549 | <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> |
| 550 | <li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a> |
| 551 | <li> <a href="./history.md">The History and Purpose of Fossil</a> |
| 552 | <li> <a href="./branching.wiki">Branching, Forking, and Tagging</a> |
| 553 | <li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a> |
| 554 | <li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a> |
| 555 | </ul> |
| 556 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -4,552 +4,552 @@ | |
| 4 | <p>This is a guide to help you get started using the Fossil [https://en.wikipedia.org/wiki/Distributed_version_control|Distributed Version Control System] quickly |
| 5 | and painlessly.</p> |
| 6 | |
| 7 | <h2 id="install">Installing</h2> |
| 8 | |
| 9 | <p>Fossil is a single self-contained C program. You need to |
| 10 | either download a |
| 11 | [https://www.fossil-scm.org/fossil/uv/download.html|precompiled |
| 12 | binary] |
| 13 | or <a href="build.wiki">compile it yourself</a> from sources. |
| 14 | Install Fossil by putting the fossil binary |
| 15 | someplace on your $PATH.</p> |
| 16 | You can test that Fossil is present and working like this: |
| 17 | |
| 18 | <blockquote> |
| 19 | <b> |
| 20 | fossil version<br> |
| 21 | <tt>This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC</tt><br> |
| 22 | </b> |
| 23 | </blockquote> |
| 24 | |
| 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | |
| 27 | <p>Fossil works with repository files (a database in a single file with the project's |
| 28 | complete history) and with checked-out local trees (the working directory |
| 29 | you use to do your work). |
| 30 | (See [./whyusefossil.wiki#definitions | definitions] for more background.) |
| 31 | The workflow looks like this:</p> |
| 32 | |
| 33 | <ul> |
| 34 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | [/help/clone | fossil clone]) |
| 36 | <li>Check out a local tree. ([/help/open | fossil open]) |
| 37 | <li>Perform operations on the repository (including repository |
| 38 | configuration). |
| 39 | </ul> |
| 40 | |
| 41 | Fossil can be entirely driven from the command line. Many features |
| 42 | can also be conveniently accessed from the build-in web interface. |
| 43 | |
| 44 | <p>The following sections give a brief overview of these |
| 45 | operations.</p> |
| 46 | |
| 47 | <h2 id="new">Starting A New Project</h2> |
| 48 | |
| 49 | <p>To start a new project with fossil create a new empty repository |
| 50 | this way: ([/help/init | more info]) </p> |
| 51 | |
| 52 | <blockquote> |
| 53 | <b>fossil init </b><i> repository-filename</i> |
| 54 | </blockquote> |
| 55 | |
| 56 | You can name the database anything you like, and you can place it anywhere in the filesystem. |
| 57 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 58 | <tt>[./help?cmd=/server | fossil server DIRECTORY]</tt> feature.” |
| 59 | |
| 60 | <h2 id="clone">Cloning An Existing Repository</h2> |
| 61 | |
| 62 | <p>Most fossil operations interact with a repository that is on the |
| 63 | local disk drive, not on a remote system. Hence, before accessing |
| 64 | a remote repository it is necessary to make a local copy of that |
| 65 | repository. Making a local copy of a remote repository is called |
| 66 | "cloning".</p> |
| 67 | |
| 68 | <p>Clone a remote repository as follows: ([/help/clone | more info])</p> |
| 69 | |
| 70 | <blockquote> |
| 71 | <b>fossil clone</b> <i>URL repository-filename</i> |
| 72 | </blockquote> |
| 73 | |
| 74 | <p>The <i>URL</i> specifies the fossil repository |
| 75 | you want to clone. The <i>repository-filename</i> is the new local |
| 76 | filename into which the cloned repository will be written. For |
| 77 | example, to clone the source code of Fossil itself: |
| 78 | |
| 79 | <blockquote> |
| 80 | <b>fossil clone https://www.fossil-scm.org/ myclone.fossil</b> |
| 81 | </blockquote> |
| 82 | |
| 83 | If your logged-in username is 'exampleuser', you should see output something like this: |
| 84 | |
| 85 | <blockquote> |
| 86 | <b><tt> |
| 87 | Round-trips: 8 Artifacts sent: 0 received: 39421<br> |
| 88 | Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0<br> |
| 89 | Rebuilding repository meta-data...<br> |
| 90 | 100% complete...<br> |
| 91 | Extra delta compression... <br> |
| 92 | Vacuuming the database... <br> |
| 93 | project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333<br> |
| 94 | server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> |
| 95 | admin-user: exampleuser (password is "yoWgDR42iv")><br> |
| 96 | </tt></b> |
| 97 | </blockquote> |
| 98 | |
| 99 | <p>If the remote repository requires a login, include a |
| 100 | userid in the URL like this: |
| 101 | |
| 102 | <blockquote> |
| 103 | <b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> |
| 104 | </blockquote> |
| 105 | |
| 106 | <p>You will be prompted separately for the password. |
| 107 | Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. |
| 108 | For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") </p> |
| 109 | |
| 110 | <p>If you are behind a restrictive firewall, you might need |
| 111 | to <a href="#proxy">specify an HTTP proxy</a>.</p> |
| 112 | |
| 113 | <p>A Fossil repository is a single disk file. Instead of cloning, |
| 114 | you can just make a copy of the repository file (for example, using |
| 115 | "scp"). Note, however, that the repository file contains auxiliary |
| 116 | information above and beyond the versioned files, including some |
| 117 | sensitive information such as password hashes and email addresses. If you |
| 118 | want to share Fossil repositories directly by copying, consider running the |
| 119 | [/help/scrub|fossil scrub] command to remove sensitive information |
| 120 | before transmitting the file. |
| 121 | |
| 122 | <h2 id="import">Importing From Another Version Control System</h2> |
| 123 | |
| 124 | <p>Rather than start a new project, or clone an existing Fossil project, |
| 125 | you might prefer to |
| 126 | <a href="./inout.wiki">import an existing Git project</a> |
| 127 | into Fossil using the [/help/import | fossil import] command. |
| 128 | |
| 129 | You can even decide to export your project back into git using the |
| 130 | [/help/git | fossil git] command, which is how the Fossil project maintains |
| 131 | [https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There |
| 132 | is no limit to the number of times a tree can be imported and exported between |
| 133 | Fossil and git. |
| 134 | |
| 135 | The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become |
| 136 | a popular way to move files between version management systems, including from |
| 137 | [https://www.mercurial-scm.org/|Mercurial]. |
| 138 | Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. |
| 139 | |
| 140 | <h2 id="checkout">Checking Out A Local Tree</h2> |
| 141 | |
| 142 | <p>To work on a project in fossil, you need to check out a local |
| 143 | copy of the source tree. Create the directory you want to be |
| 144 | the root of your tree and cd into that directory. Then |
| 145 | do this: ([/help/open | more info])</p> |
| 146 | |
| 147 | <blockquote> |
| 148 | <b>fossil open </b><i> repository-filename</i> |
| 149 | </blockquote> |
| 150 | |
| 151 | for example: |
| 152 | |
| 153 | <blockquote> |
| 154 | <b><tt> |
| 155 | fossil open ../myclone.fossil<br> |
| 156 | BUILD.txt<br> |
| 157 | COPYRIGHT-BSD2.txt<br> |
| 158 | README.md<br> |
| 159 | ︙<br> |
| 160 | </tt></b> |
| 161 | </blockquote> |
| 162 | |
| 163 | (or "fossil open ..\myclone.fossil" on Windows). |
| 164 | |
| 165 | <p>This leaves you with the newest version of the tree |
| 166 | checked out. |
| 167 | From anywhere underneath the root of your local tree, you |
| 168 | can type commands like the following to find out the status of |
| 169 | your local tree:</p> |
| 170 | |
| 171 | <blockquote> |
| 172 | <b>[/help/info | fossil info]</b><br> |
| 173 | <b>[/help/status | fossil status]</b><br> |
| 174 | <b>[/help/changes | fossil changes]</b><br> |
| 175 | <b>[/help/diff | fossil diff]</b><br> |
| 176 | <b>[/help/timeline | fossil timeline]</b><br> |
| 177 | <b>[/help/ls | fossil ls]</b><br> |
| 178 | <b>[/help/branch | fossil branch]</b><br> |
| 179 | </blockquote> |
| 180 | |
| 181 | <p>If you created a new respository using "fossil init" some commands will not |
| 182 | produce much output.</p> |
| 183 | |
| 184 | <p>Note that Fossil allows you to make multiple check-outs in |
| 185 | separate directories from the same repository. This enables you, |
| 186 | for example, to do builds from multiple branches or versions at |
| 187 | the same time without having to generate extra clones.</p> |
| 188 | |
| 189 | <p>To switch a checkout between different versions and branches, |
| 190 | use:</p> |
| 191 | |
| 192 | <blockquote> |
| 193 | <b>[/help/update | fossil update]</b><br> |
| 194 | <b>[/help/checkout | fossil checkout]</b><br> |
| 195 | </blockquote> |
| 196 | |
| 197 | <p>[/help/update | update] honors the "autosync" option and |
| 198 | does a "soft" switch, merging any local changes into the target |
| 199 | version, whereas [/help/checkout | checkout] does not |
| 200 | automatically sync and does a "hard" switch, overwriting local |
| 201 | changes if told to do so.</p> |
| 202 | |
| 203 | <h2 id="changes">Making and Commiting Changes</h2> |
| 204 | |
| 205 | <p>To add new files to your project or remove existing ones, use these |
| 206 | commands:</p> |
| 207 | |
| 208 | <blockquote> |
| 209 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 210 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 211 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 212 | </blockquote> |
| 213 | |
| 214 | <p>The command:</p> |
| 215 | <blockquote> |
| 216 | <b> |
| 217 | [/help/changes | fossil changes]</b> |
| 218 | </blockquote> |
| 219 | <p>lists files that have changed since the last commit to the repository. For |
| 220 | example, if you edit the file "README.md":</p> |
| 221 | |
| 222 | <blockquote> |
| 223 | <b> |
| 224 | fossil changes<br> |
| 225 | EDITED README.md |
| 226 | </b> |
| 227 | </blockquote> |
| 228 | |
| 229 | <p>To see exactly what change was made you can use the command</p> |
| 230 | [/help/diff | fossil diff]: |
| 231 | <blockquote> |
| 232 | <b> |
| 233 | fossil diff <br><tt> |
| 234 | Index: README.md<br> |
| 235 | ============================================================<br> |
| 236 | --- README.md<br> |
| 237 | +++ README.md<br> |
| 238 | @@ -1,5 +1,6 @@<br> |
| 239 | +Made some changes to the project<br> |
| 240 | # Original text<br> |
| 241 | </tt></b> |
| 242 | </blockquote> |
| 243 | |
| 244 | <p>"fossil diff" is the difference between your tree on disk now and as the tree was |
| 245 | when you did "fossil open". An open is the first checkout from a repository |
| 246 | into a new directory. </p> |
| 247 | |
| 248 | <p>To commit your changes to a local-only repository:</p> |
| 249 | <blockquote> |
| 250 | <b> |
| 251 | fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> |
| 252 | # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> |
| 253 | #<br> |
| 254 | # user: exampleuser<br> |
| 255 | # tags: trunk<br> |
| 256 | #<br> |
| 257 | # EDITED README.md<br> |
| 258 | Edited file to add description of code changes<br> |
| 259 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> |
| 260 | </tt></b> |
| 261 | </blockquote> |
| 262 | |
| 263 | <p>You will be prompted for check-in comments using whatever editor |
| 264 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 265 | specified Fossil uses line-editing in the terminal.</p> |
| 266 | |
| 267 | <p>To commit your changes to a repository that was cloned from remote you |
| 268 | perform the same actions but the results are different. Fossil |
| 269 | defaults to 'autosync' mode, a single-stage commit that sends all changes |
| 270 | committed to the local repository immediately on to the remote parent repository. This |
| 271 | only works if you have write permission to the remote respository.</p> |
| 272 | |
| 273 | <h2 id="naming">Naming of Files, Checkins, and Branches</h2> |
| 274 | |
| 275 | <p>Fossil deals with information artifacts. This Quickstart document only deals |
| 276 | with files and collections of files, but be aware there are also tickets, wiki pages and more. |
| 277 | Every artifact in Fossil has a universally-unique hash id, and may also have a |
| 278 | human-readable name.</p> |
| 279 | |
| 280 | <p>The following are all equivalent ways of identifying a Fossil file, |
| 281 | checkin or branch artifact:</p> |
| 282 | |
| 283 | <ul> |
| 284 | <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a |
| 285 | <li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters |
| 286 | <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash |
| 287 | </ul> |
| 288 | |
| 289 | <p>A special convenience branch is "trunk", which is Fossil's default branch name for |
| 290 | the first checkin, and the default for any time a branch name is needed but not |
| 291 | specified.</p> |
| 292 | |
| 293 | This will get you started on identifying checkins. The |
| 294 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 295 | how timestamps can also be used. |
| 296 | |
| 297 | <h2 id="config">Configuring Your Local Repository</h2> |
| 298 | |
| 299 | <p>When you create a new repository, either by cloning an existing |
| 300 | project or create a new project of your own, you usually want to do some |
| 301 | local configuration. This is easily accomplished using the web-server |
| 302 | that is built into fossil. Start the fossil web server like this: |
| 303 | ([/help/ui | more info])</p> |
| 304 | |
| 305 | <blockquote> |
| 306 | <b>fossil ui </b><i> repository-filename</i> |
| 307 | </blockquote> |
| 308 | |
| 309 | <p>You can omit the <i>repository-filename</i> from the command above |
| 310 | if you are inside a checked-out local tree.</p> |
| 311 | |
| 312 | <p>This starts a web server then automatically launches your |
| 313 | web browser and makes it point to this web server. If your system |
| 314 | has an unusual configuration, fossil might not be able to figure out |
| 315 | how to start your web browser. In that case, first tell fossil |
| 316 | where to find your web browser using a command like this:</p> |
| 317 | |
| 318 | <blockquote> |
| 319 | <b>fossil setting web-browser </b><i> path-to-web-browser</i> |
| 320 | </blockquote> |
| 321 | |
| 322 | <p>By default, fossil does not require a login for HTTP connections |
| 323 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 324 | should, change this after you create a few users.</p> |
| 325 | |
| 326 | <p>When you are finished configuring, just press Control-C or use |
| 327 | the <b>kill</b> command to shut down the mini-server.</p> |
| 328 | |
| 329 | <h2 id="changes">Making Changes</h2> |
| 330 | |
| 331 | <p>To add new files to your project, or remove old files, use these |
| 332 | commands:</p> |
| 333 | |
| 334 | <blockquote> |
| 335 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 336 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 337 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 338 | </blockquote> |
| 339 | |
| 340 | <p>You can also edit files freely. Once you are ready to commit |
| 341 | your changes, type:</p> |
| 342 | |
| 343 | <blockquote> |
| 344 | <b>[/help/commit | fossil commit]</b> |
| 345 | </blockquote> |
| 346 | |
| 347 | <p>You will be prompted for check-in comments using whatever editor |
| 348 | is specified by your VISUAL or EDITOR environment variable.</p> |
| 349 | |
| 350 | In the default configuration, the [/help/commit|commit] |
| 351 | command will also automatically [/help/push|push] your changes, but that |
| 352 | feature can be disabled. (More information about |
| 353 | [./concepts.wiki#workflow|autosync] and how to disable it.) |
| 354 | Remember that your coworkers can not see your changes until you |
| 355 | commit and push them.</p> |
| 356 | |
| 357 | <h2 id="sharing">Sharing Changes</h2> |
| 358 | |
| 359 | <p>When [./concepts.wiki#workflow|autosync] is turned off, |
| 360 | the changes you [/help/commit | commit] are only |
| 361 | on your local repository. |
| 362 | To share those changes with other repositories, do:</p> |
| 363 | |
| 364 | <blockquote> |
| 365 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 366 | </blockquote> |
| 367 | |
| 368 | <p>Where <i>URL</i> is the http: URL of the server repository you |
| 369 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 370 | fossil will use whatever server you most recently synced with.</p> |
| 371 | |
| 372 | <p>The [/help/push | push] command only sends your changes to others. To |
| 373 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 374 | once using [/help/sync | sync]:</p> |
| 375 | |
| 376 | <blockquote> |
| 377 | <b>[/help/pull | fossil pull]</b> <i>URL</i><br> |
| 378 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 379 | </blockquote> |
| 380 | |
| 381 | <p>When you pull in changes from others, they go into your repository, |
| 382 | not into your checked-out local tree. To get the changes into your |
| 383 | local tree, use [/help/update | update]:</p> |
| 384 | |
| 385 | <blockquote> |
| 386 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 387 | </blockquote> |
| 388 | |
| 389 | <p>The <i>VERSION</i> can be the name of a branch or tag or any |
| 390 | abbreviation to the 40-character |
| 391 | artifact identifier for a particular check-in, or it can be a |
| 392 | date/time stamp. ([./checkin_names.wiki | more info]) |
| 393 | If you omit |
| 394 | the <i>VERSION</i>, then fossil moves you to the |
| 395 | latest version of the branch your are currently on.</p> |
| 396 | |
| 397 | <p>The default behavior is for [./concepts.wiki#workflow|autosync] to |
| 398 | be turned on. That means that a [/help/pull|pull] automatically occurs |
| 399 | when you run [/help/update|update] and a [/help/push|push] happens |
| 400 | automatically after you [/help/commit|commit]. So in normal practice, |
| 401 | the push, pull, and sync commands are rarely used. But it is important |
| 402 | to know about them, all the same.</p> |
| 403 | |
| 404 | <blockquote> |
| 405 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 406 | </blockquote> |
| 407 | |
| 408 | <p>Is similar to update except that it does not honor the autosync |
| 409 | setting, nor does it merge in local changes - it prefers to overwrite |
| 410 | them and fails if local changes exist unless the <tt>--force</tt> |
| 411 | flag is used.</p> |
| 412 | |
| 413 | <h2 id="branch" name="merge">Branching And Merging</h2> |
| 414 | |
| 415 | <p>Use the --branch option to the [/help/commit | commit] command |
| 416 | to start a new branch. Note that in Fossil, branches are normally |
| 417 | created when you commit, not before you start editing. You can |
| 418 | use the [/help/branch | branch new] command to create a new branch |
| 419 | before you start editing, if you want, but most people just wait |
| 420 | until they are ready to commit. |
| 421 | |
| 422 | To merge two branches back together, first |
| 423 | [/help/update | update] to the branch you want to merge into. |
| 424 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 425 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 426 | do this:</p> |
| 427 | |
| 428 | <blockquote> |
| 429 | <b>fossil [/help/update|update] trunk</b><br> |
| 430 | <b>fossil [/help/merge|merge] featureX</b><br> |
| 431 | <i># make sure the merge didn't break anything...</i><br> |
| 432 | <b>fossil [/help/commit|commit] |
| 433 | </blockquote> |
| 434 | |
| 435 | <p>The argument to the [/help/merge|merge] command can be any of the |
| 436 | version identifier forms that work for [/help/update|update]. |
| 437 | ([./checkin_names.wiki|more info].) |
| 438 | The merge command has options to cherry-pick individual |
| 439 | changes, or to back out individual changes, if you don't want to |
| 440 | do a full merge.</p> |
| 441 | |
| 442 | The merge command puts all changes in your working check-out. |
| 443 | No changes are made to the repository. |
| 444 | You must run [/help/commit|commit] separately |
| 445 | to add the merge changes into your repository to make them persistent |
| 446 | and so that your coworkers can see them. |
| 447 | But before you do that, you will normally want to run a few tests |
| 448 | to verify that the merge didn't cause logic breaks in your code. |
| 449 | |
| 450 | The same branch can be merged multiple times without trouble. Fossil |
| 451 | automatically keeps up with things and avoids conflicts when doing |
| 452 | multiple merges. So even if you have merged the featureX branch |
| 453 | into trunk previously, you can do so again and Fossil will automatically |
| 454 | know to pull in only those changes that have occurred since the previous |
| 455 | merge. |
| 456 | |
| 457 | <p>If a merge or update doesn't work out (perhaps something breaks or |
| 458 | there are many merge conflicts) then you back up using:</p> |
| 459 | |
| 460 | <blockquote> |
| 461 | <b>[/help/undo | fossil undo]</b> |
| 462 | </blockquote> |
| 463 | |
| 464 | <p>This will back out the changes that the merge or update made to the |
| 465 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 466 | mistake. Undo and redo only work for changes that have |
| 467 | not yet been checked in using commit and there is only a single |
| 468 | level of undo/redo.</p> |
| 469 | |
| 470 | |
| 471 | <h2 id="server">Setting Up A Server</h2> |
| 472 | |
| 473 | <p>Fossil can act as a stand-alone web server using one of these |
| 474 | commands:</p> |
| 475 | |
| 476 | <blockquote> |
| 477 | <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> |
| 478 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 479 | </blockquote> |
| 480 | |
| 481 | <p>The <i>repository-filename</i> can be omitted when these commands |
| 482 | are run from within an open check-out, which a particularly useful |
| 483 | shortcut for the <b>fossil ui</b> command. |
| 484 | |
| 485 | <p>The <b>ui</b> command is intended for accessing the web interface |
| 486 | from a local desktop. The <b>ui</b> command binds to the loopback IP |
| 487 | address only (and thus makes the web interface visible only on the |
| 488 | local machine) and it automatically start your web browser pointing at the |
| 489 | server. For cross-machine collaboration, use the <b>server</b> command, |
| 490 | which binds on all IP addresses and does not try to start a web browser.</p> |
| 491 | |
| 492 | <p>Servers are also easily configured as: |
| 493 | <ul> |
| 494 | <li>[./server/any/inetd.md|inetd] |
| 495 | <li>[./server/debian/service.md|systemd] |
| 496 | <li>[./server/any/cgi.md|CGI] |
| 497 | <li>[./server/any/scgi.md|SCGI] |
| 498 | </ul> |
| 499 | |
| 500 | <p>The [./selfhost.wiki | self-hosting fossil repositories] use |
| 501 | CGI. |
| 502 | |
| 503 | <h2 id="proxy">HTTP Proxies</h2> |
| 504 | |
| 505 | <p>If you are behind a restrictive firewall that requires you to use |
| 506 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 507 | in three different ways. You can tell fossil about your proxy using |
| 508 | a command-line option on commands that use the network, |
| 509 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> |
| 510 | |
| 511 | <blockquote> |
| 512 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 513 | </blockquote> |
| 514 | |
| 515 | <p>It is annoying to have to type in the proxy URL every time you |
| 516 | sync your project, though, so you can make the proxy configuration |
| 517 | persistent using the [/help/setting | setting] command:</p> |
| 518 | |
| 519 | <blockquote> |
| 520 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 521 | </blockquote> |
| 522 | |
| 523 | <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> |
| 524 | |
| 525 | <blockquote> |
| 526 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 527 | </blockquote> |
| 528 | |
| 529 | <p>To stop using the proxy, do:</p> |
| 530 | |
| 531 | <blockquote> |
| 532 | <b>fossil setting proxy off</b> |
| 533 | </blockquote> |
| 534 | |
| 535 | <p>Or unset the environment variable. The fossil setting for the |
| 536 | HTTP proxy takes precedence over the environment variable and the |
| 537 | command-line option overrides both. If you have an persistent |
| 538 | proxy setting that you want to override for a one-time sync, that |
| 539 | is easily done on the command-line. For example, to sync with |
| 540 | a co-workers repository on your LAN, you might type:</p> |
| 541 | |
| 542 | <blockquote> |
| 543 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 544 | </blockquote> |
| 545 | |
| 546 | <h2 id="links">Other Resources</h2> |
| 547 | |
| 548 | <ul> |
| 549 | <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> |
| 550 | <li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a> |
| 551 | <li> <a href="./history.md">The History and Purpose of Fossil</a> |
| 552 | <li> <a href="./branching.wiki">Branching, Forking, and Tagging</a> |
| 553 | <li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a> |
| 554 | <li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a> |
| 555 | </ul> |
| 556 |