From: Junio C Hamano Date: Wed, 7 Feb 2007 17:47:49 +0000 (-0800) Subject: Merge branch 'ml/gitk' (early part) X-Git-Tag: v1.5.0-rc4~5 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/ecea1ed5fe18a00bfca546d20de8ed8759c35ff6?hp=0f57a31b4c7f8784b70535681a669b7746f38f1c Merge branch 'ml/gitk' (early part) * 'ml/gitk' (early part): gitk: Use show-ref instead of ls-remote Make gitk work reasonably well on Cygwin. gitk - remove trailing whitespace from a few lines. --- diff --git a/.gitignore b/.gitignore index a43444fb92..d99372afc4 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ git-diff-index git-diff-stages git-diff-tree git-describe +git-fast-import git-fetch git-fetch-pack git-findtags @@ -71,7 +72,6 @@ git-merge-tree git-merge-octopus git-merge-one-file git-merge-ours -git-merge-recur git-merge-recursive git-merge-resolve git-merge-stupid diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ce85d06c62..285781d9db 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -316,7 +316,6 @@ settings but I haven't tried, yet. mail.identity.id?.compose_html => false - Gnus ---- @@ -331,3 +330,20 @@ whitespaces (fatal in patches). Running 'C-u g' to display the message in raw form before using '|' to run the pipe can work this problem around. + +KMail +----- + +This should help you to submit patches inline using KMail. + +1) Prepare the patch as a text file. + +2) Click on New Mail. + +3) Go under "Options" in the Composer window and be sure that +"Word wrap" is not set. + +4) Use Message -> Insert file... and insert the patch. + +5) Back in the compose window: add whatever other text you wish to the +message, complete the addressing and subject fields, and press send. diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt index 120d14e87e..b8f45b8cdc 100644 --- a/Documentation/git-diff-stages.txt +++ b/Documentation/git-diff-stages.txt @@ -12,6 +12,8 @@ SYNOPSIS 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. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt new file mode 100644 index 0000000000..0b64d3348b --- /dev/null +++ b/Documentation/git-fast-import.txt @@ -0,0 +1,885 @@ +git-fast-import(1) +================== + +NAME +---- +git-fast-import - Backend for fast Git data importers. + + +SYNOPSIS +-------- +frontend | 'git-fast-import' [options] + +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 gitlink:git-init[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. + + +OPTIONS +------- +--date-format=:: + Specify the type of dates the frontend will supply to + gfi within `author`, `committer` and `tagger` commands. + See ``Date Formats'' below for details about which formats + are supported, and their syntax. + +--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). + +--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. + +--depth=:: + Maximum delta depth, for blob and tree deltification. + Default is 10. + +--active-branches=:: + Maximum number of branches to maintain active at once. + See ``Memory Utilization'' below for details. Default is 5. + +--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. + +--quiet:: + Disable all non-fatal output, making gfi silent when it + is successful. This option disables the output shown by + \--stats. + +--stats:: + Display some basic statistics about the objects gfi has + created, the packfiles they were stored into, and the + memory used by gfi during this run. Showing this output + is currently the default, but can be disabled with \--quiet. + + +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). + + +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). + + +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. + + +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. + +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 +*exactly* 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. + +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. + +`raw`:: + This is the Git native format and is `