Fossil SCM

fossil-scm / www / quickstart.wiki
Source Blame History 577 lines
5523218… drh 1 <title>Fossil Quick Start Guide</title>
f392fac… wyoung 2
1fd407f… wyoung 3 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
1fd407f… wyoung 4 and painlessly.
f392fac… wyoung 5
f392fac… wyoung 6 <h2 id="install">Installing</h2>
f392fac… wyoung 7
1fd407f… wyoung 8 Fossil is a single self-contained C program. You need to
3ff0968… drh 9 either download a
09908ab… drh 10 [https://fossil-scm.org/home/uv/download.html|precompiled
3ff0968… drh 11 binary]
3ff0968… drh 12 or <a href="build.wiki">compile it yourself</a> from sources.
3ff0968… drh 13 Install Fossil by putting the fossil binary
1fd407f… wyoung 14 someplace on your $PATH.
1fd407f… wyoung 15
3ff0968… drh 16 You can test that Fossil is present and working like this:
3ff0968… drh 17
8a1ba49… wyoung 18 <pre><b>fossil version
4f42cae… wyoung 19 This is fossil version 2.25 [8f798279d5] 2024-11-06 12:59:09 UTC
8a1ba49… wyoung 20 </b></pre>
8da7b15… wyoung 21
8da7b15… wyoung 22 <h2 id="workflow" name="fslclone">General Work Flow</h2>
8da7b15… wyoung 23
ab7a22f… wyoung 24 Fossil works with [./glossary.md#repository | repository files]
ab7a22f… wyoung 25 and [./glossary.md#check-out | check-out directories] using a
ab7a22f… wyoung 26 workflow like this:
3ff0968… drh 27
3ff0968… drh 28 <ul>
3ff0968… drh 29 <li>Create or clone a repository file. ([/help/init|fossil init] or
3ff0968… drh 30 [/help/clone | fossil clone])
3ff0968… drh 31 <li>Check out a local tree. ([/help/open | fossil open])
3ff0968… drh 32 <li>Perform operations on the repository (including repository
3ff0968… drh 33 configuration).
3ff0968… drh 34 </ul>
3ff0968… drh 35
3ff0968… drh 36 Fossil can be entirely driven from the command line. Many features
f17ab29… wyoung 37 can also be conveniently accessed from the built-in web user interface.
3ff0968… drh 38
1fd407f… wyoung 39 The following sections give a brief overview of these
1fd407f… wyoung 40 operations.
8da7b15… wyoung 41
8da7b15… wyoung 42 <h2 id="new">Starting A New Project</h2>
8da7b15… wyoung 43
529b947… wyoung 44 To start a new project with Fossil, [/help/init | create a new empty repository]:
3ff0968… drh 45
8a1ba49… wyoung 46 <pre><b>fossil init</b> <i>repository-filename</i>
8a1ba49… wyoung 47 </pre>
3ff0968… drh 48
3ff0968… drh 49 You can name the database anything you like, and you can place it anywhere in the filesystem.
4f42cae… wyoung 50 The <tt>.fossil</tt> extension is traditional, but it is only required if you are going to use the
4f42cae… wyoung 51 <tt>[/help/server | fossil server DIRECTORY]</tt> feature.
4f42cae… wyoung 52
4f42cae… wyoung 53 Next, do something along the lines of:
4f42cae… wyoung 54
4f42cae… wyoung 55 <pre>
4f42cae… wyoung 56 <b>mkdir -p ~/src/project/trunk</b>
4f42cae… wyoung 57 <b>cd ~/src/project/trunk</b>
4f42cae… wyoung 58 <b>fossil open</b> <i>repository-filename</i>
4f42cae… wyoung 59 <b>fossil add</b> foo.c bar.h qux.md
4f42cae… wyoung 60 <b>fossil commit</b>
4f42cae… wyoung 61 </pre>
4f42cae… wyoung 62
4f42cae… wyoung 63 If your project directory already exists, obviating the <b>mkdir</b>
4f42cae… wyoung 64 step, you will instead need to add the <tt>--force</tt> flag to the
4f42cae… wyoung 65 <b>open</b> command to authorize Fossil to open the repo into a
4f42cae… wyoung 66 non-empty checkout directory. (This is to avoid accidental opens into,
4f42cae… wyoung 67 for example, your home directory.)
4f42cae… wyoung 68
4f42cae… wyoung 69 The convention of naming your checkout directory after a long-lived
4f42cae… wyoung 70 branch name like "trunk" is in support of Fossil's ability to have as
4f42cae… wyoung 71 many open checkouts as you like. This author frequently has additional
4f42cae… wyoung 72 checkout directories named <tt>../release</tt>, <tt>../scratch</tt>,
4f42cae… wyoung 73 etc. The release directory is open to the branch of the same name, while
4f42cae… wyoung 74 the scratch directory is used when disturbing one of the other
4f42cae… wyoung 75 long-lived checkout directories is undesireable, as when performing a
4f42cae… wyoung 76 [/help/bisect | bisect] operation.
4f42cae… wyoung 77
8da7b15… wyoung 78
8da7b15… wyoung 79 <h2 id="clone">Cloning An Existing Repository</h2>
8da7b15… wyoung 80
1fd407f… wyoung 81 Most fossil operations interact with a repository that is on the
3ff0968… drh 82 local disk drive, not on a remote system. Hence, before accessing
3ff0968… drh 83 a remote repository it is necessary to make a local copy of that
eb52410… wyoung 84 repository, a process called
eb52410… wyoung 85 "[/help/clone | cloning]".
8a1ba49… wyoung 86
eb52410… wyoung 87 This is done as follows:
8a1ba49… wyoung 88
8a1ba49… wyoung 89 <pre><b>fossil clone</b> <i>URL repository-filename</i>
8a1ba49… wyoung 90 </pre>
1fd407f… wyoung 91
1fd407f… wyoung 92 The <i>URL</i> specifies the fossil repository
3ff0968… drh 93 you want to clone. The <i>repository-filename</i> is the new local
3ff0968… drh 94 filename into which the cloned repository will be written. For
3ff0968… drh 95 example, to clone the source code of Fossil itself:
3ff0968… drh 96
8a1ba49… wyoung 97 <pre><b>fossil clone https://fossil-scm.org/ myclone.fossil</b></pre>
3ff0968… drh 98
3ff0968… drh 99 If your logged-in username is 'exampleuser', you should see output something like this:
3ff0968… drh 100
8a1ba49… wyoung 101 <pre><b>Round-trips: 8 Artifacts sent: 0 received: 39421
8a1ba49… wyoung 102 Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0
8a1ba49… wyoung 103 Rebuilding repository meta-data...
8a1ba49… wyoung 104 100% complete...
8a1ba49… wyoung 105 Extra delta compression...
8a1ba49… wyoung 106 Vacuuming the database...
8a1ba49… wyoung 107 project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333
8a1ba49… wyoung 108 server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42
7ebd944… danield 109 admin-user: exampleuser (intial remote-access password is "yoWgDR42iv")>
8a1ba49… wyoung 110 </b></pre>
f5b9f01… andybradford 111
f5b9f01… andybradford 112 This <i>exampleuser</i> will be used by Fossil as the author of commits when
f5b9f01… andybradford 113 you checkin changes to the repository. It is also used by Fossil when you
f5b9f01… andybradford 114 make your repository available to others using the built-in server mode by
f5b9f01… andybradford 115 running <tt>[/help/server | fossil server]</tt> and will also be used when
7ebd944… danield 116 running <tt>[/help/ui | fossil ui]</tt> to view the repository through
f5b9f01… andybradford 117 the Fossil UI. See the quick start topic for setting up a
f5b9f01… andybradford 118 <a href="#server">server</a> for more details.
1fd407f… wyoung 119
1fd407f… wyoung 120 If the remote repository requires a login, include a
3ff0968… drh 121 userid in the URL like this:
3ff0968… drh 122
8a1ba49… wyoung 123 <pre><b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b></pre>
1fd407f… wyoung 124
1fd407f… wyoung 125 You will be prompted separately for the password.
1fd407f… wyoung 126 Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid.
1fd407f… wyoung 127 For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget")
1fd407f… wyoung 128
1fd407f… wyoung 129 If you are behind a restrictive firewall, you might need
1fd407f… wyoung 130 to <a href="#proxy">specify an HTTP proxy</a>.
1fd407f… wyoung 131
1fd407f… wyoung 132 A Fossil repository is a single disk file. Instead of cloning,
3ff0968… drh 133 you can just make a copy of the repository file (for example, using
3ff0968… drh 134 "scp"). Note, however, that the repository file contains auxiliary
3ff0968… drh 135 information above and beyond the versioned files, including some
3ff0968… drh 136 sensitive information such as password hashes and email addresses. If you
3ff0968… drh 137 want to share Fossil repositories directly by copying, consider running the
3ff0968… drh 138 [/help/scrub|fossil scrub] command to remove sensitive information
3ff0968… drh 139 before transmitting the file.
8da7b15… wyoung 140
8da7b15… wyoung 141 <h2 id="import">Importing From Another Version Control System</h2>
8da7b15… wyoung 142
1fd407f… wyoung 143 Rather than start a new project, or clone an existing Fossil project,
3ff0968… drh 144 you might prefer to
3ff0968… drh 145 <a href="./inout.wiki">import an existing Git project</a>
3ff0968… drh 146 into Fossil using the [/help/import | fossil import] command.
3ff0968… drh 147
3ff0968… drh 148 You can even decide to export your project back into git using the
3ff0968… drh 149 [/help/git | fossil git] command, which is how the Fossil project maintains
3ff0968… drh 150 [https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There
3ff0968… drh 151 is no limit to the number of times a tree can be imported and exported between
3ff0968… drh 152 Fossil and git.
3ff0968… drh 153
3ff0968… drh 154 The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become
3ff0968… drh 155 a popular way to move files between version management systems, including from
3ff0968… drh 156 [https://www.mercurial-scm.org/|Mercurial].
3ff0968… drh 157 Fossil can also import [https://subversion.apache.org/|Subversion projects] directly.
8da7b15… wyoung 158
8da7b15… wyoung 159 <h2 id="checkout">Checking Out A Local Tree</h2>
8da7b15… wyoung 160
1fd407f… wyoung 161 To work on a project in fossil, you need to check out a local
3ff0968… drh 162 copy of the source tree. Create the directory you want to be
eb52410… wyoung 163 the root of your tree, <tt>cd</tt> into that directory, and then:
8a1ba49… wyoung 164
8a1ba49… wyoung 165 <pre><b>fossil open</b> <i>repository-filename</i></pre>
8a1ba49… wyoung 166
eb52410… wyoung 167 For example:
8a1ba49… wyoung 168
8a1ba49… wyoung 169 <pre><b>fossil open ../myclone.fossil
8a1ba49… wyoung 170 BUILD.txt
8a1ba49… wyoung 171 COPYRIGHT-BSD2.txt
8a1ba49… wyoung 172 README.md
8a1ba49… wyoung 173 ︙
8a1ba49… wyoung 174 </tt></b></pre>
1fd407f… wyoung 175
1fd407f… wyoung 176 This leaves you with the newest version of the tree
3ff0968… drh 177 checked out.
3ff0968… drh 178 From anywhere underneath the root of your local tree, you
3ff0968… drh 179 can type commands like the following to find out the status of
1fd407f… wyoung 180 your local tree:
1fd407f… wyoung 181
8a1ba49… wyoung 182 <pre>
8a1ba49… wyoung 183 <b>[/help/info | fossil info]</b>
8a1ba49… wyoung 184 <b>[/help/status | fossil status]</b>
8a1ba49… wyoung 185 <b>[/help/changes | fossil changes]</b>
8a1ba49… wyoung 186 <b>[/help/diff | fossil diff]</b>
8a1ba49… wyoung 187 <b>[/help/timeline | fossil timeline]</b>
8a1ba49… wyoung 188 <b>[/help/ls | fossil ls]</b>
8a1ba49… wyoung 189 <b>[/help/branch | fossil branch]</b>
8a1ba49… wyoung 190 </pre>
1fd407f… wyoung 191
1fd407f… wyoung 192 If you created a new repository using "fossil init" some commands will not
1fd407f… wyoung 193 produce much output.
1fd407f… wyoung 194
1fd407f… wyoung 195 Note that Fossil allows you to make multiple check-outs in
3ff0968… drh 196 separate directories from the same repository. This enables you,
3ff0968… drh 197 for example, to do builds from multiple branches or versions at
1fd407f… wyoung 198 the same time without having to generate extra clones.
1fd407f… wyoung 199
1fd407f… wyoung 200 To switch a checkout between different versions and branches,
2b4a8b4… wyoung 201 use:
1fd407f… wyoung 202
8a1ba49… wyoung 203 <pre>
8a1ba49… wyoung 204 <b>[/help/update | fossil update]</b>
8a1ba49… wyoung 205 <b>[/help/checkout | fossil checkout]</b>
8a1ba49… wyoung 206 </pre>
1fd407f… wyoung 207
1fd407f… wyoung 208 [/help/update | update] honors the "autosync" option and
3ff0968… drh 209 does a "soft" switch, merging any local changes into the target
3ff0968… drh 210 version, whereas [/help/checkout | checkout] does not
3ff0968… drh 211 automatically sync and does a "hard" switch, overwriting local
1fd407f… wyoung 212 changes if told to do so.
e755561… danield 213
e755561… danield 214 <h2 id="changes">Making and Committing Changes</h2>
e755561… danield 215
1fd407f… wyoung 216 To add new files to your project or remove existing ones, use these
1fd407f… wyoung 217 commands:
1fd407f… wyoung 218
8a1ba49… wyoung 219 <pre>
8a1ba49… wyoung 220 <b>[/help/add | fossil add]</b> <i>file...</i>
8a1ba49… wyoung 221 <b>[/help/rm | fossil rm]</b> <i>file...</i>
8a1ba49… wyoung 222 <b>[/help/addremove | fossil addremove]</b> <i>file...</i>
8a1ba49… wyoung 223 </pre>
1fd407f… wyoung 224
1fd407f… wyoung 225 The command:
1fd407f… wyoung 226
8a1ba49… wyoung 227 <pre><b>[/help/changes | fossil changes]</b></pre>
1fd407f… wyoung 228
1fd407f… wyoung 229 lists files that have changed since the last commit to the repository. For
1fd407f… wyoung 230 example, if you edit the file "README.md":
1fd407f… wyoung 231
8a1ba49… wyoung 232 <pre><b>fossil changes
8a1ba49… wyoung 233 EDITED README.md
8a1ba49… wyoung 234 </b></pre>
1fd407f… wyoung 235
1fd407f… wyoung 236 To see exactly what change was made you can use the command
1fd407f… wyoung 237 <b>[/help/diff | fossil diff]</b>:
1fd407f… wyoung 238
8a1ba49… wyoung 239 <pre><b>fossil diff
8a1ba49… wyoung 240 Index: README.md
8a1ba49… wyoung 241 ============================================================
8a1ba49… wyoung 242 --- README.md
8a1ba49… wyoung 243 +++ README.md
8a1ba49… wyoung 244 @@ -1,5 +1,6 @@
8a1ba49… wyoung 245 +Made some changes to the project
8a1ba49… wyoung 246 # Original text
8a1ba49… wyoung 247 </b></pre>
39beee4… wyoung 248
39beee4… wyoung 249 "fossil diff" shows the difference between your tree on disk now and as
39beee4… wyoung 250 the tree was when you last committed changes. If you haven't committed
39beee4… wyoung 251 yet, then it shows the difference relative to the tip-of-trunk commit in
39beee4… wyoung 252 the repository, being what you get when you "fossil open" a repository
39beee4… wyoung 253 without specifying a version, populating the working directory.
1fd407f… wyoung 254
1fd407f… wyoung 255 To see the most recent changes made to the repository by other users, use "fossil timeline" to
19f4b06… danshearer 256 find out the most recent commit, and then "fossil diff" between that commit and the
1fd407f… wyoung 257 current tree:
8a1ba49… wyoung 258
c64f28d… drh 259 <pre><b><verbatim>fossil timeline
c64f28d… drh 260 === 2021-03-28 ===
8a1ba49… wyoung 261 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk)
8a1ba49… wyoung 262 === 2021-03-27 ===
8a1ba49… wyoung 263 23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk)
8a1ba49… wyoung 264 ⋮
8a1ba49… wyoung 265
8a1ba49… wyoung 266 fossil diff --from current --to ab975c6632
8a1ba49… wyoung 267 Index: frobnicate.c
8a1ba49… wyoung 268 ============================================================
8a1ba49… wyoung 269 --- frobnicate.c
8a1ba49… wyoung 270 +++ frobnicate.c
8a1ba49… wyoung 271 @@ -1,10 +1,11 @@
8a1ba49… wyoung 272 +/* made a change to the source file */
8a1ba49… wyoung 273 # Original text
c64f28d… drh 274 </verbatim></b></pre>
68344d6… george 275
68344d6… george 276 "current" is an alias for the checkout version, so the command
19f4b06… danshearer 277 "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results.
19f4b06… danshearer 278
1fd407f… wyoung 279 To commit your changes to a local-only repository:
8a1ba49… wyoung 280
8a1ba49… wyoung 281 <pre><b>fossil commit</b> <i>(... Fossil will start your editor, if defined)</i><b>
8a1ba49… wyoung 282 # Enter a commit message for this check-in. Lines beginning with # are ignored.
8a1ba49… wyoung 283 #
8a1ba49… wyoung 284 # user: exampleuser
8a1ba49… wyoung 285 # tags: trunk
8a1ba49… wyoung 286 #
8a1ba49… wyoung 287 # EDITED README.md
8a1ba49… wyoung 288 Edited file to add description of code changes
8a1ba49… wyoung 289 New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab
8a1ba49… wyoung 290 </b></pre>
1fd407f… wyoung 291
1fd407f… wyoung 292 You will be prompted for check-in comments using whatever editor
3ff0968… drh 293 is specified by your VISUAL or EDITOR environment variable. If none is
1fd407f… wyoung 294 specified Fossil uses line-editing in the terminal.
3ff0968… drh 295
39beee4… wyoung 296 To commit your changes to a repository that was cloned from a remote
39beee4… wyoung 297 repository, you give the same command, but the results are different.
39beee4… wyoung 298 Fossil defaults to [./concepts.wiki#workflow|autosync] mode, a
39beee4… wyoung 299 single-stage commit that sends all changes committed to the local
39beee4… wyoung 300 repository immediately on to the remote parent repository. This only
7db623e… danield 301 works if you have write permission to the remote repository.
590a8fc… danshearer 302
590a8fc… danshearer 303 <h2 id="naming">Naming of Files, Checkins, and Branches</h2>
590a8fc… danshearer 304
1fd407f… wyoung 305 Fossil deals with information artifacts. This Quickstart document only deals
3ff0968… drh 306 with files and collections of files, but be aware there are also tickets, wiki pages and more.
3ff0968… drh 307 Every artifact in Fossil has a universally-unique hash id, and may also have a
1fd407f… wyoung 308 human-readable name.
3ff0968… drh 309
1fd407f… wyoung 310 The following are all equivalent ways of identifying a Fossil file,
1fd407f… wyoung 311 checkin or branch artifact:
3ff0968… drh 312
3ff0968… drh 313 <ul>
3ff0968… drh 314 <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a
3ff0968… drh 315 <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
3ff0968… drh 316 <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash
3ff0968… drh 317 </ul>
3ff0968… drh 318
1fd407f… wyoung 319 A special convenience branch is "trunk", which is Fossil's default branch name for
3ff0968… drh 320 the first checkin, and the default for any time a branch name is needed but not
1fd407f… wyoung 321 specified.
3ff0968… drh 322
3ff0968… drh 323 This will get you started on identifying checkins. The
3ff0968… drh 324 <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including
3ff0968… drh 325 how timestamps can also be used.
3ff0968… drh 326
6a2fee8… wyoung 327 <h2 id="config">Accessing Your Local Repository's Web User Interface</h2>
8a1ba49… wyoung 328
6a2fee8… wyoung 329 After you create a new repository, you usually want to do some local
6a2fee8… wyoung 330 configuration. This is most easily accomplished by firing up the Fossil
6a2fee8… wyoung 331 UI:
8a1ba49… wyoung 332
8a1ba49… wyoung 333 <pre>
8a1ba49… wyoung 334 <b>fossil ui</b> <i>repository-filename</i>
8a1ba49… wyoung 335 </pre>
8a1ba49… wyoung 336
eb52410… wyoung 337 You can shorten that to just [/help/ui | <b>fossil ui</b>]
1fd407f… wyoung 338 if you are inside a checked-out local tree.
1fd407f… wyoung 339
6a2fee8… wyoung 340 This command starts an internal web server, after which Fossil
6a2fee8… wyoung 341 automatically launches your default browser, pointed at itself,
6a2fee8… wyoung 342 presenting a special view of the repository, its web user interface.
6a2fee8… wyoung 343
6a2fee8… wyoung 344 You may override Fossil's logic for selecting the default browser so:
8a1ba49… wyoung 345
8a1ba49… wyoung 346 <pre>
8a1ba49… wyoung 347 <b>fossil setting web-browser</b> <i>path-to-web-browser</i>
8a1ba49… wyoung 348 </pre>
8a1ba49… wyoung 349
6a2fee8… wyoung 350 When launched this way, Fossil binds its internal web server to the IP
6a2fee8… wyoung 351 loopback address, 127.0.0.1, which it treats specially, bypassing all
6a2fee8… wyoung 352 user controls, effectively giving visitors the
6a2fee8… wyoung 353 [./caps/admin-v-setup.md#apsu | all-powerful Setup capabliity].
6a2fee8… wyoung 354
6a2fee8… wyoung 355 Why is that a good idea, you ask? Because it is a safe
eb52410… wyoung 356 presumption that only someone with direct file access to the repository
eb52410… wyoung 357 database file could be using the resulting web interface. Anyone who can
eb52410… wyoung 358 modify the repo DB directly could give themselves any and all access
eb52410… wyoung 359 with a SQL query, or even by direct file manipulation; no amount of
eb52410… wyoung 360 access control matters to such a user.
eb52410… wyoung 361
e6c4176… wyoung 362 (Contrast the [#server | many <i>other</i> ways] of setting Fossil up
afb3db9… wyoung 363 as an HTTP server, where the repo DB is on the other side of the HTTP
afb3db9… wyoung 364 server wall, inaccessible by all means other than Fossil's own
afb3db9… wyoung 365 mediation. For this reason, the "localhost bypasses access control"
afb3db9… wyoung 366 policy does <i>not</i> apply to these other interfaces. That is a very
afb3db9… wyoung 367 good thing, since without this difference in policy, it would be unsafe
c64f28d… drh 368 to bind a [/help/server | <b>fossil server</b>] instance to
afb3db9… wyoung 369 localhost on a high-numbered port and then reverse-proxy it out to the
afb3db9… wyoung 370 world via HTTPS, a practice this author does engage in, with confidence.)
afb3db9… wyoung 371
eb52410… wyoung 372 Once you are finished configuring Fossil, you may safely Control-C out
eb52410… wyoung 373 of the <b>fossil&nbsp;ui</b> command to shut down this privileged
9c07d8a… wyoung 374 built-in web server. Moreover, you may by grace of SQLite do this <i>at
9c07d8a… wyoung 375 any time</i>: all changes are either committed durably to the repo DB or
9c07d8a… wyoung 376 rolled back, in their totality. This includes configuration changes.
8da7b15… wyoung 377
8da7b15… wyoung 378 <h2 id="sharing">Sharing Changes</h2>
8da7b15… wyoung 379
1fd407f… wyoung 380 When [./concepts.wiki#workflow|autosync] is turned off,
3ff0968… drh 381 the changes you [/help/commit | commit] are only
3ff0968… drh 382 on your local repository.
1fd407f… wyoung 383 To share those changes with other repositories, do:
3ff0968… drh 384
8a1ba49… wyoung 385 <pre>
3ff0968… drh 386 <b>[/help/push | fossil push]</b> <i>URL</i>
8a1ba49… wyoung 387 </pre>
3ff0968… drh 388
1fd407f… wyoung 389 Where <i>URL</i> is the http: URL of the server repository you
3ff0968… drh 390 want to share your changes with. If you omit the <i>URL</i> argument,
1fd407f… wyoung 391 fossil will use whatever server you most recently synced with.
3ff0968… drh 392
1fd407f… wyoung 393 The [/help/push | push] command only sends your changes to others. To
3ff0968… drh 394 Receive changes from others, use [/help/pull | pull]. Or go both ways at
1fd407f… wyoung 395 once using [/help/sync | sync]:
3ff0968… drh 396
8a1ba49… wyoung 397 <pre>
8a1ba49… wyoung 398 <b>[/help/pull | fossil pull]</b> <i>URL</i>
3ff0968… drh 399 <b>[/help/sync | fossil sync]</b> <i>URL</i>
8a1ba49… wyoung 400 </pre>
3ff0968… drh 401
1fd407f… wyoung 402 When you pull in changes from others, they go into your repository,
3ff0968… drh 403 not into your checked-out local tree. To get the changes into your
1fd407f… wyoung 404 local tree, use [/help/update | update]:
3ff0968… drh 405
8a1ba49… wyoung 406 <pre>
3ff0968… drh 407 <b>[/help/update | fossil update]</b> <i>VERSION</i>
8a1ba49… wyoung 408 </pre>
3ff0968… drh 409
1fd407f… wyoung 410 The <i>VERSION</i> can be the name of a branch or tag or any
3ff0968… drh 411 abbreviation to the 40-character
3ff0968… drh 412 artifact identifier for a particular check-in, or it can be a
3ff0968… drh 413 date/time stamp. ([./checkin_names.wiki | more info])
3ff0968… drh 414 If you omit
3ff0968… drh 415 the <i>VERSION</i>, then fossil moves you to the
a186d8b… drh 416 latest version of the branch you are currently on.
3ff0968… drh 417
1fd407f… wyoung 418 The default behavior is for [./concepts.wiki#workflow|autosync] to
3ff0968… drh 419 be turned on. That means that a [/help/pull|pull] automatically occurs
3ff0968… drh 420 when you run [/help/update|update] and a [/help/push|push] happens
3ff0968… drh 421 automatically after you [/help/commit|commit]. So in normal practice,
3ff0968… drh 422 the push, pull, and sync commands are rarely used. But it is important
1fd407f… wyoung 423 to know about them, all the same.
3ff0968… drh 424
8a1ba49… wyoung 425 <pre>
3ff0968… drh 426 <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i>
8a1ba49… wyoung 427 </pre>
3ff0968… drh 428
1fd407f… wyoung 429 Is similar to update except that it does not honor the autosync
3ff0968… drh 430 setting, nor does it merge in local changes - it prefers to overwrite
3ff0968… drh 431 them and fails if local changes exist unless the <tt>--force</tt>
1fd407f… wyoung 432 flag is used.
8da7b15… wyoung 433
8da7b15… wyoung 434 <h2 id="branch" name="merge">Branching And Merging</h2>
8da7b15… wyoung 435
f04b61f… wyoung 436 Use the --branch option to the [/help/commit | commit] command to start
f04b61f… wyoung 437 a new branch at the point of need. ([./gitusers.md#bneed | Contrast git].)
3ff0968… drh 438
3ff0968… drh 439 To merge two branches back together, first
3ff0968… drh 440 [/help/update | update] to the branch you want to merge into.
3ff0968… drh 441 Then do a [/help/merge|merge] of the other branch that you want to incorporate
3ff0968… drh 442 the changes from. For example, to merge "featureX" changes into "trunk"
1fd407f… wyoung 443 do this:
3ff0968… drh 444
8a1ba49… wyoung 445 <pre>
8a1ba49… wyoung 446 <b>fossil [/help/update|update] trunk</b>
8a1ba49… wyoung 447 <b>fossil [/help/merge|merge] featureX</b>
8a1ba49… wyoung 448 <i># make sure the merge didn't break anything...</i>
3ff0968… drh 449 <b>fossil [/help/commit|commit]
8a1ba49… wyoung 450 </pre>
3ff0968… drh 451
1fd407f… wyoung 452 The argument to the [/help/merge|merge] command can be any of the
3ff0968… drh 453 version identifier forms that work for [/help/update|update].
3ff0968… drh 454 ([./checkin_names.wiki|more info].)
3ff0968… drh 455 The merge command has options to cherry-pick individual
3ff0968… drh 456 changes, or to back out individual changes, if you don't want to
1fd407f… wyoung 457 do a full merge.
3ff0968… drh 458
3ff0968… drh 459 The merge command puts all changes in your working check-out.
3ff0968… drh 460 No changes are made to the repository.
3ff0968… drh 461 You must run [/help/commit|commit] separately
3ff0968… drh 462 to add the merge changes into your repository to make them persistent
3ff0968… drh 463 and so that your coworkers can see them.
3ff0968… drh 464 But before you do that, you will normally want to run a few tests
3ff0968… drh 465 to verify that the merge didn't cause logic breaks in your code.
3ff0968… drh 466
3ff0968… drh 467 The same branch can be merged multiple times without trouble. Fossil
3ff0968… drh 468 automatically keeps up with things and avoids conflicts when doing
3ff0968… drh 469 multiple merges. So even if you have merged the featureX branch
3ff0968… drh 470 into trunk previously, you can do so again and Fossil will automatically
3ff0968… drh 471 know to pull in only those changes that have occurred since the previous
3ff0968… drh 472 merge.
3ff0968… drh 473
1fd407f… wyoung 474 If a merge or update doesn't work out (perhaps something breaks or
1fd407f… wyoung 475 there are many merge conflicts) then you back up using:
3ff0968… drh 476
8a1ba49… wyoung 477 <pre>
3ff0968… drh 478 <b>[/help/undo | fossil undo]</b>
8a1ba49… wyoung 479 </pre>
3ff0968… drh 480
1fd407f… wyoung 481 This will back out the changes that the merge or update made to the
3ff0968… drh 482 working checkout. There is also a [/help/redo|redo] command if you undo by
3ff0968… drh 483 mistake. Undo and redo only work for changes that have
3ff0968… drh 484 not yet been checked in using commit and there is only a single
1fd407f… wyoung 485 level of undo/redo.
8da7b15… wyoung 486
8da7b15… wyoung 487
8da7b15… wyoung 488 <h2 id="server">Setting Up A Server</h2>
8da7b15… wyoung 489
6a2fee8… wyoung 490 In addition to the inward-facing <b>fossil ui</b> mode covered [#config
6a2fee8… wyoung 491 | above], Fossil can also act as an outward-facing web server:
8a1ba49… wyoung 492
8a1ba49… wyoung 493 <pre>
8a1ba49… wyoung 494 <b>[/help/server | fossil server]</b> <i>repository-filename</i>
8a1ba49… wyoung 495 </pre>
8a1ba49… wyoung 496
6a2fee8… wyoung 497 Just as with <b>fossil ui</b>, you may omit the
6a2fee8… wyoung 498 <i>repository-filename</i> parameter when running this from within an open
6a2fee8… wyoung 499 check-out.
6a2fee8… wyoung 500
6a2fee8… wyoung 501 <i>Unlike</i> <b>fossil ui</b> mode, Fossil binds to all network
6a2fee8… wyoung 502 interfaces by default in this mode, and it enforces the configured
6a2fee8… wyoung 503 [./caps/ | role-based access controls]. Further, because it is meant to
6a2fee8… wyoung 504 provide external web service, it doesn't try to launch a local web
6a2fee8… wyoung 505 browser pointing to a "Fossil UI" presentation; external visitors see
6a2fee8… wyoung 506 your repository's configured home page instead.
6a2fee8… wyoung 507
6a2fee8… wyoung 508 To serve varying needs, there are additional ways to serve a Fossil repo
6a2fee8… wyoung 509 to external users:
f17ab29… wyoung 510
3ff0968… drh 511 <ul>
6a2fee8… wyoung 512 <li>[./server/any/cgi.md|CGI], as used by Fossil's [./selfhost.wiki |
6a2fee8… wyoung 513 self-hosting repositories]
6a2fee8… wyoung 514 <li>[./server/any/scgi.md|SCGI]
3ff0968… drh 515 <li>[./server/any/inetd.md|inetd]
3ff0968… drh 516 <li>[./server/debian/service.md|systemd]
3ff0968… drh 517 </ul>
3ff0968… drh 518
1fd407f… wyoung 519 …along with [./server/#matrix | several other options].
1fd407f… wyoung 520
6a2fee8… wyoung 521 We recommend that you read the [./server/whyuseaserver.wiki | Benefits
6a2fee8… wyoung 522 of a Fossil Server] article, because you might <i>need</i> to do this
6a2fee8… wyoung 523 and not yet know it.
8da7b15… wyoung 524
8da7b15… wyoung 525 <h2 id="proxy">HTTP Proxies</h2>
8da7b15… wyoung 526
1fd407f… wyoung 527 If you are behind a restrictive firewall that requires you to use
3ff0968… drh 528 an HTTP proxy to reach the internet, then you can configure the proxy
3ff0968… drh 529 in three different ways. You can tell fossil about your proxy using
3ff0968… drh 530 a command-line option on commands that use the network,
1fd407f… wyoung 531 <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.
3ff0968… drh 532
8a1ba49… wyoung 533 <pre>
8a1ba49… wyoung 534 <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i>
8a1ba49… wyoung 535 </pre>
3ff0968… drh 536
1fd407f… wyoung 537 It is annoying to have to type in the proxy URL every time you
3ff0968… drh 538 sync your project, though, so you can make the proxy configuration
1fd407f… wyoung 539 persistent using the [/help/setting | setting] command:
3ff0968… drh 540
8a1ba49… wyoung 541 <pre>
3ff0968… drh 542 <b>fossil setting proxy </b><i>Proxy-URL</i>
8a1ba49… wyoung 543 </pre>
3ff0968… drh 544
1fd407f… wyoung 545 Or, you can set the "<b>http_proxy</b>" environment variable:
3ff0968… drh 546
8a1ba49… wyoung 547 <pre>
3ff0968… drh 548 <b>export http_proxy=</b><i>Proxy-URL</i>
8a1ba49… wyoung 549 </pre>
3ff0968… drh 550
1fd407f… wyoung 551 To stop using the proxy, do:
3ff0968… drh 552
8a1ba49… wyoung 553 <pre>
3ff0968… drh 554 <b>fossil setting proxy off</b>
8a1ba49… wyoung 555 </pre>
3ff0968… drh 556
1fd407f… wyoung 557 Or unset the environment variable. The fossil setting for the
3ff0968… drh 558 HTTP proxy takes precedence over the environment variable and the
e755561… danield 559 command-line option overrides both. If you have a persistent
3ff0968… drh 560 proxy setting that you want to override for a one-time sync, that
3ff0968… drh 561 is easily done on the command-line. For example, to sync with
1fd407f… wyoung 562 a co-worker's repository on your LAN, you might type:
3ff0968… drh 563
8a1ba49… wyoung 564 <pre>
3ff0968… drh 565 <b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
8a1ba49… wyoung 566 </pre>
8389757… drh 567
8389757… drh 568 <h2 id="links">Other Resources</h2>
8389757… drh 569
3ff0968… drh 570 <ul>
3ff0968… drh 571 <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a>
3ff0968… drh 572 <li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a>
3ff0968… drh 573 <li> <a href="./history.md">The History and Purpose of Fossil</a>
3ff0968… drh 574 <li> <a href="./branching.wiki">Branching, Forking, and Tagging</a>
3ff0968… drh 575 <li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a>
3ff0968… drh 576 <li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a>
3ff0968… drh 577 </ul>

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button