summaryrefslogtreecommitdiff
path: root/Documentation/git-fast-export.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-fast-export.txt')
-rw-r--r--Documentation/git-fast-export.txt93
1 files changed, 83 insertions, 10 deletions
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index f37eada63a..929e496af8 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -27,15 +27,17 @@ OPTIONS
Insert 'progress' statements every <n> objects, to be shown by
'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 object is filtered out.
@@ -66,6 +68,8 @@ produced incorrect results if you gave these options.
incremental runs. As <file> is only opened and truncated
at completion, the same path can also be safely given to
\--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
@@ -101,12 +105,21 @@ marks the same across runs.
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{tilde}10..master` causes the
- current master reference to be exported along with all objects
- added since its 10th ancestor commit.
+ 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
--------
@@ -133,13 +146,73 @@ referenced by that revision range contains the string
'refs/heads/master'.
+ANONYMIZING
+-----------
+
+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.
+
+
Limitations
-----------
Since 'git fast-import' cannot tag trees, you will not be
-able to export the linux-2.6.git repository completely, as it contains
+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
---
Part of the linkgit:git[1] suite