git-export-filter.1

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