summaryrefslogtreecommitdiff
path: root/Documentation/git-fast-import.txt
AgeCommit message (Collapse)AuthorFilesLines
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>
2007-02-07Teach fast-import how to clear the internal branch content.Libravatar Shawn O. Pearce1-5/+31
Some frontends may not be able to (easily) keep track of which files are included in the branch, and which aren't. Performing this tracking can be tedious and error prone for the frontend to do, especially if its foreign data source cannot supply the changed path list on a per-commit basis. fast-import now allows a frontend to request that a branch's tree be wiped clean (reset to the empty tree) at the start of a commit, allowing the frontend to feed in all paths which belong on the branch. This is ideal for a tar-file importer frontend, for example, as the frontend just needs to reformat the tar data stream into a gfi data stream, which may be something a few Perl regexps can take care of. :) Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-07Minor timestamp related documentation corrections for fast-import.Libravatar Shawn O. Pearce1-7/+14
As discussed on the mailing list, the documentation used here was not quite accurate. Improve upon it. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-06S_IFLNK != 0140000Libravatar Junio C Hamano1-1/+1
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-06Don't do non-fastforward updates in fast-import.Libravatar Shawn O. Pearce1-5/+17
If fast-import is being used to update an existing branch of a repository, the user may not want to lose commits if another process updates the same ref at the same time. For example, the user might be using fast-import to make just one or two commits against a live branch. We now perform a fast-forward check during the ref updating process. If updating a branch would cause commits in that branch to be lost, we skip over it and display the new SHA1 to standard error. This new default behavior can be overridden with `--force`, like git-push and git-fetch. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-06Support RFC 2822 date parsing in fast-import.Libravatar Shawn O. Pearce1-10/+85
Since some frontends may be working with source material where the dates are only readily available as RFC 2822 strings, it is more friendly if fast-import exposes Git's parse_date() function to handle the conversion. This way the frontend doesn't need to perform the parsing itself. The new --date-format option to fast-import can be used by a frontend to select which format it will supply date strings in. The default is the standard `raw` Git format, which fast-import has always supported. Format rfc2822 can be used to activate the parse_date() function instead. Because fast-import could also be useful for creating new, current commits, the format `now` is also supported to generate the current system timestamp. The implementation of `now` is a trivial call to datestamp(), but is actually a whole whopping 3 lines so that fast-import can verify the frontend really meant `now`. As part of this change I have added validation of the `raw` date format. Prior to this change fast-import would accept anything in a `committer` command, even if it was seriously malformed. Now fast-import requires the '> ' near the end of the string and verifies the timestamp is formatted properly. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-06Minor fast-import documentation corrections.Libravatar Shawn O. Pearce1-14/+18
Corrected a couple of header markup lines which were shorter than the actual header, and made the `data` commands two formats into a named list, which matches how we document the two formats of the `M` command within a commit. Also tried to simplify the language about our decimal integer format; Linus pointed out I was probably being too specific at the cost of reduced readability. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-06Correct fast-import timezone documentation.Libravatar Shawn O. Pearce1-2/+2
Andy Parkins and Linus Torvalds both noticed that the description of the timezone was incorrect. Its not expressed in minutes. Its more like "hhmm", where "hh" is the number of hours and "mm" is the number of minutes shifted from GMT/UTC. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-06Remove --branch-log from fast-import.Libravatar Shawn O. Pearce1-7/+0
The --branch-log option and its associated code hasn't been used in several months, as its not really very useful for debugging fast-import or a frontend. I don't plan on supporting it in this state long-term, so I'm killing it now before it gets distributed to a wider audience. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2007-02-05Initial draft of fast-import documentation.Libravatar Shawn O. Pearce1-0/+655
This is a first pass at the manpage for git-fast-import. I have tried to cover the input format in extreme detail, creating a reference which is more detailed than the BNF grammar appearing in the header of fast-import.c. I have also covered some details about gfi's performance and memory utilization, as well as the average learning curve required to create a gfi frontend application (as it is far lower than it might appear on first glance). The documentation still lacks real example input streams, which may turn out to be difficult to format in asciidoc due to the blank lines which carry meaning within the format. Signed-off-by: Shawn O. Pearce <spearce@spearce.org>