1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
+
+
|
<h1>The f-tools</h1>
The source tree contains a few test/demo apps which are named <tt>f-something</tt> (the "f" is for "fossil", of course).
* <tt>[/finfo?name=f-acat.c|f-acat]</tt> ("artifact cat") can output arbitrary artifacts from a repository.
* <tt>[/finfo?name=f-ls.c|f-ls]</tt> lists files from a repository.
* <tt>[/finfo?name=f-mfparse.c|f-mfparse]</tt> reads in Fossil control artifacts, converts them to its internal high-level form, and saves them back out to a file. This is used for testing both the manifest parsing and generation code, to test round-trip fidelity and compatibility with fossil(1) manifests.
* <tt>[/finfo?name=f-new.c|f-new]</tt> creates new/empty repository databases.
* <tt>[/finfo?name=f-resolve.c|f-resolve]</tt> resolves symbolic checkin names (like "trunk", "current", and "prev") and partial UUIDs to their full UUIDs and RIDs.
* <tt>[/finfo?name=f-tag.c|f-tag]</tt> can add tags to artifacts.
* <tt>[/finfo?name=f-timeline.c|f-timeline]</tt> provides a simple timeline
* <tt>[/finfo?name=f-wiki.c|f-wiki]</tt> hopes to one day be a generic wiki manipulation tool.
All of these applications accept <tt>-?</tt>, <tt>--help</tt>, or a first non-flag argument of <tt>help</tt> to show their help text.
These applications provide demonstrations of using the library and give devs a place to test new features. <tt>[FossilApp]</tt> provides a mini-framework which takes care of bootstrapping fossil for these applications, making it pretty simple to create new ones. FossilApp handles the CLI parsing, global flags, opening of a repo/checkout, and other "getting started" bits. If you've ever hacked on fossil(1), adding a new f-* app is very similar to adding a new command to fossil, with only a few more lines of bootstrap code (because each "command" is in its own app to simplify testing).
<h2>Demos</h2>
<nowiki><pre>
# f-wiki ls
|
116
117
118
119
120
121
122
|
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|
</pre></nowiki>
Values are always optional but Fossil internally treats some tag names specially and may require (or expect) a value. The <tt>bgcolor</tt> tag is one example. When cancelling a tag, the value is always optional, regardless of whether or not it is a special tag.
When adding a tag, the tag name may optionally be prefixed with a <tt>+</tt> sign, for symmetry with the cancel (<tt>-</tt>) and propagate (<tt>*</tt>) markers. Cancel tags might <em>look</em> like options/flags because they start with a minus, but they are not interpreted as a flag due to a happy accident of design. When using propagating tags, it is wise to enclose the tag in quotes to prevent any unwanted side-effects of shell globbing. Optionally, use <tt>-t=*tagname</tt>, which would only match a glob in the most unusual of circumstances. Likewise, <tt>-t=-tag-to-cancel</tt> can be used if having the tag value look like a flag seems disturbing to you.
Note that the +/-/* prefixes were not chosen arbitrarily: they reflect how Fossil internally stores and recognizes the type of a tag: <tt>+</tt> represents an "add tag", <tt>-</tt> a "cancel tag" (a.k.a. "anti-tag"), and <tt>*</tt> a propagating tag.
<h2>f-acat</h2>
The "artifact cat" tool outputs content from the content. If given a checkin name or the ID of some other fossil-internal structure, it outputs that structure (as opposed to doing complex rendering of the structure-specific type). By default it applies any necessary deltas to produce the desired version of a blob, but it can also be told (using the <tt>--raw</tt> flag) that it should do no undeltification. It always uncompresses the data (assuming it was compressed, which it normally, but not always, is).
<nowiki><pre>
# The current checkout version's manifest:
# f-acat current
B 200d1cd898f4e05591e78f82b2c0f2bc4c8db998
C Added\s--raw,\s--output,\sand\s--artifact\sflags\sto\sf-acat.
D 2013-09-08T12:25:31.660
F Makefile.in 41c00b5876e09e6bef5eaf4a68e885926eeca159
...
# The previous version's manifest, in its raw form (in this case
# a fossil-format delta):
# f-acat prev --raw
II
i@0,3P:Moved\sfsl_memory_allocator<SNIP>.
D 2013-09-08T12:01:11.6142g@24,9d@5Z,1u:04923c4435ee082205979a2bc0a9b518e1ff3d80
R a5f73027c19c1b33364845d4808bca6d
U stephan
Z 6721ef25586956f13ef59a4dcb77e339
</nowiki></pre>
|