initial commitHEADmaster

1 files changed, 577 insertions, 0 deletions

diff --git a/www/quickstart.wiki b/www/quickstart.wiki
new file mode 100644
index 0000000..e75e939
--- /dev/null
+++ b/www/quickstart.wiki
@@ -0,0 +1,577 @@
+<title>Fossil Quick Start Guide</title>
+
+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
+and painlessly.
+
+<h2 id="install">Installing</h2>
+
+Fossil is a single self-contained C program.  You need to
+either download a
+[https://fossil-scm.org/home/uv/download.html|precompiled
+binary]
+or <a href="build.wiki">compile it yourself</a> from sources.
+Install Fossil by putting the fossil binary
+someplace on your $PATH.
+
+You can test that Fossil is present and working like this:
+
+<pre><b>fossil version
+This is fossil version 2.25 [8f798279d5] 2024-11-06 12:59:09 UTC
+</b></pre>
+
+<h2 id="workflow" name="fslclone">General Work Flow</h2>
+
+Fossil works with [./glossary.md#repository | repository files]
+and [./glossary.md#check-out | check-out directories] using a
+workflow like this:
+
+<ul>
+    <li>Create or clone a repository file.  ([/help/init|fossil init] or
+        [/help/clone | fossil clone])
+    <li>Check out a local tree.  ([/help/open | fossil open])
+    <li>Perform operations on the repository (including repository
+        configuration).
+</ul>
+
+Fossil can be entirely driven from the command line. Many features
+can also be conveniently accessed from the built-in web user interface.
+
+The following sections give a brief overview of these
+operations.
+
+<h2 id="new">Starting A New Project</h2>
+
+To start a new project with Fossil, [/help/init | create a new empty repository]:
+
+<pre><b>fossil init</b> <i>repository-filename</i>
+</pre>
+
+You can name the database anything you like, and you can place it anywhere in the filesystem.
+The <tt>.fossil</tt> extension is traditional, but it is only required if you are going to use the 
+<tt>[/help/server | fossil server DIRECTORY]</tt> feature.
+
+Next, do something along the lines of:
+
+<pre>
+<b>mkdir -p ~/src/project/trunk</b>
+<b>cd ~/src/project/trunk</b>
+<b>fossil open</b> <i>repository-filename</i>
+<b>fossil add</b> foo.c bar.h qux.md
+<b>fossil commit</b>
+</pre>
+
+If your project directory already exists, obviating the <b>mkdir</b>
+step, you will instead need to add the <tt>--force</tt> flag to the
+<b>open</b> command to authorize Fossil to open the repo into a
+non-empty checkout directory. (This is to avoid accidental opens into,
+for example, your home directory.)
+
+The convention of naming your checkout directory after a long-lived
+branch name like "trunk" is in support of Fossil's ability to have as
+many open checkouts as you like. This author frequently has additional
+checkout directories named <tt>../release</tt>, <tt>../scratch</tt>,
+etc. The release directory is open to the branch of the same name, while
+the scratch directory is used when disturbing one of the other
+long-lived checkout directories is undesireable, as when performing a
+[/help/bisect | bisect] operation.
+
+
+<h2 id="clone">Cloning An Existing Repository</h2>
+
+Most fossil operations interact with a repository that is on the
+local disk drive, not on a remote system.  Hence, before accessing
+a remote repository it is necessary to make a local copy of that
+repository, a process called
+"[/help/clone | cloning]".
+
+This is done as follows:
+
+<pre><b>fossil clone</b> <i>URL repository-filename</i>
+</pre>
+
+The <i>URL</i> specifies the fossil repository
+you want to clone.  The <i>repository-filename</i> is the new local
+filename into which the cloned repository will be written.  For
+example, to clone the source code of Fossil itself:
+
+<pre><b>fossil clone https://fossil-scm.org/ myclone.fossil</b></pre>
+
+If your logged-in username is 'exampleuser', you should see output something like this:
+
+<pre><b>Round-trips: 8   Artifacts sent: 0  received: 39421
+Clone done, sent: 2424  received: 42965725  ip: 10.10.10.0
+Rebuilding repository meta-data...
+100% complete...
+Extra delta compression... 
+Vacuuming the database... 
+project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333
+server-id:  016595e9043054038a9ea9bc526d7f33f7ac0e42
+admin-user: exampleuser (intial remote-access password is "yoWgDR42iv")>
+</b></pre>
+
+This <i>exampleuser</i> will be used by Fossil as the author of commits when
+you checkin changes to the repository.  It is also used by Fossil when you
+make your repository available to others using the built-in server mode by
+running <tt>[/help/server | fossil server]</tt> and will also be used when
+running <tt>[/help/ui | fossil ui]</tt> to view the repository through 
+the Fossil UI.  See the quick start topic for setting up a
+<a href="#server">server</a> for more details.
+
+If the remote repository requires a login, include a
+userid in the URL like this:
+
+<pre><b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b></pre>
+
+You will be prompted separately for the password.
+Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid.
+For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget")
+
+If you are behind a restrictive firewall, you might need
+to <a href="#proxy">specify an HTTP proxy</a>.
+
+A Fossil repository is a single disk file.  Instead of cloning,
+you can just make a copy of the repository file (for example, using
+"scp").  Note, however, that the repository file contains auxiliary
+information above and beyond the versioned files, including some
+sensitive information such as password hashes and email addresses.  If you
+want to share Fossil repositories directly by copying, consider running the
+[/help/scrub|fossil scrub] command to remove sensitive information
+before transmitting the file.
+
+<h2 id="import">Importing From Another Version Control System</h2>
+
+Rather than start a new project, or clone an existing Fossil project,
+you might prefer to
+<a href="./inout.wiki">import an existing Git project</a>
+into Fossil using the [/help/import | fossil import] command. 
+
+You can even decide to export your project back into git using the
+[/help/git | fossil git] command, which is how the Fossil project maintains
+[https://github.com/drhsqlite/fossil-mirror | its public GitHub mirror]. There
+is no limit to the number of times a tree can be imported and exported between
+Fossil and git.
+
+The [https://git-scm.com/docs/git-fast-export|Git fast-export format] has become
+a popular way to move files between version management systems, including from
+[https://www.mercurial-scm.org/|Mercurial].
+Fossil can also import [https://subversion.apache.org/|Subversion projects] directly.
+
+<h2 id="checkout">Checking Out A Local Tree</h2>
+
+To work on a project in fossil, you need to check out a local
+copy of the source tree.  Create the directory you want to be
+the root of your tree, <tt>cd</tt> into that directory, and then:
+
+<pre><b>fossil open</b> <i>repository-filename</i></pre>
+
+For example:
+
+<pre><b>fossil open ../myclone.fossil
+    BUILD.txt
+    COPYRIGHT-BSD2.txt
+    README.md
+      ︙
+</tt></b></pre>
+
+This leaves you with the newest version of the tree
+checked out.
+From anywhere underneath the root of your local tree, you
+can type commands like the following to find out the status of
+your local tree:
+
+<pre>
+<b>[/help/info | fossil info]</b>
+<b>[/help/status | fossil status]</b>
+<b>[/help/changes | fossil changes]</b>
+<b>[/help/diff | fossil diff]</b>
+<b>[/help/timeline | fossil timeline]</b>
+<b>[/help/ls | fossil ls]</b>
+<b>[/help/branch | fossil branch]</b>
+</pre>
+
+If you created a new repository using "fossil init" some commands will not
+produce much output.
+
+Note that Fossil allows you to make multiple check-outs in
+separate directories from the same repository.  This enables you,
+for example, to do builds from multiple branches or versions at
+the same time without having to generate extra clones.
+
+To switch a checkout between different versions and branches,
+use:
+
+<pre>
+<b>[/help/update | fossil update]</b>
+<b>[/help/checkout | fossil checkout]</b>
+</pre>
+
+[/help/update | update] honors the "autosync" option and
+does a "soft" switch, merging any local changes into the target
+version, whereas [/help/checkout | checkout] does not
+automatically sync and does a "hard" switch, overwriting local
+changes if told to do so.
+
+<h2 id="changes">Making and Committing Changes</h2>
+
+To add new files to your project or remove existing ones, use these
+commands:
+
+<pre>
+<b>[/help/add | fossil add]</b> <i>file...</i>
+<b>[/help/rm | fossil rm]</b> <i>file...</i>
+<b>[/help/addremove | fossil addremove]</b> <i>file...</i>
+</pre>
+
+The command:
+
+<pre><b>[/help/changes | fossil changes]</b></pre>
+
+lists files that have changed since the last commit to the repository. For
+example, if you edit the file "README.md":
+
+<pre><b>fossil changes
+EDITED     README.md
+</b></pre>
+
+To see exactly what change was made you can use the command
+<b>[/help/diff | fossil diff]</b>:
+
+<pre><b>fossil diff
+Index: README.md
+============================================================
+--- README.md
++++ README.md
+@@ -1,5 +1,6 @@
++Made some changes to the project
+# Original text
+</b></pre>
+
+"fossil diff" shows the difference between your tree on disk now and as
+the tree was when you last committed changes. If you haven't committed
+yet, then it shows the difference relative to the tip-of-trunk commit in
+the repository, being what you get when you "fossil open" a repository
+without specifying a version, populating the working directory.
+
+To see the most recent changes made to the repository by other users, use "fossil timeline" to
+find out the most recent commit, and then "fossil diff" between that commit and the
+current tree:
+
+<pre><b><verbatim>fossil timeline
+=== 2021-03-28 ===
+03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) 
+=== 2021-03-27 === 
+23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) 
+     ⋮ 
+
+fossil diff --from current --to ab975c6632
+Index: frobnicate.c
+============================================================
+--- frobnicate.c
++++ frobnicate.c
+@@ -1,10 +1,11 @@
++/* made a change to the source file */
+# Original text
+</verbatim></b></pre>
+
+"current" is an alias for the checkout version, so the command
+"fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results.
+
+To commit your changes to a local-only repository:
+
+<pre><b>fossil commit</b>     <i>(... Fossil will start your editor, if defined)</i><b>
+# Enter a commit message for this check-in. Lines beginning with # are ignored.
+#
+# user: exampleuser
+# tags: trunk
+#
+# EDITED     README.md
+Edited file to add description of code changes
+New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab
+</b></pre>
+
+You will be prompted for check-in comments using whatever editor
+is specified by your VISUAL or EDITOR environment variable. If none is
+specified Fossil uses line-editing in the terminal.
+
+To commit your changes to a repository that was cloned from a remote
+repository, you give the same command, but the results are different.
+Fossil defaults to [./concepts.wiki#workflow|autosync] mode, a
+single-stage commit that sends all changes committed to the local
+repository immediately on to the remote parent repository. This only
+works if you have write permission to the remote repository.
+
+<h2 id="naming">Naming of Files, Checkins, and Branches</h2>
+
+Fossil deals with information artifacts. This Quickstart document only deals
+with files and collections of files, but be aware there are also tickets, wiki pages and more. 
+Every artifact in Fossil has a universally-unique hash id, and may also have a
+human-readable name.
+
+The following are all equivalent ways of identifying a Fossil file,
+checkin or branch artifact:
+
+<ul>
+<li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a
+<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
+<li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash
+</ul>
+
+A special convenience branch is "trunk", which is Fossil's default branch name for
+the first checkin, and the default for any time a branch name is needed but not
+specified.
+
+This will get you started on identifying checkins. The
+<a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including
+how timestamps can also be used.
+
+<h2 id="config">Accessing Your Local Repository's Web User Interface</h2>
+
+After you create a new repository, you usually want to do some local
+configuration.  This is most easily accomplished by firing up the Fossil
+UI:
+
+<pre>
+<b>fossil ui</b> <i>repository-filename</i>
+</pre>
+
+You can shorten that to just [/help/ui | <b>fossil ui</b>]
+if you are inside a checked-out local tree.
+
+This command starts an internal web server, after which Fossil
+automatically launches your default browser, pointed at itself,
+presenting a special view of the repository, its web user interface.
+
+You may override Fossil's logic for selecting the default browser so:
+
+<pre>
+<b>fossil setting web-browser</b> <i>path-to-web-browser</i>
+</pre>
+
+When launched this way, Fossil binds its internal web server to the IP
+loopback address, 127.0.0.1, which it treats specially, bypassing all
+user controls, effectively giving visitors the
+[./caps/admin-v-setup.md#apsu | all-powerful Setup capabliity].
+
+Why is that a good idea, you ask? Because it is a safe
+presumption that only someone with direct file access to the repository
+database file could be using the resulting web interface. Anyone who can
+modify the repo DB directly could give themselves any and all access
+with a SQL query, or even by direct file manipulation; no amount of
+access control matters to such a user.
+
+(Contrast the [#server | many <i>other</i> ways] of setting Fossil up
+as an HTTP server, where the repo DB is on the other side of the HTTP
+server wall, inaccessible by all means other than Fossil's own
+mediation. For this reason, the "localhost bypasses access control"
+policy does <i>not</i> apply to these other interfaces. That is a very
+good thing, since without this difference in policy, it would be unsafe
+to bind a [/help/server | <b>fossil server</b>] instance to
+localhost on a high-numbered port and then reverse-proxy it out to the
+world via HTTPS, a practice this author does engage in, with confidence.)
+
+Once you are finished configuring Fossil, you may safely Control-C out
+of the <b>fossil&nbsp;ui</b> command to shut down this privileged
+built-in web server. Moreover, you may by grace of SQLite do this <i>at
+any time</i>: all changes are either committed durably to the repo DB or
+rolled back, in their totality. This includes configuration changes.
+
+<h2 id="sharing">Sharing Changes</h2>
+
+When [./concepts.wiki#workflow|autosync] is turned off,
+the changes you [/help/commit | commit] are only
+on your local repository.
+To share those changes with other repositories, do:
+
+<pre>
+<b>[/help/push | fossil push]</b> <i>URL</i>
+</pre>
+
+Where <i>URL</i> is the http: URL of the server repository you
+want to share your changes with.  If you omit the <i>URL</i> argument,
+fossil will use whatever server you most recently synced with.
+
+The [/help/push | push] command only sends your changes to others.  To
+Receive changes from others, use [/help/pull | pull].  Or go both ways at
+once using [/help/sync | sync]:
+
+<pre>
+<b>[/help/pull | fossil pull]</b> <i>URL</i>
+<b>[/help/sync | fossil sync]</b> <i>URL</i>
+</pre>
+
+When you pull in changes from others, they go into your repository,
+not into your checked-out local tree.  To get the changes into your
+local tree, use [/help/update | update]:
+
+<pre>
+<b>[/help/update | fossil update]</b> <i>VERSION</i>
+</pre>
+
+The <i>VERSION</i> can be the name of a branch or tag or any
+abbreviation to the 40-character
+artifact identifier for a particular check-in, or it can be a
+date/time stamp.  ([./checkin_names.wiki | more info])
+If you omit
+the <i>VERSION</i>, then fossil moves you to the
+latest version of the branch you are currently on.
+
+The default behavior is for [./concepts.wiki#workflow|autosync] to
+be turned on.  That means that a [/help/pull|pull] automatically occurs
+when you run [/help/update|update] and a [/help/push|push] happens
+automatically after you [/help/commit|commit].  So in normal practice,
+the push, pull, and sync commands are rarely used.  But it is important
+to know about them, all the same.
+
+<pre>
+<b>[/help/checkout | fossil checkout]</b> <i>VERSION</i>
+</pre>
+
+Is similar to update except that it does not honor the autosync
+setting, nor does it merge in local changes - it prefers to overwrite
+them and fails if local changes exist unless the <tt>--force</tt>
+flag is used.
+
+<h2 id="branch" name="merge">Branching And Merging</h2>
+
+Use the --branch option to the [/help/commit | commit] command to start
+a new branch at the point of need. ([./gitusers.md#bneed | Contrast git].)
+
+To merge two branches back together, first
+[/help/update | update] to the branch you want to merge into.
+Then do a [/help/merge|merge] of the other branch that you want to incorporate
+the changes from.  For example, to merge "featureX" changes into "trunk"
+do this:
+
+<pre>
+<b>fossil [/help/update|update] trunk</b>
+<b>fossil [/help/merge|merge] featureX</b>
+<i># make sure the merge didn't break anything...</i>
+<b>fossil [/help/commit|commit]
+</pre>
+
+The argument to the [/help/merge|merge] command can be any of the
+version identifier forms that work for [/help/update|update].
+([./checkin_names.wiki|more info].)
+The merge command has options to cherry-pick individual
+changes, or to back out individual changes, if you don't want to
+do a full merge.
+
+The merge command puts all changes in your working check-out.
+No changes are made to the repository.
+You must run [/help/commit|commit] separately
+to add the merge changes into your repository to make them persistent
+and so that your coworkers can see them.
+But before you do that, you will normally want to run a few tests
+to verify that the merge didn't cause logic breaks in your code.
+
+The same branch can be merged multiple times without trouble. Fossil
+automatically keeps up with things and avoids conflicts when doing
+multiple merges.  So even if you have merged the featureX branch
+into trunk previously, you can do so again and Fossil will automatically
+know to pull in only those changes that have occurred since the previous
+merge.
+
+If a merge or update doesn't work out (perhaps something breaks or
+there are many merge conflicts) then you back up using:
+
+<pre>
+<b>[/help/undo | fossil undo]</b>
+</pre>
+
+This will back out the changes that the merge or update made to the
+working checkout.  There is also a [/help/redo|redo] command if you undo by
+mistake.  Undo and redo only work for changes that have
+not yet been checked in using commit and there is only a single
+level of undo/redo.
+
+
+<h2 id="server">Setting Up A Server</h2>
+
+In addition to the inward-facing <b>fossil ui</b> mode covered [#config
+| above], Fossil can also act as an outward-facing web server:
+
+<pre>
+<b>[/help/server | fossil server]</b> <i>repository-filename</i>
+</pre>
+
+Just as with <b>fossil ui</b>, you may omit the
+<i>repository-filename</i> parameter when running this from within an open
+check-out.
+
+<i>Unlike</i> <b>fossil ui</b> mode, Fossil binds to all network
+interfaces by default in this mode, and it enforces the configured
+[./caps/ | role-based access controls]. Further, because it is meant to
+provide external web service, it doesn't try to launch a local web
+browser pointing to a "Fossil UI" presentation; external visitors see
+your repository's configured home page instead.
+
+To serve varying needs, there are additional ways to serve a Fossil repo
+to external users:
+
+<ul>
+<li>[./server/any/cgi.md|CGI], as used by Fossil's [./selfhost.wiki |
+    self-hosting repositories]
+<li>[./server/any/scgi.md|SCGI]
+<li>[./server/any/inetd.md|inetd]
+<li>[./server/debian/service.md|systemd]
+</ul>
+
+…along with [./server/#matrix | several other options].
+
+We recommend that you read the [./server/whyuseaserver.wiki | Benefits
+of a Fossil Server] article, because you might <i>need</i> to do this
+and not yet know it.
+
+<h2 id="proxy">HTTP Proxies</h2>
+
+If you are behind a restrictive firewall that requires you to use
+an HTTP proxy to reach the internet, then you can configure the proxy
+in three different ways.  You can tell fossil about your proxy using
+a command-line option on commands that use the network,
+<b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.
+
+<pre>
+<b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i>
+</pre>
+
+It is annoying to have to type in the proxy URL every time you
+sync your project, though, so you can make the proxy configuration
+persistent using the [/help/setting | setting] command:
+
+<pre>
+<b>fossil setting proxy </b><i>Proxy-URL</i>
+</pre>
+
+Or, you can set the "<b>http_proxy</b>" environment variable:
+
+<pre>
+<b>export http_proxy=</b><i>Proxy-URL</i>
+</pre>
+
+To stop using the proxy, do:
+
+<pre>
+<b>fossil setting proxy off</b>
+</pre>
+
+Or unset the environment variable.  The fossil setting for the
+HTTP proxy takes precedence over the environment variable and the
+command-line option overrides both.  If you have a persistent
+proxy setting that you want to override for a one-time sync, that
+is easily done on the command-line.  For example, to sync with
+a co-worker's repository on your LAN, you might type:
+
+<pre>
+<b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
+</pre>
+
+<h2 id="links">Other Resources</h2>
+
+<ul>
+<li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a>
+<li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a>
+<li> <a href="./history.md">The History and Purpose of Fossil</a>
+<li> <a href="./branching.wiki">Branching, Forking, and Tagging</a>
+<li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a>
+<li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a>
+</ul>