diff options
Diffstat (limited to 'Documentation/git-fast-export.txt')
| -rw-r--r-- | Documentation/git-fast-export.txt | 129 |
1 files changed, 102 insertions, 27 deletions
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 75b06f33e7..ed57c684db 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -8,36 +8,39 @@ git-fast-export - Git data exporter SYNOPSIS -------- +[verse] 'git fast-export [options]' | 'git fast-import' DESCRIPTION ----------- This program dumps the given revisions in a form suitable to be piped -into 'git-fast-import'. +into 'git fast-import'. You can use it as a human-readable bundle replacement (see linkgit:git-bundle[1]), or as a kind of an interactive -'git-filter-branch'. +'git filter-branch'. OPTIONS ------- --progress=<n>:: Insert 'progress' statements every <n> objects, to be shown by - 'git-fast-import' during import. + 'git fast-import' during import. ---signed-tags=(verbatim|warn|strip|abort):: +--signed-tags=(verbatim|warn|warn-strip|strip|abort):: Specify how to handle signed tags. Since any transformation after the export can change the tag names (which can also happen when excluding revisions) the signatures will not match. + When asking to 'abort' (which is the default), this program will die -when encountering a signed tag. With 'strip', the tags will be made -unsigned, with 'verbatim', they will be silently exported -and with 'warn', they will be exported, but you will see a warning. +when encountering a signed tag. With 'strip', the tags will silently +be made unsigned, with 'warn-strip' they will be made unsigned but a +warning will be displayed, with 'verbatim', they will be silently +exported and with 'warn', they will be exported, but you will see a +warning. --tag-of-filtered-object=(abort|drop|rewrite):: - Specify how to handle tags whose tagged objectis filtered out. + Specify how to handle tags whose tagged object is filtered out. Since revisions and files to export can be limited by path, tagged objects may be filtered completely. + @@ -64,15 +67,17 @@ produced incorrect results if you gave these options. have been completed, or to save the marks table across incremental runs. As <file> is only opened and truncated at completion, the same path can also be safely given to - \--import-marks. + --import-marks. + The file will not be written if no new object has been + marked/exported. --import-marks=<file>:: Before processing any input, load the marks specified in <file>. The input file must exist, must be readable, and - must use the same format as produced by \--export-marks. + must use the same format as produced by --export-marks. + Any commits that have already been marked will not be exported again. -If the backend uses a similar \--import-marks file, this allows for +If the backend uses a similar --import-marks file, this allows for incremental bidirectional exporting of the repository by keeping the marks the same across runs. @@ -82,6 +87,10 @@ marks the same across runs. allow that. So fake a tagger to be able to fast-import the output. +--use-done-feature:: + Start the stream with a 'feature done' stanza, and terminate + it with a 'done' command. + --no-data:: Skip output of blob objects and instead refer to blobs via their original SHA-1 hash. This is useful when rewriting the @@ -90,12 +99,27 @@ marks the same across runs. resulting stream can only be used by a repository which already contains the necessary objects. -[git-rev-list-args...]:: - A list of arguments, acceptable to 'git-rev-parse' and - 'git-rev-list', that specifies the specific objects and references - to export. For example, `master\~10..master` causes the - current master reference to be exported along with all objects - added since its 10th ancestor commit. +--full-tree:: + This option will cause fast-export to issue a "deleteall" + directive for each commit followed by a full list of all files + in the commit (as opposed to just listing the files which are + different from the commit's first parent). + +--anonymize:: + Anonymize the contents of the repository while still retaining + the shape of the history and stored tree. See the section on + `ANONYMIZING` below. + +--refspec:: + Apply the specified refspec to each ref exported. Multiple of them can + be specified. + +[<git-rev-list-args>...]:: + A list of arguments, acceptable to 'git rev-parse' and + 'git rev-list', that specifies the specific objects and references + to export. For example, `master~10..master` causes the + current master reference to be exported along with all objects + added since its 10th ancestor commit. EXAMPLES -------- @@ -122,21 +146,72 @@ referenced by that revision range contains the string 'refs/heads/master'. -Limitations +ANONYMIZING ----------- -Since 'git-fast-import' cannot tag trees, you will not be -able to export the linux-2.6.git repository completely, as it contains -a tag referencing a tree instead of a commit. +If the `--anonymize` option is given, git will attempt to remove all +identifying information from the repository while still retaining enough +of the original tree and history patterns to reproduce some bugs. The +goal is that a git bug which is found on a private repository will +persist in the anonymized repository, and the latter can be shared with +git developers to help solve the bug. + +With this option, git will replace all refnames, paths, blob contents, +commit and tag messages, names, and email addresses in the output with +anonymized data. Two instances of the same string will be replaced +equivalently (e.g., two commits with the same author will have the same +anonymized author in the output, but bear no resemblance to the original +author string). The relationship between commits, branches, and tags is +retained, as well as the commit timestamps (but the commit messages and +refnames bear no resemblance to the originals). The relative makeup of +the tree is retained (e.g., if you have a root tree with 10 files and 3 +trees, so will the output), but their names and the contents of the +files will be replaced. + +If you think you have found a git bug, you can start by exporting an +anonymized stream of the whole repository: + +--------------------------------------------------- +$ git fast-export --anonymize --all >anon-stream +--------------------------------------------------- + +Then confirm that the bug persists in a repository created from that +stream (many bugs will not, as they really do depend on the exact +repository contents): + +--------------------------------------------------- +$ git init anon-repo +$ cd anon-repo +$ git fast-import <../anon-stream +$ ... test your bug ... +--------------------------------------------------- + +If the anonymized repository shows the bug, it may be worth sharing +`anon-stream` along with a regular bug report. Note that the anonymized +stream compresses very well, so gzipping it is encouraged. If you want +to examine the stream to see that it does not contain any private data, +you can peruse it directly before sending. You may also want to try: + +--------------------------------------------------- +$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less +--------------------------------------------------- + +which shows all of the unique lines (with numbers converted to "X", to +collapse "User 0", "User 1", etc into "User X"). This produces a much +smaller output, and it is usually easy to quickly confirm that there is +no private data in the stream. -Author ------- -Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>. +Limitations +----------- -Documentation --------------- -Documentation by Johannes E. Schindelin <johannes.schindelin@gmx.de>. +Since 'git fast-import' cannot tag trees, you will not be +able to export the linux.git repository completely, as it contains +a tag referencing a tree instead of a commit. + +SEE ALSO +-------- +linkgit:git-fast-import[1] GIT --- |