diff --git a/Documentation/config.adoc b/Documentation/config.adoc index aa6360e230af2b..c853578cac8ebb 100644 --- a/Documentation/config.adoc +++ b/Documentation/config.adoc @@ -610,6 +610,8 @@ include::config/status.adoc[] include::config/submodule.adoc[] +include::config/svn.adoc[] + include::config/tag.adoc[] include::config/tar.adoc[] diff --git a/Documentation/config/fastimport.adoc b/Documentation/config/fastimport.adoc index 903677d7efefa0..7b721fa0e9caaf 100644 --- a/Documentation/config/fastimport.adoc +++ b/Documentation/config/fastimport.adoc @@ -1,4 +1,4 @@ -fastimport.unpackLimit:: +`fastimport.unpackLimit`:: If the number of objects imported by linkgit:git-fast-import[1] is below this limit, then the objects will be unpacked into loose object files. However, if the number of imported objects diff --git a/Documentation/config/svn.adoc b/Documentation/config/svn.adoc new file mode 100644 index 00000000000000..19df43cf58eeb5 --- /dev/null +++ b/Documentation/config/svn.adoc @@ -0,0 +1,175 @@ +`svn.addAuthorFrom`:: + Append a `From:` line based on the Git commit's author string when + committing to SVN from Git (as part of `set-tree` or `dcommit` + operations), if the existing log message doesn't already have a `From:` + or `Signed-off-by` trailer. Using this together with `svn.useLogAuthor` + will retrieve a valid author string for all commits. + +`svn.authorsfile`:: + Specify the path to the authors file used to map SVN committer names to + Git author identities. The file uses the same syntax as `git cvsimport`, + with an optional empty email address written as `<>`. If set and `git svn` + encounters an SVN committer name not present in the file, the operation + is aborted until the entry is added. + +`svn.authorsProg`:: + Specify a program to execute for each SVN committer name not found in + the authors file. The committer name is passed as the first argument; + the program must return a single line of the form `Name ` or + `Name <>`, which is treated as if it were an entry in the authors file. ++ +Due to historical reasons a relative filename is first searched relative +to the current directory for `init` and `clone` and relative to the root +of the working tree for `fetch`. If the filename is not found, it is +searched like any other command in `$PATH`. + +`svn.edit`:: + Open an editor for the commit message before committing to SVN. + This is off by default for commit objects and forced on when + committing tree objects. Used with the `dcommit`, `set-tree` and + `commit-diff` commands. + +`svn.findcopiesharder`:: +`svn.l`:: + Pass `--find-copies-harder` and `-l` directly to + linkgit:git-diff-tree[1]. Used with the `dcommit`, `set-tree` and + `commit-diff` commands. + +`svn.followparent`:: + Track the copy history of each tracked branch to determine a suitable + parent for the first Git commit on the branch. This is especially + helpful when tracking a directory that has been moved around within the + repository. Disabling this feature may speed up cloning. + Enabled by default; set to `false` to disable. + +`svn.noMetadata`:: +`svn-remote..noMetadata`:: + Remove the `git-svn-id:` lines at the end of every commit. ++ +This option can only be used for one-shot imports as `git svn` +will not be able to fetch again without metadata. Additionally, +if you lose your `$GIT_DIR/svn/**/.rev_map.*` files, `git svn` will not +be able to rebuild them. ++ +The `git svn log` command will not work on repositories using +this, either. Using this conflicts with the `useSvmProps` +option for (hopefully) obvious reasons. ++ +This option is NOT recommended as it makes it difficult to track down +old references to SVN revision numbers in existing documentation, bug +reports, and archives. If you plan to eventually migrate from SVN to +Git and are certain about dropping SVN history, consider +https://github.com/newren/git-filter-repo[git-filter-repo] instead. +filter-repo also allows reformatting of metadata for ease-of-reading +and rewriting authorship info for non-"svn.authorsFile" users. + +`svn.pushmergeinfo`:: + Cause `git svn` to attempt to automatically populate the + `svn:mergeinfo` property in the SVN repository when possible. + Currently this can only be done when dcommitting non-fast-forward + merges where all parents but the first have already been pushed into SVN. + +`svn.rmdir`:: + Remove directories from the SVN tree when they contain no files. + SVN can version empty directories; they are not removed by default + when all files are deleted. Since Git cannot track empty directories, + enabling this flag makes commits to SVN behave more like Git. + Used with the `dcommit`, `set-tree` and `commit-diff` commands. + +`svn.useLogAuthor`:: + Use the first `From:` line or `Signed-off-by` trailer found in the + log message as the author string when retrieving SVN commits into Git + (as part of `fetch`, `rebase`, or `dcommit` operations). + +`svn.useSvmProps`:: +`svn-remote..useSvmProps`:: + Re-map repository URLs and UUIDs from mirrors created using SVN::Mirror + (or svk) for metadata. ++ +If an SVN revision has a property, `svm:headrev`, it is likely +that the revision was created by SVN::Mirror (also used by SVK). +The property contains a repository UUID and a revision. We want +to make it look like we are mirroring the original URL, so +introduce a helper function that returns the original identity +URL and UUID, and use it when generating metadata in commit +messages. + +`svn.useSvnsyncProps`:: +`svn-remote..useSvnsyncprops`:: + Re-map repository URLs and UUIDs for users of the `svnsync`(1) command + distributed with SVN 1.4.x and later, similar to the `useSvmProps` option. + +`svn.brokenSymlinkWorkaround`:: + Disable potentially expensive checks to workaround broken symlinks checked + into SVN by broken clients. Set this option to `false` if you track a + SVN repository with many empty blobs that are not symlinks. This option + may be changed while `git svn` is running and take effect on the next + revision fetched. If unset, `git svn` assumes this option to be `true`. + +`svn.pathnameencoding`:: + Recode pathnames to a given encoding. + It can be used by Windows users and by those who work in non-UTF-8 + locales to avoid corrupted file names with non-ASCII characters. + Valid encodings are the ones supported by Perl's Encode module. + +`svn-remote..automkdirs`:: + Recreate empty directories that are in the Subversion repository. + Normally, the `git svn clone` and `git svn rebase` commands attempt to + do this automatically. If this option is set to `false`, then empty + directories will only be created if the `git svn mkdirs` command is run + explicitly. If unset, `git svn` assumes this option to be `true`. + +`svn-remote..commiturl`:: +`svn.commiturl`:: + Specify the URL to use when committing to SVN (the full path). + `svn.commiturl` overrides the value for all `svn-remote..commiturl` + entries. This allows repositories created with one transport method + (e.g. `svn://` or `http://` for anonymous read) to commit via an alternate + transport (e.g. `svn+ssh://` or `https://`). ++ +Note that the SVN URL of `commiturl` includes the SVN branch. To set the +commit URL for an entire SVN repository use `svn-remote..pushurl` instead. ++ +Using this option for any other purpose (don't ask) is very strongly discouraged. + +`svn-remote..ignore-paths`:: + Specify a Perl regular expression to skip matching paths when + checking out from SVN. The pattern is applied on every `fetch`, + including automatic fetches triggered by `clone`, `dcommit`, + `rebase`, etc. If both this key and the `--ignore-paths` command-line + option are given, both regular expressions are applied. + +`svn-remote..ignore-refs`:: + Specify a Perl regular expression to ignore matching branch or tag refs + when fetching. A negative look-ahead assertion such as + `^refs/remotes/origin/(?!tags/wanted-tag|wanted-branch).*$` + can be used to allow only certain refs. If both this key and the + `--ignore-refs` command-line option are given, both regular expressions + are applied. + +`svn-remote..include-paths`:: + Specify a Perl regular expression so that only matching paths are + included when checking out from SVN. The pattern is applied on every + `fetch`, including automatic fetches triggered by `clone`, `dcommit`, + `rebase`, etc. `svn-remote..ignore-paths` takes precedence over + this key. + +`svn-remote..pushurl`:: + Provide an alternate read/write transport for the SVN repository, + similar to Git's `remote..pushurl`. This key is designed + to be used in cases where `url` points to an SVN repository + via a read-only transport. It is assumed that both keys point to the same + repository. Unlike `commiturl`, `pushurl` is a base path. If + either `commiturl` or `pushurl` could be used, `commiturl` + takes precedence. + +`svn-remote..rewriteRoot`:: + Create repositories from alternate URLs. For example, an administrator + could run `git svn` on the server locally (accessing via `file://`) but + wish to distribute the repository with a public `http://` or `svn://` URL + in the metadata so users of it will see the public URL. + +`svn-remote..rewriteUUID`:: + Remap the UUID manually, similar to the `useSvmProps` option. + This may be useful in situations where the original UUID is not available + via either `useSvmProps` or `useSvnsyncProps`. diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc index 0c2ce385c45cc5..76b9b807d157f4 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -8,55 +8,57 @@ git-fast-export - Git data exporter SYNOPSIS -------- -[verse] -'git fast-export' [] [] [[--] ...] +[synopsis] +git fast-export [] [] [[--] ...] 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 format that can be edited before being -fed to 'git fast-import' in order to do history rewrites (an ability -relied on by tools like 'git filter-repo'). +fed to `git fast-import` in order to do history rewrites (an ability +relied on by tools like `git filter-repo`). OPTIONS ------- ---progress=:: - Insert 'progress' statements every objects, to be shown by - 'git fast-import' during import. +`--progress=`:: + Insert `progress` statements every __ objects, to be shown by + `git fast-import` during import. ---signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort):: +`--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)`:: Specify how to handle signed tags. Since any transformation after the export (or during the export, such as excluding revisions) can change the hashes being signed, the signatures may become invalid. + -When asking to 'abort' (which is the default), this program will die -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-verbatim' (or 'warn', a deprecated synonym), -they will be exported, but you will see a warning. 'verbatim' and -'warn-verbatim' should only be used if you know that no transformation +`abort`;; Die when encountering a signed tag. This is the default. +`strip`;; Silently make signed tags unsigned. +`warn-strip`;; Make signed tags unsigned and display a warning. +`verbatim`;; Silently export signed tags. +`warn-verbatim` (or `warn`, a deprecated synonym);; Export signed tags and +display a warning. ++ +Use `verbatim` and `warn-verbatim` only if you know that no transformation affecting tags or any commit in their history will be performed by you -or by fast-export or fast-import, or if you do not care that the +or by `git fast-export` or `git fast-import`, or if you do not care that the resulting tag will have an invalid signature. ---signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort):: +`--signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort)`:: Specify how to handle signed commits. Behaves exactly as - '--signed-tags', but for commits. Default is 'strip', which + `--signed-tags`, but for commits. Default is `strip`, which is the same as how earlier versions of this command without this option behaved. + When exported, a signature starts with: + +[synopsis] gpgsig + -where is the Git object hash so either "sha1" or -"sha256", and is the signature type, so "openpgp", -"x509", "ssh" or "unknown". +where __ is the Git object hash so either `sha1` or +`sha256`, and __ is the signature type, so `openpgp`, +`x509`, `ssh` or `unknown`. + For example, an OpenPGP signature on a SHA-1 commit starts with `gpgsig sha1 openpgp`, while an SSH signature on a SHA-256 commit @@ -70,19 +72,19 @@ Git hash algorithm in each commit. NOTE: This is highly experimental and the format of the data stream may change in the future without compatibility guarantees. ---tag-of-filtered-object=(abort|drop|rewrite):: +`--tag-of-filtered-object=(abort|drop|rewrite)`:: 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. + -When asking to 'abort' (which is the default), this program will die -when encountering such a tag. With 'drop' it will omit such tags from -the output. With 'rewrite', if the tagged object is a commit, it will -rewrite the tag to tag an ancestor commit (via parent rewriting; see -linkgit:git-rev-list[1]). - --M:: --C:: +`abort`;; Die when encountering a tag whose tagged object is filtered out. +This is the default. +`drop`;; Omit filtered tags from the output. +`rewrite`;; Rewrite a tag to tag an ancestor commit if the tagged object is a +commit (via parent rewriting; see linkgit:git-rev-list[1]). + +`-M`:: +`-C`:: Perform move and/or copy detection, as described in the linkgit:git-diff[1] manual page, and use it to generate rename and copy commands in the output dump. @@ -90,26 +92,26 @@ linkgit:git-rev-list[1]). Note that earlier versions of this command did not complain and produced incorrect results if you gave these options. ---export-marks=:: - Dumps the internal marks table to when complete. +`--export-marks=`:: + Dump the internal marks table to __ when complete. Marks are written one per line as `:markid SHA-1`. 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 is only opened and truncated + incremental runs. As __ 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=:: - Before processing any input, load the marks specified in - . The input file must exist, must be readable, and - must use the same format as produced by --export-marks. +`--import-marks=`:: + Load the marks specified in __ before processing any input. + The input file must exist, must be readable, and + must use the same format as produced by `--export-marks`. ---mark-tags:: - In addition to labelling blobs and commits with mark ids, also - label tags. This is useful in conjunction with +`--mark-tags`:: + Label tags with mark ids in addition of blobs and commits. + This is useful in conjunction with `--export-marks` and `--import-marks`, 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 @@ -117,21 +119,21 @@ produced incorrect results if you gave these options. identifiers. + Any commits (or tags) that have already been marked will not be -exported again. If the backend uses a similar --import-marks file, +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. ---fake-missing-tagger:: - Some old repositories have tags without a tagger. The +`--fake-missing-tagger`:: + Fake a tagger for tags from old repositories that do not have one. 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 + allow that. This allows `git fast-import` to import the output. ---use-done-feature:: - Start the stream with a 'feature done' stanza, and terminate - it with a 'done' command. +`--use-done-feature`:: + Start the stream with a `feature done` stanza, and terminate + it with a `done` command. ---no-data:: +`--no-data`:: 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 @@ -139,53 +141,54 @@ by keeping the marks the same across runs. resulting stream can only be used by a repository which already contains the necessary objects. ---full-tree:: - This option will cause fast-export to issue a "deleteall" +`--full-tree`:: + 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`:: Anonymize the contents of the repository while still retaining the shape of the history and stored tree. See the section on - <> below. - ---anonymize-map=[:]:: - Convert token `` to `` in the anonymized output. If - `` is omitted, map `` to itself (i.e., do not - anonymize it). See the section on <> below. - ---reference-excluded-parents:: - By default, running a command such as `git fast-export - master~5..master` will not include the commit master{tilde}5 - and will make master{tilde}4 no longer have master{tilde}5 as - a parent (though both the old master{tilde}4 and new - master{tilde}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 + <> below. + +`--anonymize-map=[:]`:: + Convert token __ to __ in the anonymized output. If + __ is omitted, map __ to itself (i.e., do not + anonymize it). See the section on <> below. + +`--reference-excluded-parents`:: + Have the stream refer to commits in the excluded range of history by their SHA-1 object + name instead of rewriting their parent references. By default, running + a command such as `git fast-export master~5..master` 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). Note that the resulting stream + can only be used by a repository which already contains the necessary parent commits. ---show-original-ids:: +`--show-original-ids`:: Add an extra directive to the output for commits and blobs, `original-oid `. While such directives will likely be - ignored by importers such as git-fast-import, it may be useful + 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). ---reencode=(yes|no|abort):: +`--reencode=(yes|no|abort)`:: Specify how to handle `encoding` header in commit objects. When - asking to 'abort' (which is the default), this program will die - when encountering such a commit object. With 'yes', the commit - message will be re-encoded into UTF-8. With 'no', the original - encoding will be preserved. + asking to one of the following values: ++ +`abort`;; Die when encountering a commit object with an `encoding` header. +This is the default. +`yes`;; Re-encode the commit message into UTF-8. +`no`;; Preserve the original encoding. ---refspec:: +`--refspec`:: Apply the specified refspec to each ref exported. Multiple of them can be specified. -[...]:: +`...`:: 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 @@ -197,26 +200,26 @@ by keeping the marks the same across runs. EXAMPLES -------- -------------------------------------------------------------------- +---- $ git fast-export --all | (cd /empty/repository && git fast-import) -------------------------------------------------------------------- +---- 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. ------------------------------------------------------ +---- $ git fast-export master~5..master | sed "s|refs/heads/master|refs/heads/other|" | git fast-import ------------------------------------------------------ +---- -This makes a new branch called 'other' from 'master~5..master' -(i.e. if 'master' has linear history, it will take the last 5 commits). +This makes a new branch called `other` from `master~5..master` +(i.e. if `master` has linear history, it will take the last 5 commits). Note that this assumes that none of the blobs and commit messages referenced by that revision range contains the string -'refs/heads/master'. +`refs/heads/master`. [[ANONYMIZING]] @@ -245,20 +248,20 @@ 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 @@ -266,9 +269,9 @@ 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' stream ---------------------------------------------------- +---- After importing the stream, you can then run `git rev-list foo -- bar.c` in the anonymized repository. @@ -303,7 +306,7 @@ final pathname would be `publicdir/bar.c`. LIMITATIONS ----------- -Since 'git fast-import' cannot tag trees, you will not be +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. diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index 5201e493345a85..9a3f83b2b96598 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -8,15 +8,15 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- -[verse] -'git fast-import' [] +[synopsis] +git fast-import [] DESCRIPTION ----------- This program is usually not what the end user wants to run directly. Most end users want to use one of the existing frontend programs, which parses a specific type of foreign source and feeds the contents -stored there to 'git fast-import'. +stored there to `git fast-import`. fast-import reads a mixed command/data stream from standard input and writes one or more packfiles directly into the current repository. @@ -25,7 +25,7 @@ updated branch and tag refs, fully updating the current repository with the newly imported data. The fast-import backend itself can import into an empty repository (one that -has already been initialized by 'git init') or incrementally +has already been initialized by `git init`) or incrementally update an existing populated repository. Whether or not incremental imports are supported from a particular foreign source depends on the frontend program in use. @@ -35,24 +35,24 @@ the frontend program in use. OPTIONS ------- ---force:: +`--force`:: Force updating modified existing branches, even if doing so would cause commits to be lost (as the new commit does not contain the old commit). ---quiet:: - Disable the output shown by --stats, making fast-import usually +`--quiet`:: + Disable the output shown by `--stats`, making fast-import usually be silent when it is successful. However, if the import stream has directives intended to show user output (e.g. `progress` directives), the corresponding messages will still be shown. ---stats:: +`--stats`:: Display some basic statistics about the objects fast-import has created, the packfiles they were stored into, and the memory used by fast-import during this run. Showing this output - is currently the default, but can be disabled with --quiet. + is currently the default, but can be disabled with `--quiet`. ---allow-unsafe-features:: +`--allow-unsafe-features`:: Many command-line options can be provided as part of the fast-import stream itself by using the `feature` or `option` commands. However, some of these options are unsafe (e.g., @@ -85,43 +85,41 @@ already trusted to run their own code. the default mode is `verbatim`. `--signed-commits=`:: - Specify how to handle signed commits. The following s + Specify how to handle signed commits. The following __s are supported: + -* `verbatim`, which is the default, will silently import commit - signatures. -* `warn-verbatim` will import them, but will display a warning. -* `abort` will make this program die when encountering a signed - commit. -* `strip` will silently make the commits unsigned. -* `warn-strip` will make them unsigned, but will display a warning. -* `strip-if-invalid` will check signatures and, if they are invalid, - will strip them and display a warning. The validation is performed - in the same way as linkgit:git-verify-commit[1] does it. -* `sign-if-invalid[=]`, similar to `strip-if-invalid`, verifies - commit signatures and replaces invalid signatures with newly created ones. - Valid signatures are left unchanged. If `` is provided, that key is - used for signing; otherwise the configured default signing key is used. -* `abort-if-invalid` will make this program die when encountering a signed - commit that is unable to be verified. +`verbatim`;; Silently import commit signatures. This is the default. +`warn-verbatim`;; Import commit signatures, but display a warning. +`abort`;; Die when encountering a signed commit. +`strip`;; Silently make the commits unsigned. +`warn-strip`;; Make the commits unsigned, but display a warning. +`strip-if-invalid`;; Check signatures and, if they are invalid, strip them +and display a warning. Perform the validation in the same way as +linkgit:git-verify-commit[1]. +`sign-if-invalid[=]`;; Verify commit signatures and replace invalid +signatures with newly created ones. Leave valid signatures unchanged. If +__ is provided, use that key for signing; otherwise use the configured +default signing key. +`abort-if-invalid`;; Die when encountering a signed commit that cannot be +verified. Options for Frontends ~~~~~~~~~~~~~~~~~~~~~ ---cat-blob-fd=:: +`--cat-blob-fd=`:: Write responses to `get-mark`, `cat-blob`, and `ls` queries to the - file descriptor instead of `stdout`. Allows `progress` + file descriptor __ instead of `stdout`. Allows `progress` output intended for the end-user to be separated from other output. ---date-format=:: +`--date-format=`:: Specify the type of dates the frontend will supply to fast-import within `author`, `committer` and `tagger` commands. - See ``Date Formats'' below for details about which formats + See the 'Date Formats' section below for details about which formats are supported, and their syntax. ---done:: - Terminate with error if there is no `done` command at the end of +`--done`:: + Terminate with an error if there is no `done` command at the end of the stream. This option might be useful for detecting errors that cause the frontend to terminate before it has started to write a stream. @@ -129,52 +127,52 @@ Options for Frontends Locations of Marks Files ~~~~~~~~~~~~~~~~~~~~~~~~ ---export-marks=:: - Dumps the internal marks table to when complete. +`--export-marks=`:: + Dump the internal marks table to __ when complete. Marks are written one per line as `:markid SHA-1`. Frontends can use this file to validate imports after they have been completed, or to save the marks table across - incremental runs. As is only opened and truncated + incremental runs. As __ is only opened and truncated at checkpoint (or completion) the same path can also be - safely given to --import-marks. + safely given to `--import-marks`. ---import-marks=:: - Before processing any input, load the marks specified in - . The input file must exist, must be readable, and - must use the same format as produced by --export-marks. +`--import-marks=`:: + Load the marks specified in __ before processing any input. + The input file must exist, must be readable, and + must use the same format as produced by `--export-marks`. Multiple options may be supplied to import more than one set of marks. If a mark is defined to different values, the last file wins. ---import-marks-if-exists=:: - Like --import-marks but instead of erroring out, silently +`--import-marks-if-exists=`:: + Load marks like `--import-marks` but, instead of erroring out, silently skips the file if it does not exist. ---relative-marks:: ---no-relative-marks:: - After specifying --relative-marks the paths specified - with --import-marks= and --export-marks= are relative +`--relative-marks`:: +`--no-relative-marks`:: + Make the paths specified with `--import-marks=` and `--export-marks=` relative to an internal directory in the current repository. - In git-fast-import this means that the paths are relative - to the .git/info/fast-import directory. However, other + In `git-fast-import` this means that the paths are relative + to the `.git/info/fast-import` directory. However, other importers may use a different location. + -Relative and non-relative marks may be combined by interweaving ---(no-)-relative-marks with the --(import|export)-marks= options. +Combine relative and non-relative marks by interweaving +`--(no-)-relative-marks` with the `--(import|export)-marks=` options. Submodule Rewriting ~~~~~~~~~~~~~~~~~~~ ---rewrite-submodules-from=::: ---rewrite-submodules-to=::: - Rewrite the object IDs for the submodule specified by from the values - used in the from to those used in the to . The from marks should + +`--rewrite-submodules-from=:`:: +`--rewrite-submodules-to=:`:: + Rewrite the object IDs for the submodule specified by __ from the values + used in the from __ to those used in the to __. The from marks should have been created by `git fast-export`, and the to marks should have been created by `git fast-import` when importing that same submodule. + - may be any arbitrary string not containing a colon character, but the +__ may be any arbitrary string not containing a colon character, but the same value must be used with both options when specifying corresponding marks. -Multiple submodules may be specified with different values for . It is an +Multiple submodules may be specified with different values for __. It is an error not to use these options in corresponding pairs. + These options are primarily useful when converting a repository from one hash @@ -185,34 +183,34 @@ algorithm. Performance and Compression Tuning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---active-branches=:: - Maximum number of branches to maintain active at once. - See ``Memory Utilization'' below for details. Default is 5. +`--active-branches=`:: + Maintain at most __ branches as active at once. + See the 'Memory Utilization' section below for details. The default is 5. ---big-file-threshold=:: - Maximum size of a blob that fast-import will attempt to +`--big-file-threshold=`:: + Set the maximum size of a blob that fast-import will attempt to create a delta for, expressed in bytes. The default is 512m (512 MiB). Some importers may wish to lower this on systems with constrained memory. ---depth=:: - Maximum delta depth, for blob and tree deltification. +`--depth=`:: + Set the maximum delta depth for blob and tree deltification. Default is 50. ---export-pack-edges=:: - After creating a packfile, print a line of data to - listing the filename of the packfile and the last +`--export-pack-edges=`:: + Print a line of data to + __ listing the filename of the packfile and the last commit on each branch that was written to that packfile. This information may be useful after importing projects whose total object set exceeds the 4 GiB packfile limit, as these commits can be used as edge points during calls - to 'git pack-objects'. + to `git pack-objects`. ---max-pack-size=:: - Maximum size of each output packfile. +`--max-pack-size=`:: + Set the maximum size of each output packfile. The default is unlimited. -fastimport.unpackLimit:: +`fastimport.unpackLimit`:: See linkgit:git-config[1] PERFORMANCE @@ -243,9 +241,9 @@ an ideal situation, given that most conversion tools are throw-away PARALLEL OPERATION ------------------ -Like 'git push' or 'git fetch', imports handled by fast-import are safe to +Like `git push` or `git fetch`, imports handled by fast-import are safe to run alongside parallel `git repack -a -d` or `git gc` invocations, -or any other Git operation (including 'git prune', as loose objects +or any other Git operation (including `git prune`, as loose objects are never used by fast-import). fast-import does not lock the branch or tag refs it is actively importing. @@ -257,8 +255,8 @@ fast-forward update, fast-import will skip updating that ref and instead prints a warning message. fast-import will always attempt to update all branch refs, and does not stop on the first failure. -Branch updates can be forced with --force, but it's recommended that -this only be used on an otherwise quiet repository. Using --force +Branch updates can be forced with `--force`, but it's recommended that +this only be used on an otherwise quiet repository. Using `--force` is not necessary for an initial import into an empty repository. @@ -309,11 +307,11 @@ Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the --date-format= command-line option. +in the `--date-format=` command-line option. `raw`:: This is the Git native format and is `