git-export-filter.txt

   1 git-export-filter(1)
   2 ====================
   3
   4 NAME
   5 ----
   6 git-export-filter - Filter fast-export data with optional rewrites
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git export-filter' [--verbose|-v] [-h|--help] [--version|-V] [--debug|-d]
  13                   [--authors-file=<authors_file> [--require-authors]]
  14                   [--branches-file=<branches_file>] [--trunk-is-master]
  15                   [--convert-tagger=<email>] [--strip-at-suffix]
  16                   [--expand-renames] [--names] [--]
  17                   [<input_file>] > <output_file>
  18
  19
  20 DESCRIPTION
  21 -----------
  22
  23 Filters a git fast-export data stream optionally rewriting author and/or
  24 branch names along the way and writes the result to standard output.
  25
  26 When given no options or arguments, simply copies the input to the output.
  27 In this case the input is still parsed and invalid fast-export input data will
  28 still be detected even though no rewriting is being performed.
  29
  30
  31 OPTIONS
  32 -------
  33
  34 --verbose::
  35 --v::
  36         Show additional information on standard error while processing the
  37         data stream.
  38
  39 --help::
  40 -h::
  41         Show basic help.  If `--verbose` is given first show extensive help.
  42         No conversion is performed if this option is given.
  43
  44 --version::
  45 --V::
  46         Show the version information.
  47         No conversion is performed if this option is given.
  48
  49 --debug::
  50 -d::
  51         Show debugging information on standard error during the conversion.
  52
  53 --authors-file <authors_file>::
  54         Specifies author/committer names to rewrite.
  55         See the "REWRITE FILE FORMAT" below for information on `<authors_file>`
  56         format.
  57
  58 --require-authors::
  59         May only be specified if `--authors-file` is also specified.  If this
  60         option is given, then all author/committer names encountered in the
  61         input stream must be found in `<authors_file>` or an error will occur
  62         and the conversion will stop.  If this option is not given then
  63         author/committer names not listed in `<authors_file>` are
  64         left unchanged.
  65
  66 --branches-file <branches_file>::
  67         Specifies branch and/or tag names to rewrite.
  68         See the "REWRITE FILE FORMAT" below for information on
  69         `<branches_file>` format.
  70 +
  71 Annotated tag names can be renamed but only if they are located under
  72 `refs/tags/` as the fast-export file format forces that prefix to be present.
  73 The `refs/tags/` prefix must be included in the `<branches_file>` on both the
  74 left and right sides of the `=` in order to successfully rewrite annotated tag
  75 names.
  76
  77 --trunk-is-master::
  78         Giving this option converts `refs/heads/trunk` to `refs/heads/master`
  79         in the output.  The `--trunk-is-master` option can be given in place of
  80         or in addition to the `--branches-file` option.
  81 +
  82 Really this is just intended to be a shortcut to having a `<branches_file>`
  83 with a single line `refs/heads/trunk=refs/heads/master` in it.
  84
  85 --convert-tagger <email>::
  86         If this option is given, then any annotated tags with a committer that
  87         has an email of `<email>` will be converted to a lightweight tag.
  88 +
  89 Some fast-export producers create tag commands which always use a fixed tagger
  90 (typically `tagger`) with a data length of 0 and a timestamp identical to the
  91 commit that is being tagged.  In other words, a lightweight tag in disguise.
  92 +
  93 The `--convert-tagger` option can be used to convert these
  94 lightweight-tag-in-disguise annotated tags to a real lightweight tags.
  95
  96 --strip-at-suffix::
  97         If this option is given then when converting author/committer names,
  98         if the authors file does not contain an exact match for the email
  99         and the email contains an '@' sign then the email is looked up again
 100         after stripping everything starting with and including the '@'
 101         character from the end.
 102 +
 103 The 'svn-fe' utility appends '@...' suffixes to the email addresses it
 104 generates in the fast-export data and will need this option to use a standard
 105 'git svn' authors file.
 106
 107 --expand-renames::
 108         Some importers of fast-export data cannot handle renames but can
 109         handle copies.  If --expand-renames is given then any instances of
 110         filerename 'R' are replaced with a filecopy 'C' followed by a
 111         filedelete 'D' instead.
 112
 113 --names::
 114         This option may not be combined with any of the others.  Instead of
 115         outputting a modified fast-import stream, output only the author,
 116         committer and tagger names as they are encountered one per line
 117         without any timestamp information.  This can be used to help build
 118         an initial authors file.
 119 +
 120 Do note that the names are output as-is from the input stream whereas this
 121 utility expects to match only the email portion when given an authors file
 122 with the --authors-file option.  This means the name, non-email portion and
 123 surrounding '<' and '>' characters will have to be removed from the output
 124 provided by this option.  Additionally, of course, duplicate names need to
 125 be removed as well.
 126
 127 <input_file>::
 128         The fast-export stream to read.  If `<input_file>` is omitted, then
 129         standard input will be read.
 130
 131
 132 REWRITE FILE FORMAT
 133 -------------------
 134
 135 Syntax is compatible with the 'git svn' `--authors-file` and
 136 'git cvsimport' `-A` files.  For committer/author rewrites the syntax
 137 looks like:
 138 ------------------------------------------------------------------------
 139         email = John Smith <smith@example.com>
 140 ------------------------------------------------------------------------
 141 And for branch rewrites it looks like:
 142 ------------------------------------------------------------------------
 143         refs/heads/ALL_CAPS = refs/heads/small_caps
 144 ------------------------------------------------------------------------
 145 Blank lines and lines starting with `#` are ignored.
 146
 147 Note that when rewriting author/committer names, only the `<email>` portion
 148 (the part between `<` and `>`) of the name is matched, the rest of the name is
 149 ignored for matching purposes.
 150
 151
 152 TIPS
 153 ----
 154
 155 If the input data is the result of `fossil export --git` then probably the
 156 `--trunk-is-master` and `--convert-tagger tagger` options will be needed.
 157
 158
 159 AUTHOR
 160 ------
 161
 162 Kyle J. McKay <\mackyle@gmail.com>
 163
 164
 165 GIT
 166 ---
 167 Not part of the linkgit:git[1] suite yet