logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-fast-export.1 (12905B)


  1. '\" t
  2. .\" Title: git-fast-export
  3. .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\" Date: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GIT\-FAST\-EXPORT" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. git-fast-export \- Git data exporter
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. \fIgit fast\-export\fR [<options>] | \fIgit fast\-import\fR
  36. .fi
  37. .SH "DESCRIPTION"
  38. .sp
  39. This program dumps the given revisions in a form suitable to be piped into \fIgit fast\-import\fR\&.
  40. .sp
  41. You can use it as a human\-readable bundle replacement (see \fBgit-bundle\fR(1)), or as a format that can be edited before being fed to \fIgit fast\-import\fR in order to do history rewrites (an ability relied on by tools like \fIgit filter\-repo\fR)\&.
  42. .SH "OPTIONS"
  43. .PP
  44. \-\-progress=<n>
  45. .RS 4
  46. Insert
  47. \fIprogress\fR
  48. statements every <n> objects, to be shown by
  49. \fIgit fast\-import\fR
  50. during import\&.
  51. .RE
  52. .PP
  53. \-\-signed\-tags=(verbatim|warn|warn\-strip|strip|abort)
  54. .RS 4
  55. 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\&.
  56. .sp
  57. When asking to
  58. \fIabort\fR
  59. (which is the default), this program will die when encountering a signed tag\&. With
  60. \fIstrip\fR, the tags will silently be made unsigned, with
  61. \fIwarn\-strip\fR
  62. they will be made unsigned but a warning will be displayed, with
  63. \fIverbatim\fR, they will be silently exported and with
  64. \fIwarn\fR, they will be exported, but you will see a warning\&.
  65. .RE
  66. .PP
  67. \-\-tag\-of\-filtered\-object=(abort|drop|rewrite)
  68. .RS 4
  69. 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\&.
  70. .sp
  71. When asking to
  72. \fIabort\fR
  73. (which is the default), this program will die when encountering such a tag\&. With
  74. \fIdrop\fR
  75. it will omit such tags from the output\&. With
  76. \fIrewrite\fR, if the tagged object is a commit, it will rewrite the tag to tag an ancestor commit (via parent rewriting; see
  77. \fBgit-rev-list\fR(1))\&.
  78. .RE
  79. .PP
  80. \-M, \-C
  81. .RS 4
  82. Perform move and/or copy detection, as described in the
  83. \fBgit-diff\fR(1)
  84. manual page, and use it to generate rename and copy commands in the output dump\&.
  85. .sp
  86. Note that earlier versions of this command did not complain and produced incorrect results if you gave these options\&.
  87. .RE
  88. .PP
  89. \-\-export\-marks=<file>
  90. .RS 4
  91. Dumps the internal marks table to <file> when complete\&. Marks are written one per line as
  92. \fB:markid\fR
  93. \fBSHA\-1\fR\&. Only marks for revisions are dumped; marks for blobs are ignored\&. Backends can use this file to validate imports after they 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\&. The file will not be written if no new object has been marked/exported\&.
  94. .RE
  95. .PP
  96. \-\-import\-marks=<file>
  97. .RS 4
  98. 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\&.
  99. .RE
  100. .PP
  101. \-\-mark\-tags
  102. .RS 4
  103. In addition to labelling blobs and commits with mark ids, also label tags\&. This is useful in conjunction with
  104. \fB\-\-export\-marks\fR
  105. and
  106. \fB\-\-import\-marks\fR, and is also useful (and necessary) for exporting of nested tags\&. It does not hurt other cases and would be the default, but many fast\-import frontends are not prepared to accept tags with mark identifiers\&.
  107. .sp
  108. Any commits (or tags) that have already been marked will not be exported again\&. 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\&.
  109. .RE
  110. .PP
  111. \-\-fake\-missing\-tagger
  112. .RS 4
  113. Some old repositories have tags without a tagger\&. The fast\-import protocol was pretty strict about that, and did not allow that\&. So fake a tagger to be able to fast\-import the output\&.
  114. .RE
  115. .PP
  116. \-\-use\-done\-feature
  117. .RS 4
  118. Start the stream with a
  119. \fIfeature done\fR
  120. stanza, and terminate it with a
  121. \fIdone\fR
  122. command\&.
  123. .RE
  124. .PP
  125. \-\-no\-data
  126. .RS 4
  127. Skip output of blob objects and instead refer to blobs via their original SHA\-1 hash\&. This is useful when rewriting the directory structure or history of a repository without touching the contents of individual files\&. Note that the resulting stream can only be used by a repository which already contains the necessary objects\&.
  128. .RE
  129. .PP
  130. \-\-full\-tree
  131. .RS 4
  132. 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\(cqs first parent)\&.
  133. .RE
  134. .PP
  135. \-\-anonymize
  136. .RS 4
  137. Anonymize the contents of the repository while still retaining the shape of the history and stored tree\&. See the section on
  138. \fBANONYMIZING\fR
  139. below\&.
  140. .RE
  141. .PP
  142. \-\-anonymize\-map=<from>[:<to>]
  143. .RS 4
  144. Convert token
  145. \fI<from>\fR
  146. to
  147. \fI<to>\fR
  148. in the anonymized output\&. If
  149. \fI<to>\fR
  150. is omitted, map
  151. \fI<from>\fR
  152. to itself (i\&.e\&., do not anonymize it)\&. See the section on
  153. \fBANONYMIZING\fR
  154. below\&.
  155. .RE
  156. .PP
  157. \-\-reference\-excluded\-parents
  158. .RS 4
  159. By default, running a command such as
  160. \fBgit\fR
  161. \fBfast\-export\fR
  162. \fBmaster~5\fR\fB\&.\&.\fR\fBmaster\fR
  163. will not include the commit master~5 and will make master~4 no longer have master~5 as a parent (though both the old master~4 and new master~4 will have all the same files)\&. Use \-\-reference\-excluded\-parents to instead have the stream refer to commits in the excluded range of history by their sha1sum\&. Note that the resulting stream can only be used by a repository which already contains the necessary parent commits\&.
  164. .RE
  165. .PP
  166. \-\-show\-original\-ids
  167. .RS 4
  168. Add an extra directive to the output for commits and blobs,
  169. \fBoriginal\-oid\fR
  170. \fI<SHA1SUM>\fR\&. While such directives will likely be ignored by importers such as git\-fast\-import, it may be useful for intermediary filters (e\&.g\&. for rewriting commit messages which refer to older commits, or for stripping blobs by id)\&.
  171. .RE
  172. .PP
  173. \-\-reencode=(yes|no|abort)
  174. .RS 4
  175. Specify how to handle
  176. \fBencoding\fR
  177. header in commit objects\&. When asking to
  178. \fIabort\fR
  179. (which is the default), this program will die when encountering such a commit object\&. With
  180. \fIyes\fR, the commit message will be re\-encoded into UTF\-8\&. With
  181. \fIno\fR, the original encoding will be preserved\&.
  182. .RE
  183. .PP
  184. \-\-refspec
  185. .RS 4
  186. Apply the specified refspec to each ref exported\&. Multiple of them can be specified\&.
  187. .RE
  188. .PP
  189. [<git\-rev\-list\-args>\&...\:]
  190. .RS 4
  191. A list of arguments, acceptable to
  192. \fIgit rev\-parse\fR
  193. and
  194. \fIgit rev\-list\fR, that specifies the specific objects and references to export\&. For example,
  195. \fBmaster~10\fR\fB\&.\&.\fR\fBmaster\fR
  196. causes the current master reference to be exported along with all objects added since its 10th ancestor commit and (unless the \-\-reference\-excluded\-parents option is specified) all files common to master~9 and master~10\&.
  197. .RE
  198. .SH "EXAMPLES"
  199. .sp
  200. .if n \{\
  201. .RS 4
  202. .\}
  203. .nf
  204. $ git fast\-export \-\-all | (cd /empty/repository && git fast\-import)
  205. .fi
  206. .if n \{\
  207. .RE
  208. .\}
  209. .sp
  210. This will export the whole repository and import it into the existing empty repository\&. Except for reencoding commits that are not in UTF\-8, it would be a one\-to\-one mirror\&.
  211. .sp
  212. .if n \{\
  213. .RS 4
  214. .\}
  215. .nf
  216. $ git fast\-export master~5\&.\&.master |
  217. sed "s|refs/heads/master|refs/heads/other|" |
  218. git fast\-import
  219. .fi
  220. .if n \{\
  221. .RE
  222. .\}
  223. .sp
  224. This makes a new branch called \fIother\fR from \fImaster~5\&.\&.master\fR (i\&.e\&. if \fImaster\fR has linear history, it will take the last 5 commits)\&.
  225. .sp
  226. Note that this assumes that none of the blobs and commit messages referenced by that revision range contains the string \fIrefs/heads/master\fR\&.
  227. .SH "ANONYMIZING"
  228. .sp
  229. If the \fB\-\-anonymize\fR 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\&.
  230. .sp
  231. 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\&.
  232. .sp
  233. If you think you have found a git bug, you can start by exporting an anonymized stream of the whole repository:
  234. .sp
  235. .if n \{\
  236. .RS 4
  237. .\}
  238. .nf
  239. $ git fast\-export \-\-anonymize \-\-all >anon\-stream
  240. .fi
  241. .if n \{\
  242. .RE
  243. .\}
  244. .sp
  245. 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):
  246. .sp
  247. .if n \{\
  248. .RS 4
  249. .\}
  250. .nf
  251. $ git init anon\-repo
  252. $ cd anon\-repo
  253. $ git fast\-import <\&.\&./anon\-stream
  254. $ \&.\&.\&. test your bug \&.\&.\&.
  255. .fi
  256. .if n \{\
  257. .RE
  258. .\}
  259. .sp
  260. If the anonymized repository shows the bug, it may be worth sharing \fBanon\-stream\fR 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:
  261. .sp
  262. .if n \{\
  263. .RS 4
  264. .\}
  265. .nf
  266. $ perl \-pe \*(Aqs/\ed+/X/g\*(Aq <anon\-stream | sort \-u | less
  267. .fi
  268. .if n \{\
  269. .RE
  270. .\}
  271. .sp
  272. 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\&.
  273. .sp
  274. Reproducing some bugs may require referencing particular commits or paths, which becomes challenging after refnames and paths have been anonymized\&. You can ask for a particular token to be left as\-is or mapped to a new value\&. For example, if you have a bug which reproduces with \fBgit\fR \fBrev\-list\fR \fBsensitive\fR \fB\-\-\fR \fBsecret\&.c\fR, you can run:
  275. .sp
  276. .if n \{\
  277. .RS 4
  278. .\}
  279. .nf
  280. $ git fast\-export \-\-anonymize \-\-all \e
  281. \-\-anonymize\-map=sensitive:foo \e
  282. \-\-anonymize\-map=secret\&.c:bar\&.c \e
  283. >stream
  284. .fi
  285. .if n \{\
  286. .RE
  287. .\}
  288. .sp
  289. After importing the stream, you can then run \fBgit\fR \fBrev\-list\fR \fBfoo\fR \fB\-\-\fR \fBbar\&.c\fR in the anonymized repository\&.
  290. .sp
  291. Note that paths and refnames are split into tokens at slash boundaries\&. The command above would anonymize \fBsubdir/secret\&.c\fR as something like \fBpath123/bar\&.c\fR; you could then search for \fBbar\&.c\fR in the anonymized repository to determine the final pathname\&.
  292. .sp
  293. To make referencing the final pathname simpler, you can map each path component; so if you also anonymize \fBsubdir\fR to \fBpublicdir\fR, then the final pathname would be \fBpublicdir/bar\&.c\fR\&.
  294. .SH "LIMITATIONS"
  295. .sp
  296. Since \fIgit fast\-import\fR 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\&.
  297. .SH "SEE ALSO"
  298. .sp
  299. \fBgit-fast-import\fR(1)
  300. .SH "GIT"
  301. .sp
  302. Part of the \fBgit\fR(1) suite