Fossil

Check-in [bc857ecd]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Doc update for branch and co.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:bc857ecd923b8a6ff5951d7d5ad21d6988974fa5
User & Date: kejoki 2009-02-13 20:30:30
Context
2009-02-21
13:09
Documentation tweaks. No changes to code. check-in: 6ba52ae7 user: drh tags: trunk
2009-02-13
20:30
Doc update for branch and co. check-in: bc857ecd user: kejoki tags: trunk
2009-02-11
05:00
Make command-alias for 'checkout': co. This command could -not- have been used previously as a shortcut, as it would be ambiguous becuase of 'commit' and 'configuration'. A natural mate for 'ci'. check-in: a89b436b user: bharder tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/concepts.wiki.

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
manifest also contains a check-in comment, the date and time
when the check-in was established, who created the check-in,
and links to other check-ins from which the current check-in
is derived.  There is also a couple of checksums used to verify
the integrity of the check-in.  And the whole manifest might
be PGP clearsigned.</p>

<h3>2.3 Key concepts</h3>

<ul>
<li>A <b>check-in</b> is a set of files arranged
    in a hierarchy.</li>
<li>A <b>repository</b> keeps a record of historical check-ins.</li>
<li>Repositories share their changes using <b>push</b>, <b>pull</b>,
    <b>sync</b>, and <b>clone</b>.</li>
<li>A particular version of a particular file is an <b>artifact</b>
    that is identified by an <b>artifact ID</b>.</li>
<li>Artifacts tracked by fossil are inherently immutable.</li>
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a check-in.</li>
<li>The artifact ID of the manifest is the identifier of the check-in.</li>
</ul>








|







|







146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
manifest also contains a check-in comment, the date and time
when the check-in was established, who created the check-in,
and links to other check-ins from which the current check-in
is derived.  There is also a couple of checksums used to verify
the integrity of the check-in.  And the whole manifest might
be PGP clearsigned.</p>

<h3><a name="keyconc">2.3</a> Key concepts</h3>

<ul>
<li>A <b>check-in</b> is a set of files arranged
    in a hierarchy.</li>
<li>A <b>repository</b> keeps a record of historical check-ins.</li>
<li>Repositories share their changes using <b>push</b>, <b>pull</b>,
    <b>sync</b>, and <b>clone</b>.</li>
<li>A particular <u>version</u> of a particular file is an <b>artifact</b>
    that is identified by an <b>artifact ID</b>.</li>
<li>Artifacts tracked by fossil are inherently immutable.</li>
<li>Fossil automatically generates a <b>manifest</b> file that identifies
    every artifact in a check-in.</li>
<li>The artifact ID of the manifest is the identifier of the check-in.</li>
</ul>

Changes to www/quickstart.wiki.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    either download a 
    <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
    or <a href="build.wiki">build it yourself</a> from sources.
    Install fossil by putting the fossil binary
    someplace on your PATH environment variable.</p>
    
    </blockquote>
    <h2>Cloning A Existing Repository</h2>
    <blockquote>

    <p>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.  Making a local copy of a remote repository is called
    "cloning".</p>







|







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    either download a 
    <a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
    or <a href="build.wiki">build it yourself</a> from sources.
    Install fossil by putting the fossil binary
    someplace on your PATH environment variable.</p>
    
    </blockquote>
    <a name="#fslclone"><h2>Cloning An Existing Repository</h2></a>
    <blockquote>

    <p>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.  Making a local copy of a remote repository is called
    "cloning".</p>

Changes to www/reference.wiki.

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38












39
40
41
42
43
44
45
46
47
48














49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
...
142
143
144
145
146
147
148















149
150
151
152
153
154
155

  * Any fossil command is acceptable once enough of it has been
  entered to make the intent unambiguous.  'clo' is a proper prefix of
  both the 'clone' and 'close' commands, for instance, but 'clon' is
  enough to make the intent&#8212;the 'clone'
  command&#8212;unambiguous.

  * Pragmatically, a [ | <u>version</u>] in <b>fossil</b> is a
  40-character long string of hexadecimal.  <b>fossil</b> will be
  able to figure out which version you want with any
  <i>distinct</i> prefix of that string which is at least four
  characters long.  <em>Commands which require a version are
  looking for the string, a distinct prefix of the string, or a
  <code>tag</code>.</em>

  * SCM in a distributed environment can be a bit confusing with
  regard to branching, merging, and versions in general.  See the
  [./branching.wiki | explanation of branching] and it will all make
  much more sense.













  You should probably start interacting with fossil at the command
  line by asking it what it can
  do:&nbsp;&nbsp;&nbsp;&nbsp;<a name="tof">&#710;</a>

  <code>$ fossil help</code><nowiki><pre>
Usage: fossil help COMMAND.
Available COMMANDs:</pre><table width="80%"
                          style="font-family: fixed, courier, monospace;">
      <tr>
	<td><a href="#add">add</a>*</td>














	<td><a href="#configuration">configuration</a></td>
	<td><a href="#leaves">leaves</a></td>
	<td><a href="#redo">redo</a></td>
	<td><a href="#timeline">timeline</a></td>
      </tr>
      <tr>
	<td><a href="#all">all</a>*</td>
	<td><a href="#deconstruct">deconstruct</a></td>
	<td><a href="#ls">ls</a>*</td>
	<td><a href="#mv">rename</a>*</td>
	<td><a href="#server">ui</a></td>
      </tr>
      <tr>
	<td><a href="#cgi">cgi</a>*</td>
	<td><a href="#rm">del</a>*</td>
	<td><a href="#merge">merge</a></td>
	<td><a href="#revert">revert</a></td>
	<td><a href="#undo">undo</a></td>
      </tr>
      <tr>
	<td><a href="#changes">changes</a>*</td>
        <td><a href="#descendants">descendants</a></td>
	<td><a href="#mv">mv</a>*</td>
	<td><a href="#rm">rm</a>*</td>
	<td><a href="#setting">unset</a></td>
      </tr>
      <tr>
	<td><a href="#checkout">checkout</a>*</td>
	<td><a href="#diff">diff</a></td>
	<td><a href="#new">new</a>*</td>
	<td><a href="#rstats">rstats</a></td>
	<td><a href="#update">update</a>*</td>
      </tr>
      <tr>
	<td><a href="#commit">ci</a></td>
	<td><a href="#extra">extra</a>*</td>
	<td><a href="#open">open</a></td>
	<td><a href="#server">server</a></td>
	<td><a href="#user">user</a></td>
      </tr>
      <tr>
	<td><a href="#clean">clean</a></td>
	<td><a href="#diff">gdiff</a></td>
	<td><a href="#pull">pull</a></td>
	<td><a href="#setting">settings</a></td>
	<td><a href="#version">version</a>*</td>
      </tr>
      <tr>
	<td><a href="#clone">clone</a></td>
	<td><a href="#help">help</a></td>
	<td><a href="#push">push</a></td>
	<td><a href="#status">status</a>*</td>
	<td><a href="#wiki">wiki</a></td>
      </tr>
      <tr>
	<td><a href="#close">close</a></td>
	<td><a href="#http">http</a></td>
	<td><a href="#rebuild">rebuild</a></td>
	<td><a href="#sync">sync</a>*</td>
      </tr>
      <tr>
	<td><a href="#commit">commit</a></td>
	<td><a href="#info">info</a></td>
	<td><a href="#reconstruct">reconstruct</a></td>
        <td><a href="#tag">tag</a></td>
      </tr>
    </table><nowiki><pre>
This is fossil version [b12a031557] 2008-12-26 17:41:09 UTC
</pre>
<b>What follows</b> is a survey of what you get if you type<code>
fossil&nbsp;help&nbsp;<i>command</i> </code>for all of the
commands listed above.  There are links to individual pages for each
of them; pages with content (commands marked with a '*' are done) go
into the reason for a command in a bit more depth than the program help.
<pre>
................................................................................
    rebuild    Rebuild on all repositories

    sync       Run a "sync" on all repositories

    Respositories are automatically added to the set of known repositories
    when one of the following commands against the repository: clone, info,
    pull, push, or sync
















<hr><a href="#tof">&#710;</a>
    <a name="cgi">Usage: </a><a href="cmd_cgi.wiki">fossil cgi</a> SCRIPT
    The SCRIPT argument is the name of a file that is the CGI script
    that is being run.  The command name, "cgi", may be omitted if
    the GATEWAY_INTERFACE environment variable is set to "CGI" (which
    should always be the case for CGI scripts run by a webserver.)  The







|
|
|
|
|
|
|






>
>
>
>
>
>
>
>
>
>
>
>
|







|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<
<
<
<
<
<
<
<
<
<
<
<
|
|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128












129
130
131
132
133
134
135
136
137
...
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184

  * Any fossil command is acceptable once enough of it has been
  entered to make the intent unambiguous.  'clo' is a proper prefix of
  both the 'clone' and 'close' commands, for instance, but 'clon' is
  enough to make the intent&#8212;the 'clone'
  command&#8212;unambiguous.

  * Pragmatically, a [./concepts.wiki#keyconc | <u>version</u>]
  in <b>fossil</b> is a 40-character long string of hexadecimal.
  <b>fossil</b> will be able to figure out which version you want
  with any <i>distinct</i> prefix of that string which is at
  least four characters long.  <em>Commands which require a
  version are looking for the string, a distinct prefix of the
  string, or a <code>tag</code>.</em>

  * SCM in a distributed environment can be a bit confusing with
  regard to branching, merging, and versions in general.  See the
  [./branching.wiki | explanation of branching] and it will all make
  much more sense.

  * <i>Op.Ed.</i> An excellent way to learn to use <b>fossil</b>
    effectively is to
    [./quickstart.wiki#fslclone | clone the repository for fossil]
    itself.  You can then poke around using the <code>fossil ui</code>
    command, and look things up with no connection worries.  You can
    set up test repositories and try things out on-the-fly to see how
    they work, using their own ui's.  The CLI will far easier to
    understand if you can run a repository, watch it in a browser, and
    hack around with it in a simplified environment (your tests) with
    guaranteed and fast access to the sources & docs (your cloned fossil
    repository).
<br /><br /> <br />
  <b>You should</b> probably start interacting with fossil at the command
  line by asking it what it can
  do:&nbsp;&nbsp;&nbsp;&nbsp;<a name="tof">&#710;</a>

  <code>$ fossil help</code><nowiki><pre>
Usage: fossil help COMMAND.
Available COMMANDs:</pre><table width="80%"
                          style="font-family: fixed, courier, monospace;">
  <tr>
    <td><a href="#add">add</a>*</td>
    <td><a href="#checkout">co</a>*</td>
    <td><a href="#http">http</a></td>
    <td><a href="#rebuild">rebuild</a></td>
    <td><a href="#sync">sync</a>*</td>
  </tr>
  <tr>
    <td><a href="#all">all</a>*</td>
    <td><a href="#commit">commit</a></td>
    <td><a href="#info">info</a></td>
    <td><a href="#reconstruct">reconstruct</a></td>
    <td><a href="#tag">tag</a></td>
  </tr>
  <tr>
    <td><a href="#branch">branch</a></td>
    <td><a href="#configuration">configuration</a></td>
    <td><a href="#leaves">leaves</a></td>
    <td><a href="#redo">redo</a></td>
    <td><a href="#timeline">timeline</a></td>
  </tr>
  <tr>
    <td><a href="#cgi">cgi</a>*</td>
    <td><a href="#deconstruct">deconstruct</a></td>
    <td><a href="#ls">ls</a>*</td>
    <td><a href="#mv">rename</a>*</td>
    <td><a href="#server">ui</a></td>
  </tr>
  <tr>
    <td><a href="#changes">changes</a>*</td>
    <td><a href="#rm">del</a>*</td>
    <td><a href="#merge">merge</a></td>
    <td><a href="#revert">revert</a></td>
    <td><a href="#undo">undo</a></td>
  </tr>
  <tr>
    <td><a href="#checkout">checkout</a>*</td>
    <td><a href="#descendants">descendants</a></td>
    <td><a href="#mv">mv</a>*</td>
    <td><a href="#rm">rm</a>*</td>
    <td><a href="#setting">unset</a></td>
  </tr>
  <tr>
    <td><a href="#commit">ci</a></td>
    <td><a href="#diff">diff</a></td>
    <td><a href="#new">new</a>*</td>
    <td><a href="#rstats">rstats</a></td>
    <td><a href="#update">update</a>*</td>
  </tr>
  <tr>
    <td><a href="#clean">clean</a></td>
    <td><a href="#extra">extra</a>*</td>
    <td><a href="#open">open</a></td>
    <td><a href="#server">server</a></td>
    <td><a href="#user">user</a></td>
  </tr>
  <tr>
    <td><a href="#clone">clone</a></td>
    <td><a href="#diff">gdiff</a></td>
    <td><a href="#pull">pull</a></td>
    <td><a href="#setting">settings</a></td>
    <td><a href="#version">version</a>*</td>
  </tr>
  <tr>
    <td><a href="#close">close</a></td>
    <td><a href="#help">help</a></td>
    <td><a href="#push">push</a></td>
    <td><a href="#status">status</a>*</td>
    <td><a href="#wiki">wiki</a></td>
  </tr>












</table><nowiki><pre>
This is fossil version [a89b436bc9] 2009-02-11 05:00:02 UTC
</pre>
<b>What follows</b> is a survey of what you get if you type<code>
fossil&nbsp;help&nbsp;<i>command</i> </code>for all of the
commands listed above.  There are links to individual pages for each
of them; pages with content (commands marked with a '*' are done) go
into the reason for a command in a bit more depth than the program help.
<pre>
................................................................................
    rebuild    Rebuild on all repositories

    sync       Run a "sync" on all repositories

    Respositories are automatically added to the set of known repositories
    when one of the following commands against the repository: clone, info,
    pull, push, or sync

<hr><a href="#tof">&#710;</a>
    <a name="branch">Usage: </a><code><a href="cmd_branch.wiki">fossil branch</a></code> SUBCOMMAND ... ?-R|--repository FILE?

Run various subcommands on the branches of the open repository or
of the repository identified by the -R or --repository option.

   fossil branch new BRANCH-NAME BASIS ?-bgcolor COLOR?

       Create a new branch BRANCH-NAME off of check-in BASIS.
       You can optionally give the branch a default color.

   fossil branch list

       List all branches

<hr><a href="#tof">&#710;</a>
    <a name="cgi">Usage: </a><a href="cmd_cgi.wiki">fossil cgi</a> SCRIPT
    The SCRIPT argument is the name of a file that is the CGI script
    that is being run.  The command name, "cgi", may be omitted if
    the GATEWAY_INTERFACE environment variable is set to "CGI" (which
    should always be the case for CGI scripts run by a webserver.)  The