From 48f714c92b3c76654711a2243bd34a67c4754780 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 7 Feb 2007 05:52:51 +0000 Subject: [PATCH] Autogenerated man pages for v1.5.0-rc3-175-g6506 --- man1/git-diff-stages.1 | 4 +- man1/git-fast-import.1 | 399 +++++++++++++++++++++++++++++++++++++++++ man1/git-resolve.1 | 4 +- man7/git.7 | 2 +- 4 files changed, 405 insertions(+), 4 deletions(-) create mode 100644 man1/git-fast-import.1 diff --git a/man1/git-diff-stages.1 b/man1/git-diff-stages.1 index c97a3c546..f6efaf5ec 100644 --- a/man1/git-diff-stages.1 +++ b/man1/git-diff-stages.1 @@ -2,7 +2,7 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-DIFF\-STAGES" "1" "02/04/2007" "" "" +.TH "GIT\-DIFF\-STAGES" "1" "02/07/2007" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -12,6 +12,8 @@ git\-diff\-stages \- Compares two merge stages in the index .SH "SYNOPSIS" \fIgit\-diff\-stages\fR [] [\&...] .SH "DESCRIPTION" +DEPRECATED and will be removed in 1.5.1. + Compares the content and mode of the blobs in two stages in an unmerged index file. .SH "OPTIONS" .TP diff --git a/man1/git-fast-import.1 b/man1/git-fast-import.1 new file mode 100644 index 000000000..251903dd0 --- /dev/null +++ b/man1/git-fast-import.1 @@ -0,0 +1,399 @@ +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "GIT\-FAST\-IMPORT" "1" "02/07/2007" "" "" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +git\-fast\-import \- Backend for fast Git data importers. +.SH "SYNOPSIS" +frontend | \fIgit\-fast\-import\fR [options] +.SH "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 (gfi). + +gfi reads a mixed command/data stream from standard input and writes one or more packfiles directly into the current repository. When EOF is received on standard input, fast import writes out updated branch and tag refs, fully updating the current repository with the newly imported data. + +The gfi backend itself can import into an empty repository (one that has already been initialized by \fBgit\-init\fR(1)) 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. +.SH "OPTIONS" +.TP +\-\-date\-format= +Specify the type of dates the frontend will supply to gfi within author, committer and tagger commands. See \(lqDate Formats\(rq below for details about which formats are supported, and their syntax. +.TP +\-\-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). +.TP +\-\-max\-pack\-size= +Maximum size of each output packfile, expressed in MiB. The default is 4096 (4 GiB) as that is the maximum allowed packfile size (due to file format limitations). Some importers may wish to lower this, such as to ensure the resulting packfiles fit on CDs. +.TP +\-\-depth= +Maximum delta depth, for blob and tree deltification. Default is 10. +.TP +\-\-active\-branches= +Maximum number of branches to maintain active at once. See \(lqMemory Utilization\(rq below for details. Default is 5. +.TP +\-\-export\-marks= +Dumps 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. +.SH "PERFORMANCE" +The design of gfi allows it to import large projects in a minimum amount of memory usage and processing time. Assuming the frontend is able to keep up with gfi and feed it a constant stream of data, import times for projects holding 10+ years of history and containing 100,000+ individual commits are generally completed in just 1\-2 hours on quite modest (~$2,000 USD) hardware. + +Most bottlenecks appear to be in foreign source data access (the source just cannot extract revisions fast enough) or disk IO (gfi writes as fast as the disk will take the data). Imports will run faster if the source data is stored on a different drive than the destination Git repository (due to less IO contention). +.SH "DEVELOPMENT COST" +A typical frontend for gfi tends to weigh in at approximately 200 lines of Perl/Python/Ruby code. Most developers have been able to create working importers in just a couple of hours, even though it is their first exposure to gfi, and sometimes even to Git. This is an ideal situation, given that most conversion tools are throw\-away (use once, and never look back). +.SH "PARALLEL OPERATION" +Like git\-push or git\-fetch, imports handled by gfi 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 are never used by gfi). + +gfi does not lock the branch or tag refs it is actively importing. After the import, during its ref update phase, gfi tests each existing branch ref to verify the update will be a fast\-forward update (the commit stored in the ref is contained in the new history of the commit to be written). If the update is not a fast\-forward update, gfi will skip updating that ref and instead prints a warning message. gfi will always attempt to update all branch refs, and does not stop on the first failure. + +Branch updates can be forced with \-\-force, but its recommended that this only be used on an otherwise quiet repository. Using \-\-force is not necessary for an initial import into an empty repository. +.SH "TECHNICAL DISCUSSION" +gfi tracks a set of branches in memory. Any branch can be created or modified at any point during the import process by sending a commit command on the input stream. This design allows a frontend program to process an unlimited number of branches simultaneously, generating commits in the order they are available from the source data. It also simplifies the frontend programs considerably. + +gfi does not use or alter the current working directory, or any file within it. (It does however update the current Git repository, as referenced by GIT_DIR.) Therefore an import frontend may use the working directory for its own purposes, such as extracting file revisions from the foreign source. This ignorance of the working directory also allows gfi to run very quickly, as it does not need to perform any costly file update operations when switching between branches. +.SH "INPUT FORMAT" +With the exception of raw file data (which Git does not interpret) the gfi input format is text (ASCII) based. This text based format simplifies development and debugging of frontend programs, especially when a higher level language such as Perl, Python or Ruby is being used. + +gfi is very strict about its input. Where we say SP below we mean \fBexactly\fR one space. Likewise LF means one (and only one) linefeed. Supplying additional whitespace characters will cause unexpected results, such as branch names or file names with leading or trailing spaces in their name, or early termination of gfi when it encounters unexpected input. +.SS "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. +.TP +raw +This is the Git native format and is