SHA1 Hash:	83447b7bf1a632ed320b46bdfd2a836edadb91ce
Date:	2008-12-09 20:25:41
User:	kejoki
Comment:	Change the add command CLI doc to reflect recursive add of directories.
Timelines:	ancestors | descendants | both | trunk
Other Links:	files | ZIP archive | manifest

• branch=trunk inherited from [a28c83647d]
• sym-trunk inherited from [a28c83647d]

Modified www/cmd_add.wiki from [90059388b2] to [18a01b1247].

@@ -6,37 +6,60 @@
 <b>fossil</b> is designed to manage artifacts whose role is being
 "source" for something, most probably software program code or other
 text.  One can imagine all kinds of ways to let fossil know just what
 constitutes a source; the simplest and most direct way it
 <i>actually</i> finds out is when you give it the
-<code> fossil add <i>file</i> </code> command.
+<code> fossil add <i>path</i> </code> command.
 
 It's reasonable to think of
-the <a href="cmd_import.wiki"><code>import</code></a>
-and <a href="cmd_clone.wiki"><code>clone</code></a>
+the [./cmd_import.wiki | <code>import</code>]
+and [./cmd_clone.wiki | <code>clone</code>]
 commands as very high-powered versions of the <code>add</code>
 command that are combined with system level file movement and
 networking functions.  Not particularly accurate, but reasonable.
 
-Typing <code>fossil add myfile</code> causes fossil to put
+Typing <code>&nbsp;fossil add myfile</code> causes fossil to put
 <i>myfile</i> into the repository at the next
 <code>commit</code>&#8212;provided you issue it from within the source
 tree, of course.
 
-Note that the repository is <u>not</u> changed by the <code>add</code>
-command, but by the <code>commit</code> command.  <code>add</code>
-<i>myfile</i> tells <b>fossil</b> to "mark" <i>myfile</i> as part of
-the repository.  Only commands which actually manipulate the content
-of the "source" artifacts can physically put the file into (or remove
-it from) the repository.
+By contrast, <code>&nbsp;fossil add mydirectory</code> will add
+<em><strong>all</strong></em> of the files in <i>mydirectory</i>, and
+all of its sub-directories.  In other words, adding a directory will
+recursively add all of the directory's file system descendants to the
+repository.  This was an oft-requested feature, recently implemented.
+It is very flexible.  Only when you add a directory do you get the
+recursive behavior.  If you are globbing a subset of files, you won't
+get the recursion.
+
+Realize that the repository is <u>not</u> changed by the
+<code>add</code> command, but by the <code>&nbsp;commit</code> command.
+<code>add</code> <i>myfile</i> tells <b>fossil</b> to "mark"
+<i>myfile</i> as part of the repository.  Only commands which actually
+manipulate the content of the repository can physically put source
+artifacts into (or remove them from) the repository.
 
-Just to keep things confused, there are also commands that can
+Just to keep things symmetric, there are also commands that can
 manipulate the repository without affecting the checked-out sources
-(see <a href="cmd_pull.wiki">fossil pull</a>, for instance.)
+(see [./cmd_pull.wiki | fossil pull], for instance.)
+
+It's worthwhile reiterating that <b>fossil</b> is storing the content
+of source artifacts and the names of the artifacts in their "native
+habitat", a sequence of "temporal slices" (aka "versions") of the
+state of the whole system, and a set of unique identifiers.  When you
+add a file to a repository, the <i>path</i> to the file is a part of
+the <i>name</i> of the file.  There is a mis-match between the file
+system's idea of a directory (a file containing pointers to files) and
+fossil's idea (a substring of the name of the artifact.)  The names of
+the artifacts specify their relative locations because of the way the
+file system interprets them.  If you don't keep this in mind, you may
+fool yourself into thinking <b>fossil</b> somehow "stores
+directories."  It doesn't, and believing it does will eventually
+confuse you.
 
-See also: <a href="cmd_rm.wiki">fossil rm</a>,
-<a href="cmd_import.wiki">fossil import</a>,
-<a href="cmd_clone.wiki">fossil clone</a>,
-<a href="cmd_commit.wiki">fossil commit</a>,
-<a href="cmd_pull.wiki">fossil pull</a>,
-<a href="cmd_settings.wiki">fossil setting</a> (async),
-<a href="reference.wiki">Reference</a>
+See also: [./cmd_rm.wiki | fossil rm],
+[./cmd_import.wiki | fossil import],
+[./cmd_clone.wiki | fossil clone],
+[./cmd_commit.wiki | fossil commit],
+[./cmd_pull.wiki | fossil pull],
+[./cmd_settings.wiki | fossil setting] (async),
+[./reference.wiki | Reference]