summaryrefslogtreecommitdiff
path: root/Documentation/git-fast-import.txt
AgeCommit message (Collapse)AuthorFilesLines
2010-07-05Documentation: link to gitrevisions rather than git-rev-parseLibravatar Michael J Gruber1-1/+1
Currently, whenever we need documentation for revisions and ranges, we link to the git-rev-parse man page, i.e. a plumbing man page, which has this along with the documentation of all rev-parse modes. Link to the new gitrevisions man page instead in all cases except - when the actual git-rev-parse command is referred to or - in very technical context (git-send-pack). Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-17fast-import: make default pack size unlimitedLibravatar Nicolas Pitre1-4/+1
Now that fast-import is creating packs with index version 2, there is no point limiting the pack size by default. A pack split will still happen if off_t is not sufficiently large to hold large offsets. While updating the doc, let's remove the "packfiles fit on CDs" suggestion. Pack files created by fast-import are still suboptimal and a 'git repack -a -f -d' or even 'git gc --aggressive' would be a pretty good idea before considering storage on CDs. Signed-off-by: Nicolas Pitre <nico@fluxnic.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-04fast-import: count --max-pack-size in bytesLibravatar Junio C Hamano1-2/+2
Similar in spirit to 07cf0f2 (make --max-pack-size argument to 'git pack-object' count in bytes, 2010-02-03) which made the option by the same name to pack-objects, this counts the pack size limit in bytes. In order not to cause havoc with people used to the previous megabyte scale an integer smaller than 8192 is interpreted in megabytes but the user gets a warning. Also a minimum size of 1 MiB is enforced to avoid an explosion of pack files. Signed-off-by: Junio C Hamano <gitster@pobox.com> Acked-by: Shawn O. Pearce <spearce@spearce.org> Acked-by: Nicolas Pitre <nico@fluxnic.net>
2010-02-02Merge branch 'sp/fast-import-large-blob'Libravatar Junio C Hamano1-0/+6
* sp/fast-import-large-blob: fast-import: Stream very large blobs directly to pack
2010-02-01Merge branch 'sp/maint-fast-import-large-blob' into sp/fast-import-large-blobLibravatar Junio C Hamano1-0/+6
* sp/maint-fast-import-large-blob: fast-import: Stream very large blobs directly to pack bash: don't offer remote transport helpers as subcommands Conflicts: fast-import.c
2010-02-01fast-import: Stream very large blobs directly to packLibravatar Shawn O. Pearce1-0/+6
If a blob is larger than the configured big-file-threshold, instead of reading it into a single buffer obtained from malloc, stream it onto the end of the current pack file. Streaming the larger objects into the pack avoids the 4+ GiB memory footprint that occurs when fast-import is processing 2+ GiB blobs. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-31Fix typos in technical documentation.Libravatar Ralf Wildenhues1-4/+4
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-20Merge remote branch 'remotes/trast-doc/for-next'Libravatar Junio C Hamano1-10/+10
* remotes/trast-doc/for-next: Documentation: spell 'git cmd' without dash throughout Documentation: format full commands in typewriter font Documentation: warn prominently against merging with dirty trees Documentation/git-merge: reword references to "remote" and "pull" Conflicts: Documentation/config.txt Documentation/git-config.txt Documentation/git-merge.txt
2010-01-17Merge branch 'sr/gfi-options'Libravatar Junio C Hamano1-0/+79
* sr/gfi-options: fast-import: add (non-)relative-marks feature fast-import: allow for multiple --import-marks= arguments fast-import: test the new option command fast-import: add option command fast-import: add feature command fast-import: put marks reading in its own function fast-import: put option parsing code in separate functions
2010-01-10Documentation: spell 'git cmd' without dash throughoutLibravatar Thomas Rast1-10/+10
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-12-31fast-import: Document author/committer/tagger name is optionalLibravatar Shawn O. Pearce1-3/+3
The fast-import parser does not validate that the author, committer or tagger name component contains both a name and an email address. Therefore the name component has always been optional. Correct the documentation to match the implementation. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-05fast-import: add (non-)relative-marks featureLibravatar Sverre Rabbelier1-0/+16
After specifying 'feature relative-marks' the paths specified with 'feature import-marks' and 'feature export-marks' are 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 importers may use a different location. Add 'feature non-relative-marks' to disable this behavior, this way it is possible to, for example, specify the import-marks location as relative, and the export-marks location as non-relative. Also add tests to verify this behavior. Cc: Daniel Barkalow <barkalow@iabervon.org> Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04fast-import: allow for multiple --import-marks= argumentsLibravatar Sverre Rabbelier1-1/+7
The --import-marks= option may be specified multiple times on the commandline and should result in all marks being read in. Only one import-marks feature may be specified in the stream, which is overriden by any --import-marks= commandline options. If one wishes to specify import-marks files in addition to the one specified in the stream, it is easy to repeat the stream option as a --import-marks= commandline option. Also verify this behavior with tests. Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04fast-import: add option commandLibravatar Sverre Rabbelier1-0/+32
This allows the frontend to specify any of the supported options as long as no non-option command has been given. This way the user does not have to include any frontend-specific options, but instead she can rely on the frontend to tell fast-import what it needs. Also factor out parsing of argv and have it execute when we reach the first non-option command, or after all commands have been read and no non-option command has been encountered. Non-git options are ignored, unrecognised options result in an error. Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-04fast-import: add feature commandLibravatar Sverre Rabbelier1-0/+25
This allows the fronted to require a specific feature to be supported by the backend, or abort. Also add support for four initial feature, date-format=, force=, import-marks=, export-marks=. Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-19fast-import: Add support for importing commit notesLibravatar Johan Herland1-6/+39
Introduce a 'notemodify' subcommand of the 'commit' command. This subcommand is similar to 'filemodify', except that no mode is supplied (all notes have mode 0644), and the path is set to the hex SHA1 of the given "comittish". This enables fast import of note objects along with their associated commits, since the notes can now be named using the mark references of their corresponding commits. The patch also includes a test case of the added functionality. Signed-off-by: Johan Herland <johan@herland.net> Acked-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-19Support gitlinks in fast-import.Libravatar Alexander Gavrilov1-0/+3
Currently fast-import/export cannot be used for repositories with submodules. This patch extends the relevant programs to make them correctly process gitlinks. Links can be represented by two forms of the Modify command: M 160000 SHA1 some/path which sets the link target explicitly, or M 160000 :mark some/path where the mark refers to a commit. The latter form can be used by importing tools to build all submodules simultaneously in one physical repository, and then simply fetch them apart. Signed-off-by: Alexander Gavrilov <angavrilov@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-05manpages: italicize git command names (which were in teletype font)Libravatar Jonathan Nieder1-10/+10
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-05manpages: fix bogus whitespaceLibravatar Jonathan Nieder1-1/+1
It's distracting. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation formatting and cleanupLibravatar Jonathan Nieder1-8/+8
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-4/+4
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-03-22fast-import: Document the effect of "merge" with no "from" in a commitLibravatar Eyvind Bernhardsen1-3/+8
The fast-import documentation currently does not document the behaviour of "merge" when there is no "from" in a commit. This patch adds a description of what happens: the commit is created with a parent, but no files. This behaviour is equivalent to "from" followed by "filedeleteall". Signed-off-by: Eyvind Bernhardsen <eyvind-git@orakel.ntnu.no> Acked-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-02-16Update fast-import documentation to discuss crash reportsLibravatar Shawn O. Pearce1-0/+87
Recent versions of fast-import will now dump information out upon crashing, making it possible for the frontend developer to review some state information and possibly restart the import from the point where it crashed. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-9/+9
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-08-24Documentation: Correct various misspellings and typos.Libravatar Brian Hetro1-9/+9
Fix minor typos throughout the documentation. Signed-off-by: Brian Hetro <whee@smaertness.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-08-19Allow frontends to bidirectionally communicate with fast-importLibravatar Shawn O. Pearce1-0/+39
The existing checkpoint command is very useful to force fast-import to dump the branches out to disk so that standard Git tools can access them and the objects they refer to. However there was not a way to know when fast-import had finished executing the checkpoint and it was safe to read those refs. The progress command can be used to make fast-import output any message of the frontend's choosing to standard out. The frontend can scan for these messages using select() or poll() to monitor a pipe connected to the standard output of fast-import. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-08-19Make trailing LF optional for all fast-import commandsLibravatar Shawn O. Pearce1-3/+8
For the same reasons as the prior change we want to allow frontends to omit the trailing LF that usually delimits commands. In some cases these just make the input stream more verbose looking than it needs to be, and its just simpler for the frontend developer to get started if our parser is slightly more lenient about where an LF is required and where it isn't. To make this optional LF feature work we now have to buffer up to one line of input in command_buf. This buffering can happen if we look at the current input command but don't recognize it at this point in the code. In such a case we need to "unget" the entire line, but we cannot depend upon the stdio library to let us do ungetc() for that many characters at once. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-08-19Make trailing LF following fast-import `data` commands optionalLibravatar Shawn O. Pearce1-1/+9
A few fast-import frontend developers have found it odd that we require the LF following a `data` command, especially in the exact byte count format. Technically we don't need this LF to parse the stream properly, but having it here does make the stream more readable to humans. We can easily make the LF optional by peeking at the next byte available from the stream and pushing it back into the buffer if its not LF. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-08-19Teach fast-import to ignore lines starting with '#'Libravatar Shawn O. Pearce1-0/+14
Several frontend developers have asked that some form of stream comments be permitted within a fast-import data stream. This way they can include information from their own frontend program about where specific data was taken from in the source system, or about a decision that their frontend may have made while creating the fast-import data stream. This change introduces comments in the Bourne-shell/Tcl/Perl style. Lines starting with '#' are ignored, up to and including the LF. Unlike the above mentioned three languages however we do not look for and ignore leading whitespace. This just simplifies the definition of the comment format and the code that parses them. To make comments work we had to stop using read_next_command() within cmd_data() and directly invoke read_line() during the inline variant of the function. This is necessary to retain any lines of the input data that might otherwise look like a comment to fast-import. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-07-15Teach fast-import to recursively copy files/directoriesLibravatar Shawn O. Pearce1-5/+35
Some source material (e.g. Subversion dump files) perform directory renames by telling us the directory was copied, then deleted in the same revision. This makes it difficult for a frontend to convert such data formats to a fast-import stream, as all the frontend has on hand is "Copy a/ to b/; Delete a/" with no details about what files are in a/, unless the frontend also kept track of all files. The new 'C' subcommand within a commit allows the frontend to make a recursive copy of one path to another path within the branch, without needing to keep track of the individual file paths. The metadata copy is performed in memory efficiently, but is implemented as a copy-immediately operation, rather than copy-on-write. With this new 'C' subcommand frontends could obviously implement an 'R' (rename) on their own as a combination of 'C' and 'D' (delete), but since we have already offered up 'R' in the past and it is a trivial thing to keep implemented I'm not going to deprecate it. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-07-10Correct trivial typo in fast-import documentationLibravatar Shawn O. Pearce1-1/+1
Rogan Dawes noticed I meant `filerename` here and not `filename`. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-07-09Support wholesale directory renames in fast-importLibravatar Shawn O. Pearce1-3/+25
Some source material (e.g. Subversion dump files) perform directory renames without telling us exactly which files in that subdirectory were moved. This makes it hard for a frontend to convert such data formats to a fast-import stream, as all the frontend has on hand is "Rename a/ to b/" with no details about what files are in a/, unless the frontend also kept track of all files. The new 'R' subcommand within a commit allows the frontend to rename either a file or an entire subdirectory, without needing to know the object's SHA-1 or the specific files contained within it. The rename is performed as efficiently as possible internally, making it cheaper than a 'D'/'M' pair for a file rename. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-07-09Merge branch 'maint'Libravatar Shawn O. Pearce1-3/+5
* maint: Clarify documentation of fast-import's D subcommand
2007-07-09Clarify documentation of fast-import's D subcommandLibravatar Shawn O. Pearce1-3/+5
The 'D' subcommand within a commit can also delete a directory recursively. This wasn't clear in the prior version of the documentation, leading to a question on the mailing list. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-06-07War on whitespaceLibravatar Junio C Hamano1-1/+0
This uses "git-apply --whitespace=strip" to fix whitespace errors that have crept in to our source files over time. There are a few files that need to have trailing whitespaces (most notably, test vectors). The results still passes the test, and build result in Documentation/ area is unchanged. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-05-09Fix documentation of tag in git-fast-import.txtLibravatar Richard P. Curnow1-1/+0
The tag command does not take a trailing LF. Signed-off-by: Richard P. Curnow <rc@rc0.org.uk> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-10Merge branch 'maint'Libravatar Junio C Hamano1-3/+3
* maint: git.el: Retrieve commit log information from .dotest directory. git.el: Avoid appending a signoff line that is already present. setup_git_directory_gently: fix off-by-one error user-manual: install user manual stylesheet with other web documents user-manual: fix rendering of history diagrams user-manual: fix missing colon in git-show example user-manual: fix inconsistent use of pull and merge user-manual: fix inconsistent example glossary: fix overoptimistic automatic linking of defined terms Documentation: s/seperator/separator/ Adjust reflog filemode in shared repository
2007-03-09Documentation: s/seperator/separator/Libravatar Jeff King1-3/+3
Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-03-07Allow fast-import frontends to reload the marks tableLibravatar Shawn O. Pearce1-1/+12
I'm giving fast-import a lesson on how to reload the marks table using the same format it outputs with --export-marks. This way a frontend can reload the marks table from a prior import, making incremental imports less painful. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-13Documentation: Drop full-stop from git-fast-import title.Libravatar Junio C Hamano1-1/+1
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-12fast-import: Support reusing 'from' and brown paper bag fix reset.Libravatar Shawn O. Pearce1-11/+10
It was suggested on the mailing list that being able to use `from` in any commit to reset the current branch is useful in some types of importers, such as a darcs importer. We originally did not permit resetting an existing branch with a new `from` command during a `commit` command, but this restriction was only to help debug the hacked up cvs2svn that Jon Smirl was developing in parallel with git-fast-import. It is probably more of a problem to disallow it than to allow it. So now we permit a `from` during any `commit`. While making the changes required to permit multiple `from` commands on the same branch, I discovered we no longer needed the last_commit field to be set to 0 during a reset, so that was removed. (Reset was originally setting the field to 0 to signal cmd_from() that it was OK to execute on the branch.) While poking around in this section of fast-import I also realized the `reset` command was not working as intended if the corresponding `from` command was omitted (as allowed by the BNF grammar and the code). If `from` was omitted we cleared out the tree but we left the tree SHA-1 and parent commit SHA-1 intact. This is not what the user intended in this case. Instead they would be trying to reset the branch to have no parent and to have no tree, making the branch look new-born during the next commit. We now clear these SHA-1 values during `reset`, ensuring the branch looks new-born if `from` does not get supplied. New test cases for these were also added. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-11fast-import: Add tip about importing renames.Libravatar Shawn O. Pearce1-0/+7
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-11fast-import: Hide the pack boundary commits by default.Libravatar Shawn O. Pearce1-0/+9
Most users don't need the pack boundary information that fast-import was printing to standard output, especially if they were calling it with --quiet. Those users who do want this information probably want it captured so they can go back and use it to repack the imported repository. So dumping the boundary commits to a log file makes more sense then printing them to standard output. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-08Correct spelling of fast-import in docs.Libravatar Shawn O. Pearce1-78/+78
Its spelled 'fast-import', not 'gfi'. Linus and Dscho have both recently pointed this out to me on the mailing list. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-08Correct some language in fast-import documentation.Libravatar Shawn O. Pearce1-5/+6
Minor documentation improvements, as suggested on the Git mailing list by Horst H. von Brand and Karl Hasselström. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-08Correct ^0 asciidoc syntax in fast-import docs.Libravatar Shawn O. Pearce1-2/+2
I wrote this documentation with asciidoc 7.1.2, but apparently asciidoc 8 assumes ^ means superscript. The solution was already documented in rev-parse's manpage and is to use {caret} instead. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-07Add a Tips and Tricks section to fast-import's manual.Libravatar Shawn O. Pearce1-0/+87
There has been some informative lessons learned in the gfi user community, and these really should be written down and documented for future generations of frontend developers. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-07Dump all refs and marks during a checkpoint in fast-import.Libravatar Shawn O. Pearce1-5/+19
If the frontend asks us to checkpoint (via the explicit checkpoint command) its probably because they are afraid the current import will crash/fail/whatever and want to make sure they can pickup from the last checkpoint. To do that sort of recovery, we will need the current tip of every branch and tag available at the next startup. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-07Teach fast-import how to sit quietly in the corner.Libravatar Shawn O. Pearce1-6/+18
Often users will be running fast-import from within a larger frontend process, and this may be a frequent periodic tool such as a future edition of `git-svn fetch`. We don't want to bombard users with our large stats output if they won't be interested in it, so `--quiet` is now an option to make gfi be more silent. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>