From: Junio C Hamano Date: Mon, 14 Jan 2013 15:59:46 +0000 (-0800) Subject: Merge branch 'jk/maint-fast-import-doc-reorder' into maint X-Git-Tag: v1.8.1.1~4 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/267aaa08e2e9b236d4ace006055066e353af8038?hp=-c Merge branch 'jk/maint-fast-import-doc-reorder' into maint * jk/maint-fast-import-doc-reorder: git-fast-import(1): reorganise options git-fast-import(1): combine documentation of --[no-]relative-marks --- 267aaa08e2e9b236d4ace006055066e353af8038 diff --combined Documentation/git-fast-import.txt index 3da5cc272a,73fec276e5..bf1a02a80d --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@@ -8,7 -8,6 +8,7 @@@ git-fast-import - Backend for fast Git SYNOPSIS -------- +[verse] frontend | 'git fast-import' [options] DESCRIPTION @@@ -33,34 -32,45 +33,46 @@@ the frontend program in use OPTIONS ------- - --date-format=:: - Specify the type of dates the frontend will supply to - fast-import within `author`, `committer` and `tagger` commands. - See ``Date Formats'' below for details about which formats - are supported, and their syntax. --force:: Force updating modified existing branches, even if doing so would cause commits to be lost (as the new commit does not contain the old commit). - --max-pack-size=:: - Maximum size of each output packfile. - The default is unlimited. + --quiet:: + Disable all non-fatal output, making fast-import silent when it + is successful. This option disables the output shown by + \--stats. - --big-file-threshold=:: - Maximum size of a blob that fast-import will attempt to - create a delta for, expressed in bytes. The default is 512m - (512 MiB). Some importers may wish to lower this on systems - with constrained memory. + --stats:: + Display some basic statistics about the objects fast-import has + created, the packfiles they were stored into, and the + memory used by fast-import during this run. Showing this output + is currently the default, but can be disabled with \--quiet. - --depth=:: - Maximum delta depth, for blob and tree deltification. - Default is 10. + Options for Frontends + ~~~~~~~~~~~~~~~~~~~~~ - --active-branches=:: - Maximum number of branches to maintain active at once. - See ``Memory Utilization'' below for details. Default is 5. + --cat-blob-fd=:: - Specify the file descriptor that will be written to - when the `cat-blob` command is encountered in the stream. - The default behaviour is to write to `stdout`. ++ Write responses to `cat-blob` and `ls` queries to the ++ file descriptor instead of `stdout`. Allows `progress` ++ output intended for the end-user to be separated from other ++ output. + + --date-format=:: + Specify the type of dates the frontend will supply to + fast-import within `author`, `committer` and `tagger` commands. + See ``Date Formats'' below for details about which formats + are supported, and their syntax. + + --done:: + Terminate with error if there is no `done` command at the end of + the stream. This option might be useful for detecting errors + that cause the frontend to terminate before it has started to + write a stream. + + Locations of Marks Files + ~~~~~~~~~~~~~~~~~~~~~~~~ --export-marks=:: Dumps the internal marks table to when complete. @@@ -83,32 -93,33 +95,33 @@@ Like --import-marks but instead of erroring out, silently skips the file if it does not exist. - --relative-marks:: + --[no-]relative-marks:: After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. In git-fast-import this means that the paths are relative to the .git/info/fast-import directory. However, other importers may use a different location. + + + Relative and non-relative marks may be combined by interweaving + --(no-)-relative-marks with the --(import|export)-marks= options. - --no-relative-marks:: - Negates a previous --relative-marks. Allows for combining - relative and non-relative marks by interweaving - --(no-)-relative-marks with the --(import|export)-marks= - options. + Performance and Compression Tuning + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - --cat-blob-fd=:: - Write responses to `cat-blob` and `ls` queries to the - file descriptor instead of `stdout`. Allows `progress` - output intended for the end-user to be separated from other - output. + --active-branches=:: + Maximum number of branches to maintain active at once. + See ``Memory Utilization'' below for details. Default is 5. - --done:: - Terminate with error if there is no `done` command at the - end of the stream. - This option might be useful for detecting errors that - cause the frontend to terminate before it has started to - write a stream. + --big-file-threshold=:: + Maximum size of a blob that fast-import will attempt to + create a delta for, expressed in bytes. The default is 512m + (512 MiB). Some importers may wish to lower this on systems + with constrained memory. + + --depth=:: + Maximum delta depth, for blob and tree deltification. + Default is 10. --export-pack-edges=:: After creating a packfile, print a line of data to @@@ -119,16 -130,9 +132,9 @@@ as these commits can be used as edge points during calls to 'git pack-objects'. - --quiet:: - Disable all non-fatal output, making fast-import silent when it - is successful. This option disables the output shown by - \--stats. - - --stats:: - Display some basic statistics about the objects fast-import has - created, the packfiles they were stored into, and the - memory used by fast-import during this run. Showing this output - is currently the default, but can be disabled with \--quiet. + --max-pack-size=:: + Maximum size of each output packfile. + The default is unlimited. Performance @@@ -424,11 -428,11 +430,11 @@@ they made it Here `` is the person's display name (for example ``Com M Itter'') and `` is the person's email address -(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) +(``\cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) and greater-than (\x3e) symbols. These are required to delimit the email address from the other fields in the line. Note that -`` is free-form and may contain any sequence of bytes, except -`LT` and `LF`. It is typically UTF-8 encoded. +`` and `` are free-form and may contain any sequence +of bytes, except `LT`, `GT` and `LF`. `` is typically UTF-8 encoded. The time of the change is specified by `` using the date format that was selected by the \--date-format= command line option. @@@ -439,9 -443,7 +445,9 @@@ their syntax ^^^^^^ The `from` command is used to specify the commit to initialize this branch from. This revision will be the first ancestor of the -new commit. +new commit. The state of the tree built at this commit will begin +with the state at the `from` commit, and be altered by the content +modifications in this commit. Omitting the `from` command in the first commit of a new branch will cause fast-import to create that commit with no ancestor. This @@@ -482,18 -484,16 +488,18 @@@ current branch value should be written ---- from refs/heads/branch^0 ---- -The `{caret}0` suffix is necessary as fast-import does not permit a branch to +The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the -`from` command is even read from the input. Adding `{caret}0` will force +`from` command is even read from the input. Adding `^0` will force fast-import to resolve the commit through Git's revision parsing library, rather than its internal branch table, thereby loading in the existing value of the branch. `merge` ^^^^^^^ -Includes one additional ancestor commit. If the `from` command is +Includes one additional ancestor commit. The additional ancestry +link does not change the way the tree state is built at this commit. +If the `from` command is omitted when creating a new branch, the first `merge` commit will be the first ancestor of the current commit, and the branch will start out with no files. An unlimited number of `merge` commands per @@@ -559,12 -559,8 +565,12 @@@ A `` string must use UNIX-style d slash `/`), may contain any byte other than `LF`, and must not start with double quote (`"`). -If an `LF` or double quote must be encoded into `` shell-style -quoting should be used, e.g. `"path/with\n and \" in it"`. +A path can use C-style string quoting; this is accepted in all cases +and mandatory if the filename starts with double quote or contains +`LF`. In C-style quoting, the complete name should be surrounded with +double quotes, and any `LF`, backslash, or double quote characters +must be escaped by preceding them with a backslash (e.g., +`"path/with\n, \\ and \" in it"`). The value of `` must be in canonical form. That is it must not: @@@ -670,14 -666,9 +676,14 @@@ paths for a commit are encouraged to d `notemodify` ^^^^^^^^^^^^ -Included in a `commit` command to add a new note (annotating a given -commit) or change the content of an existing note. This command has -two different means of specifying the content of the note. +Included in a `commit` `` command to add a new note +annotating a `` or change this annotation contents. +Internally it is similar to filemodify 100644 on `` +path (maybe split into subdirectories). It's not advised to +use any other commands to write to the `` tree except +`filedeleteall` to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note. External data format:: The data content for the note was already supplied by a prior @@@ -952,9 -943,6 +958,9 @@@ This command can be used anywhere in th accepted. In particular, the `cat-blob` command can be used in the middle of a commit but not in the middle of a `data` command. +See ``Responses To Commands'' below for details about how to read +this output safely. + `ls` ~~~~ Prints information about the object at a path to a file descriptor @@@ -988,7 -976,7 +994,7 @@@ Reading from a named tree: See `filemodify` above for a detailed description of ``. -Output uses the same format as `git ls-tree {litdd} `: +Output uses the same format as `git ls-tree -- `: ==== SP ('blob' | 'tree' | 'commit') SP HT LF @@@ -1004,9 -992,6 +1010,9 @@@ instead repor missing SP LF ==== +See ``Responses To Commands'' below for details about how to read +this output safely. + `feature` ~~~~~~~~~ Require that fast-import supports the specified feature, or abort if @@@ -1028,14 -1013,10 +1034,14 @@@ force: (see OPTIONS, above). import-marks:: +import-marks-if-exists:: Like --import-marks except in two respects: first, only one - "feature import-marks" command is allowed per stream; - second, an --import-marks= command-line option overrides - any "feature import-marks" command in the stream. + "feature import-marks" or "feature import-marks-if-exists" + command is allowed per stream; second, an --import-marks= + or --import-marks-if-exists command-line option overrides + any of these "feature" commands in the stream; third, + "feature import-marks-if-exists" like a corresponding + command-line option silently skips a nonexistent file. cat-blob:: ls:: @@@ -1097,35 -1078,6 +1103,35 @@@ If the `--done` command line option or in use, the `done` command is mandatory and marks the end of the stream. +Responses To Commands +--------------------- +New objects written by fast-import are not available immediately. +Most fast-import commands have no visible effect until the next +checkpoint (or completion). The frontend can send commands to +fill fast-import's input pipe without worrying about how quickly +they will take effect, which improves performance by simplifying +scheduling. + +For some frontends, though, it is useful to be able to read back +data from the current repository as it is being updated (for +example when the source material describes objects in terms of +patches to be applied to previously imported objects). This can +be accomplished by connecting the frontend and fast-import via +bidirectional pipes: + +==== + mkfifo fast-import-output + frontend fast-import-output +==== + +A frontend set up this way can use `progress`, `ls`, and `cat-blob` +commands to read information from the import in progress. + +To avoid deadlock, such frontends must completely consume any +pending output from `progress`, `ls`, and `cat-blob` before +performing writes to fast-import that might block. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a