Fossil SCM
Change the add command CLI doc to reflect recursive add of directories.
Commit
83447b7bf1a632ed320b46bdfd2a836edadb91ce
Parent
2be82dcc2aba6fd…
1 file changed
+44
-21
+44
-21
| --- www/cmd_add.wiki | ||
| +++ www/cmd_add.wiki | ||
| @@ -6,37 +6,60 @@ | ||
| 6 | 6 | <b>fossil</b> is designed to manage artifacts whose role is being |
| 7 | 7 | "source" for something, most probably software program code or other |
| 8 | 8 | text. One can imagine all kinds of ways to let fossil know just what |
| 9 | 9 | constitutes a source; the simplest and most direct way it |
| 10 | 10 | <i>actually</i> finds out is when you give it the |
| 11 | -<code> fossil add <i>file</i> </code> command. | |
| 11 | +<code> fossil add <i>path</i> </code> command. | |
| 12 | 12 | |
| 13 | 13 | It's reasonable to think of |
| 14 | -the <a href="cmd_import.wiki"><code>import</code></a> | |
| 15 | -and <a href="cmd_clone.wiki"><code>clone</code></a> | |
| 14 | +the [./cmd_import.wiki | <code>import</code>] | |
| 15 | +and [./cmd_clone.wiki | <code>clone</code>] | |
| 16 | 16 | commands as very high-powered versions of the <code>add</code> |
| 17 | 17 | command that are combined with system level file movement and |
| 18 | 18 | networking functions. Not particularly accurate, but reasonable. |
| 19 | 19 | |
| 20 | -Typing <code>fossil add myfile</code> causes fossil to put | |
| 20 | +Typing <code> fossil add myfile</code> causes fossil to put | |
| 21 | 21 | <i>myfile</i> into the repository at the next |
| 22 | 22 | <code>commit</code>—provided you issue it from within the source |
| 23 | 23 | tree, of course. |
| 24 | 24 | |
| 25 | -Note that the repository is <u>not</u> changed by the <code>add</code> | |
| 26 | -command, but by the <code>commit</code> command. <code>add</code> | |
| 27 | -<i>myfile</i> tells <b>fossil</b> to "mark" <i>myfile</i> as part of | |
| 28 | -the repository. Only commands which actually manipulate the content | |
| 29 | -of the "source" artifacts can physically put the file into (or remove | |
| 30 | -it from) the repository. | |
| 31 | - | |
| 32 | -Just to keep things confused, there are also commands that can | |
| 25 | +By contrast, <code> fossil add mydirectory</code> will add | |
| 26 | +<em><strong>all</strong></em> of the files in <i>mydirectory</i>, and | |
| 27 | +all of its sub-directories. In other words, adding a directory will | |
| 28 | +recursively add all of the directory's file system descendants to the | |
| 29 | +repository. This was an oft-requested feature, recently implemented. | |
| 30 | +It is very flexible. Only when you add a directory do you get the | |
| 31 | +recursive behavior. If you are globbing a subset of files, you won't | |
| 32 | +get the recursion. | |
| 33 | + | |
| 34 | +Realize that the repository is <u>not</u> changed by the | |
| 35 | +<code>add</code> command, but by the <code> commit</code> command. | |
| 36 | +<code>add</code> <i>myfile</i> tells <b>fossil</b> to "mark" | |
| 37 | +<i>myfile</i> as part of the repository. Only commands which actually | |
| 38 | +manipulate the content of the repository can physically put source | |
| 39 | +artifacts into (or remove them from) the repository. | |
| 40 | + | |
| 41 | +Just to keep things symmetric, there are also commands that can | |
| 33 | 42 | manipulate the repository without affecting the checked-out sources |
| 34 | -(see <a href="cmd_pull.wiki">fossil pull</a>, for instance.) | |
| 35 | - | |
| 36 | -See also: <a href="cmd_rm.wiki">fossil rm</a>, | |
| 37 | -<a href="cmd_import.wiki">fossil import</a>, | |
| 38 | -<a href="cmd_clone.wiki">fossil clone</a>, | |
| 39 | -<a href="cmd_commit.wiki">fossil commit</a>, | |
| 40 | -<a href="cmd_pull.wiki">fossil pull</a>, | |
| 41 | -<a href="cmd_settings.wiki">fossil setting</a> (async), | |
| 42 | -<a href="reference.wiki">Reference</a> | |
| 43 | +(see [./cmd_pull.wiki | fossil pull], for instance.) | |
| 44 | + | |
| 45 | +It's worthwhile reiterating that <b>fossil</b> is storing the content | |
| 46 | +of source artifacts and the names of the artifacts in their "native | |
| 47 | +habitat", a sequence of "temporal slices" (aka "versions") of the | |
| 48 | +state of the whole system, and a set of unique identifiers. When you | |
| 49 | +add a file to a repository, the <i>path</i> to the file is a part of | |
| 50 | +the <i>name</i> of the file. There is a mis-match between the file | |
| 51 | +system's idea of a directory (a file containing pointers to files) and | |
| 52 | +fossil's idea (a substring of the name of the artifact.) The names of | |
| 53 | +the artifacts specify their relative locations because of the way the | |
| 54 | +file system interprets them. If you don't keep this in mind, you may | |
| 55 | +fool yourself into thinking <b>fossil</b> somehow "stores | |
| 56 | +directories." It doesn't, and believing it does will eventually | |
| 57 | +confuse you. | |
| 58 | + | |
| 59 | +See also: [./cmd_rm.wiki | fossil rm], | |
| 60 | +[./cmd_import.wiki | fossil import], | |
| 61 | +[./cmd_clone.wiki | fossil clone], | |
| 62 | +[./cmd_commit.wiki | fossil commit], | |
| 63 | +[./cmd_pull.wiki | fossil pull], | |
| 64 | +[./cmd_settings.wiki | fossil setting] (async), | |
| 65 | +[./reference.wiki | Reference] | |
| 43 | 66 |
| --- www/cmd_add.wiki | |
| +++ www/cmd_add.wiki | |
| @@ -6,37 +6,60 @@ | |
| 6 | <b>fossil</b> is designed to manage artifacts whose role is being |
| 7 | "source" for something, most probably software program code or other |
| 8 | text. One can imagine all kinds of ways to let fossil know just what |
| 9 | constitutes a source; the simplest and most direct way it |
| 10 | <i>actually</i> finds out is when you give it the |
| 11 | <code> fossil add <i>file</i> </code> command. |
| 12 | |
| 13 | It's reasonable to think of |
| 14 | the <a href="cmd_import.wiki"><code>import</code></a> |
| 15 | and <a href="cmd_clone.wiki"><code>clone</code></a> |
| 16 | commands as very high-powered versions of the <code>add</code> |
| 17 | command that are combined with system level file movement and |
| 18 | networking functions. Not particularly accurate, but reasonable. |
| 19 | |
| 20 | Typing <code>fossil add myfile</code> causes fossil to put |
| 21 | <i>myfile</i> into the repository at the next |
| 22 | <code>commit</code>—provided you issue it from within the source |
| 23 | tree, of course. |
| 24 | |
| 25 | Note that the repository is <u>not</u> changed by the <code>add</code> |
| 26 | command, but by the <code>commit</code> command. <code>add</code> |
| 27 | <i>myfile</i> tells <b>fossil</b> to "mark" <i>myfile</i> as part of |
| 28 | the repository. Only commands which actually manipulate the content |
| 29 | of the "source" artifacts can physically put the file into (or remove |
| 30 | it from) the repository. |
| 31 | |
| 32 | Just to keep things confused, there are also commands that can |
| 33 | manipulate the repository without affecting the checked-out sources |
| 34 | (see <a href="cmd_pull.wiki">fossil pull</a>, for instance.) |
| 35 | |
| 36 | See also: <a href="cmd_rm.wiki">fossil rm</a>, |
| 37 | <a href="cmd_import.wiki">fossil import</a>, |
| 38 | <a href="cmd_clone.wiki">fossil clone</a>, |
| 39 | <a href="cmd_commit.wiki">fossil commit</a>, |
| 40 | <a href="cmd_pull.wiki">fossil pull</a>, |
| 41 | <a href="cmd_settings.wiki">fossil setting</a> (async), |
| 42 | <a href="reference.wiki">Reference</a> |
| 43 |
| --- www/cmd_add.wiki | |
| +++ www/cmd_add.wiki | |
| @@ -6,37 +6,60 @@ | |
| 6 | <b>fossil</b> is designed to manage artifacts whose role is being |
| 7 | "source" for something, most probably software program code or other |
| 8 | text. One can imagine all kinds of ways to let fossil know just what |
| 9 | constitutes a source; the simplest and most direct way it |
| 10 | <i>actually</i> finds out is when you give it the |
| 11 | <code> fossil add <i>path</i> </code> command. |
| 12 | |
| 13 | It's reasonable to think of |
| 14 | the [./cmd_import.wiki | <code>import</code>] |
| 15 | and [./cmd_clone.wiki | <code>clone</code>] |
| 16 | commands as very high-powered versions of the <code>add</code> |
| 17 | command that are combined with system level file movement and |
| 18 | networking functions. Not particularly accurate, but reasonable. |
| 19 | |
| 20 | Typing <code> fossil add myfile</code> causes fossil to put |
| 21 | <i>myfile</i> into the repository at the next |
| 22 | <code>commit</code>—provided you issue it from within the source |
| 23 | tree, of course. |
| 24 | |
| 25 | By contrast, <code> fossil add mydirectory</code> will add |
| 26 | <em><strong>all</strong></em> of the files in <i>mydirectory</i>, and |
| 27 | all of its sub-directories. In other words, adding a directory will |
| 28 | recursively add all of the directory's file system descendants to the |
| 29 | repository. This was an oft-requested feature, recently implemented. |
| 30 | It is very flexible. Only when you add a directory do you get the |
| 31 | recursive behavior. If you are globbing a subset of files, you won't |
| 32 | get the recursion. |
| 33 | |
| 34 | Realize that the repository is <u>not</u> changed by the |
| 35 | <code>add</code> command, but by the <code> commit</code> command. |
| 36 | <code>add</code> <i>myfile</i> tells <b>fossil</b> to "mark" |
| 37 | <i>myfile</i> as part of the repository. Only commands which actually |
| 38 | manipulate the content of the repository can physically put source |
| 39 | artifacts into (or remove them from) the repository. |
| 40 | |
| 41 | Just to keep things symmetric, there are also commands that can |
| 42 | manipulate the repository without affecting the checked-out sources |
| 43 | (see [./cmd_pull.wiki | fossil pull], for instance.) |
| 44 | |
| 45 | It's worthwhile reiterating that <b>fossil</b> is storing the content |
| 46 | of source artifacts and the names of the artifacts in their "native |
| 47 | habitat", a sequence of "temporal slices" (aka "versions") of the |
| 48 | state of the whole system, and a set of unique identifiers. When you |
| 49 | add a file to a repository, the <i>path</i> to the file is a part of |
| 50 | the <i>name</i> of the file. There is a mis-match between the file |
| 51 | system's idea of a directory (a file containing pointers to files) and |
| 52 | fossil's idea (a substring of the name of the artifact.) The names of |
| 53 | the artifacts specify their relative locations because of the way the |
| 54 | file system interprets them. If you don't keep this in mind, you may |
| 55 | fool yourself into thinking <b>fossil</b> somehow "stores |
| 56 | directories." It doesn't, and believing it does will eventually |
| 57 | confuse you. |
| 58 | |
| 59 | See also: [./cmd_rm.wiki | fossil rm], |
| 60 | [./cmd_import.wiki | fossil import], |
| 61 | [./cmd_clone.wiki | fossil clone], |
| 62 | [./cmd_commit.wiki | fossil commit], |
| 63 | [./cmd_pull.wiki | fossil pull], |
| 64 | [./cmd_settings.wiki | fossil setting] (async), |
| 65 | [./reference.wiki | Reference] |
| 66 |