diff options
Diffstat (limited to 'Documentation')
52 files changed, 1439 insertions, 191 deletions
diff --git a/Documentation/.gitattributes b/Documentation/.gitattributes new file mode 100644 index 0000000000..ddb030137d --- /dev/null +++ b/Documentation/.gitattributes @@ -0,0 +1 @@ +*.txt whitespace diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 3b042db624..994eb9159a 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -53,6 +53,18 @@ For shell scripts specifically (not exhaustive): - We do not write the noiseword "function" in front of shell functions. + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, + [::], [==], nor [..]) for portability. + + - We do not use \{m,n\}; + + - We do not use -E; + + - We do not use ? nor + (which are \{0,1\} and \{1,\} + respectively in BRE) but that goes without saying as these + are ERE elements not BRE (note that \? and \+ are not even part + of BRE -- making them accessible from BRE is a GNU extension). + For C programs: - We use tabs to indent, and interpret tabs as taking up to diff --git a/Documentation/RelNotes-1.5.5.txt b/Documentation/RelNotes-1.5.5.txt new file mode 100644 index 0000000000..2932212488 --- /dev/null +++ b/Documentation/RelNotes-1.5.5.txt @@ -0,0 +1,207 @@ +GIT v1.5.5 Release Notes +======================== + +Updates since v1.5.4 +-------------------- + +(subsystems) + + * Comes with git-gui 0.10.1 + +(portability) + + * We shouldn't ask for BSD group ownership semantics by setting g+s bit + on directories on older BSD systems that refuses chmod() by non root + users. BSD semantics is the default there anyway. + + * Bunch of portability improvement patches coming from an effort to port + to Solaris has been applied. + +(performance) + + * On platforms with suboptimal qsort(3) implementation, there + is an option to use more reasonable substitute we ship with + our software. + + * New configuration variable "pack.packsizelimit" can be used + in place of command line option --max-pack-size. + + * "git fetch" over the native git protocol used to make a + connection to find out the set of current remote refs and + another to actually download the pack data. We now use only + one connection for these tasks. + + * "git commit" does not run lstat(2) more than necessary + anymore. + +(usability, bells and whistles) + + * Bash completion script (in contrib) are aware of more commands and + options. + + * You can be warned when core.autocrlf conversion is applied in + such a way that results in an irreversible conversion. + + * A catch-all "color.ui" configuration variable can be used to + enable coloring of all color-capable commands, instead of + individual ones such as "color.status" and "color.branch". + + * The commands refused to take absolute pathnames where they + require pathnames relative to the work tree or the current + subdirectory. They now can take absolute pathnames in such a + case as long as the pathnames do not refer outside of the + work tree. E.g. "git add $(pwd)/foo" now works. + + * Error messages used to be sent to stderr, only to get hidden, + when $PAGER was in use. They now are sent to stdout along + with the command output to be shown in the $PAGER. + + * A pattern "foo/" in .gitignore file now matches a directory + "foo". Pattern "foo" also matches as before. + + * bash completion's prompt helper function can talk about + operation in-progress (e.g. merge, rebase, etc.). + + * Configuration variables "url.<usethis>.insteadof = <otherurl>" can be + used to tell "git-fetch" and "git-push" to use different URL than what + is given from the command line. + + * "git add -i" behaves better even before you make an initial commit. + + * "git am" refused to run from a subdirectory without a good reason. + + * After "git apply --whitespace=fix" fixes whitespace errors in a patch, + a line before the fix can appear as a context or preimage line in a + later patch, causing the patch not to apply. The command now knows to + see through whitespace fixes done to context lines to successfully + apply such a patch series. + + * "git branch" (and "git checkout -b") to branch from a local branch can + optionally set "branch.<name>.merge" to mark the new branch to build on + the other local branch, when "branch.autosetupmerge" is set to + "always", or when passing the command line option "--track" (this option + was ignored when branching from local branches). By default, this does + not happen when branching from a local branch. + + * "git checkout" to switch to a branch that has "branch.<name>.merge" set + (i.e. marked to build on another branch) reports how much the branch + and the other branch diverged. + + * When "git checkout" has to update a lot of paths, it used to be silent + for 4 seconds before it showed any progress report. It is now a bit + more impatient and starts showing progress report early. + + * "git commit" learned a new hook "prepare-commit-msg" that can + inspect what is going to be committed and prepare the commit + log message template to be edited. + + * "git cvsimport" can now take more than one -M options. + + * "git describe" learned to limit the tags to be used for + naming with --match option. + + * "git describe --contains" now barfs when the named commit + cannot be described. + + * "git describe --exact-match" describes only commits that are tagged. + + * "git describe --long" describes a tagged commit as $tag-0-$sha1, + instead of just showing the exact tagname. + + * "git describe" warns when using a tag whose name and path contradict + with each other. + + * "git diff" learned "--relative" option to limit and output paths + relative to the current directory when working in a subdirectory. + + * "git diff" learned "--dirstat" option to show birds-eye-summary of + changes more concisely than "--diffstat". + + * "git format-patch" learned --cover-letter option to generate a cover + letter template. + + * "git gc" learned --quiet option. + + * "git gc" now automatically prunes unreachable objects that are two + weeks old or older. + + * "git gc --auto" can be disabled more easily by just setting gc.auto + to zero. It also tolerates more packfiles by default. + + * "git grep" now knows "--name-only" is a synonym for the "-l" option. + + * "git help <alias>" now reports "'git <alias>' is alias to <what>", + instead of saying "No manual entry for git-<alias>". + + * "git help" can use different backends to show manual pages and this can + be configured using "man.viewer" configuration. + + * "gitk" does not restore window position from $HOME/.gitk anymore (it + still restores the size). + + * "git log --grep=<what>" learned "--fixed-strings" option to look for + <what> without treating it as a regular expression. + + * "git gui" learned an auto-spell checking. + + * "git push <somewhere> HEAD" and "git push <somewhere> +HEAD" works as + expected; they push the current branch (and only the current branch). + In addition, HEAD can be written as the value of "remote.<there>.push" + configuration variable. + + * When the configuration variable "pack.threads" is set to 0, "git + repack" auto detects the number of CPUs and uses that many threads. + + * "git send-email" learned to prompt for passwords + interactively. + + * "git send-email" learned an easier way to suppress CC + recipients. + + * "git stash" learned "pop" command, that applies the latest stash and + removes it from the stash, and "drop" command to discard the named + stash entry. + + * "git submodule" learned a new subcommand "summary" to show the + symmetric difference between the HEAD version and the work tree version + of the submodule commits. + + * Various "git cvsimport", "git cvsexportcommit", "git cvsserver", + "git svn" and "git p4" improvements. + +(internal) + + * Duplicated code between git-help and git-instaweb that + launches user's preferred browser has been refactored. + + * It is now easier to write test scripts that records known + breakages. + + * "git checkout" is rewritten in C. + + * "git remote" is rewritten in C. + + * Two conflict hunks that are separated by a very short span of common + lines are now coalesced into one larger hunk, to make the result easier + to read. + + * Run-command API's use of file descriptors is documented clearer and + is more consistent now. + + * diff output can be sent to FILE * that is different from stdout. This + will help reimplementing more things in C. + +Fixes since v1.5.4 +------------------ + +All of the fixes in v1.5.4 maintenance series are included in +this release, unless otherwise noted. + + * "git-http-push" did not allow deletion of remote ref with the usual + "push <remote> :<branch>" syntax. + + * "git-rebase --abort" did not go back to the right location if + "git-reset" was run during the "git-rebase" session. + + * "git imap-send" without setting imap.host did not error out but + segfaulted. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index de08d094e3..0e155c936c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -34,9 +34,9 @@ Checklist (and a short version for the impatient): - if your name is not writable in ASCII, make sure that you send off a message in the correct encoding. - send the patch to the list (git@vger.kernel.org) and the - maintainer (gitster@pobox.com). If you use - git-send-email(1), please test it first by sending - email to yourself. + maintainer (gitster@pobox.com) if (and only if) the patch + is ready for inclusion. If you use git-send-email(1), + please test it first by sending email to yourself. Long version: @@ -112,7 +112,12 @@ lose tabs that way if you are not careful. It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other -e-mail discussions. +e-mail discussions. Use of additional markers after PATCH and +the closing bracket to mark the nature of the patch is also +encouraged. E.g. [PATCH/RFC] is often used when the patch is +not ready to be applied but it is for discussion, [PATCH v2], +[PATCH v3] etc. are often seen when you are sending an update to +what you have previously sent. "git format-patch" command follows the best current practice to format the body of an e-mail message. At the beginning of the @@ -157,7 +162,8 @@ Note that your maintainer does not necessarily read everything on the git mailing list. If your patch is for discussion first, send it "To:" the mailing list, and optionally "cc:" him. If it is trivially correct or after the list reached a consensus, send -it "To:" the maintainer and optionally "cc:" the list. +it "To:" the maintainer and optionally "cc:" the list for +inclusion. Also note that your maintainer does not actively involve himself in maintaining what are in contrib/ hierarchy. When you send fixes and @@ -210,10 +216,53 @@ then you just add a line saying This line can be automatically added by git if you run the git-commit command with the -s option. -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. +Notice that you can place your own Signed-off-by: line when +forwarding somebody else's patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above). +Some people also put extra tags at the end. + +"Acked-by:" says that the patch was reviewed by the person who +is more familiar with the issues and the area the patch attempts +to modify. "Tested-by:" says the patch was tested by the person +and found to have the desired effect. + +------------------------------------------------ +An ideal patch flow + +Here is an ideal patch flow for this project the current maintainer +suggests to the contributors: + + (0) You come up with an itch. You code it up. + + (1) Send it to the list and cc people who may need to know about + the change. + + The people who may need to know are the ones whose code you + are butchering. These people happen to be the ones who are + most likely to be knowledgeable enough to help you, but + they have no obligation to help you (i.e. you ask for help, + don't demand). "git log -p -- $area_you_are_modifying" would + help you find out who they are. + + (2) You get comments and suggestions for improvements. You may + even get them in a "on top of your change" patch form. + + (3) Polish, refine, and re-send to the list and the people who + spend their time to improve your patch. Go back to step (2). + + (4) The list forms consensus that the last round of your patch is + good. Send it to the list and cc the maintainer. + + (5) A topic branch is created with the patch and is merged to 'next', + and cooked further and eventually graduates to 'master'. + +In any time between the (2)-(3) cycle, the maintainer may pick it up +from the list and queue it to 'pu', in order to make it easier for +people play with it without having to pick up and apply the patch to +their trees themselves. ------------------------------------------------ MUA specific hints diff --git a/Documentation/config.txt b/Documentation/config.txt index 531ec46e95..04c01c5fdc 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -139,6 +139,51 @@ core.autocrlf:: "text" (i.e. be subjected to the autocrlf mechanism) is decided purely based on the contents. +core.safecrlf:: + If true, makes git check if converting `CRLF` as controlled by + `core.autocrlf` is reversible. Git will verify if a command + modifies a file in the work tree either directly or indirectly. + For example, committing a file followed by checking out the + same file should yield the original file in the work tree. If + this is not the case for the current setting of + `core.autocrlf`, git will reject the file. The variable can + be set to "warn", in which case git will only warn about an + irreversible conversion but continue the operation. ++ +CRLF conversion bears a slight chance of corrupting data. +autocrlf=true will convert CRLF to LF during commit and LF to +CRLF during checkout. A file that contains a mixture of LF and +CRLF before the commit cannot be recreated by git. For text +files this is the right thing to do: it corrects line endings +such that we have only LF line endings in the repository. +But for binary files that are accidentally classified as text the +conversion can corrupt data. ++ +If you recognize such corruption early you can easily fix it by +setting the conversion type explicitly in .gitattributes. Right +after committing you still have the original file in your work +tree and this file is not yet corrupted. You can explicitly tell +git that this file is binary and git will handle the file +appropriately. ++ +Unfortunately, the desired effect of cleaning up text files with +mixed line endings and the undesired effect of corrupting binary +files cannot be distinguished. In both cases CRLFs are removed +in an irreversible way. For text files this is the right thing +to do because CRLFs are line endings, while for binary files +converting CRLFs corrupts data. ++ +Note, this safety check does not mean that a checkout will generate a +file identical to the original file for a different setting of +`core.autocrlf`, but only for the current one. For example, a text +file with `LF` would be accepted with `core.autocrlf=input` and could +later be checked out with `core.autocrlf=true`, in which case the +resulting file would contain `CRLF`, although the original file +contained `LF`. However, in both work trees the line endings would be +consistent, that is either all `LF` or all `CRLF`, but never mixed. A +file with mixed line endings would be reported by the `core.safecrlf` +mechanism. + core.symlinks:: If false, symbolic links are checked out as small plain files that contain the link text. linkgit:git-update-index[1] and @@ -308,6 +353,10 @@ core.whitespace:: error (enabled by default). * `indent-with-non-tab` treats a line that is indented with 8 or more space characters as an error (not enabled by default). +* `cr-at-eol` treats a carriage-return at the end of line as + part of the line terminator, i.e. with it, `trailing-space` + does not trigger if the character before such a carriage-return + is not a whitespace (not enabled by default). alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. @@ -330,10 +379,14 @@ apply.whitespace:: branch.autosetupmerge:: Tells `git-branch` and `git-checkout` to setup new branches - so that linkgit:git-pull[1] will appropriately merge from that - remote branch. Note that even if this option is not set, + so that linkgit:git-pull[1] will appropriately merge from the + starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` - and `--no-track` options. This option defaults to true. + and `--no-track` options. The valid settings are: `false` -- no + automatic setup is done; `true` -- automatic setup is done when the + starting point is a remote branch; `always` -- automatic setup is + done when the starting point is either a local branch or remote + branch. This option defaults to true. branch.<name>.remote:: When in branch <name>, it tells `git fetch` which remote to fetch. @@ -367,6 +420,11 @@ branch.<name>.rebase:: it unless you understand the implications (see linkgit:git-rebase[1] for details). +browser.<tool>.cmd:: + Specify the command to invoke the specified browser. The + specified command is evaluated in shell with the URLs passed + as arguments. (See linkgit:git-web--browse[1].) + browser.<tool>.path:: Override the path for the given tool that may be used to browse HTML help (see '-w' option in linkgit:git-help[1]) or a @@ -444,6 +502,13 @@ color.status.<slot>:: commit.template:: Specify a file to use as the template for new commit messages. +color.ui:: + When set to `always`, always use colors in all git commands which + are capable of colored output. When false (or `never`), never. When + set to `true` or `auto`, use colors only when the output is to the + terminal. When more specific variables of color.* are set, they always + take precedence over this setting. Defaults to false. + diff.autorefreshindex:: When using `git diff` to compare with work tree files, do not consider stat-only change as changed. @@ -496,6 +561,11 @@ format.suffix:: `.patch`. Use this variable to change that suffix (make sure to include the dot if you want it). +format.pretty:: + The default pretty format for log/show/whatchanged command, + See linkgit:git-log[1], linkgit:git-show[1], + linkgit:git-whatchanged[1]. + gc.aggressiveWindow:: The window size parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults @@ -512,7 +582,7 @@ gc.autopacklimit:: When there are more than this many packs that are not marked with `*.keep` file in the repository, `git gc --auto` consolidates them into one larger pack. The - default value is 20. Setting this to 0 disables it. + default value is 50. Setting this to 0 disables it. gc.packrefs:: `git gc` does not run `git pack-refs` in a bare repository by @@ -525,6 +595,10 @@ gc.packrefs:: at some stage, and setting this to `false` will continue to prevent `git pack-refs` from being run from `git gc`. +gc.pruneexpire:: + When `git gc` is run, it will call `prune --expire 2.weeks.ago`. + Override the grace period with this config variable. + gc.reflogexpire:: `git reflog expire` removes reflog entries older than this time; defaults to 90 days. @@ -587,6 +661,13 @@ gitcvs.dbuser, gitcvs.dbpass:: 'gitcvs.dbuser' supports variable substitution (see linkgit:git-cvsserver[1] for details). +gitcvs.dbTableNamePrefix:: + Database table name prefix. Prepended to the names of any + database tables used, allowing a single database to be used + for several repositories. Supports variable substitution (see + linkgit:git-cvsserver[1] for details). Any non-alphabetic + characters will be replaced with underscores. + All gitcvs variables except for 'gitcvs.allbinary' can also be specified as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one of "ext" and "pserver") to make them apply only for the given @@ -683,14 +764,20 @@ log.showroot:: Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which normally hide the root commit will now show it. True by default. +man.viewer:: + Specify the programs that may be used to display help in the + 'man' format. See linkgit:git-help[1]. + merge.summary:: Whether to include summaries of merged commits in newly created merge commit messages. False by default. merge.tool:: Controls which merge resolution program is used by - linkgit:git-mergetool[1]. Valid values are: "kdiff3", "tkdiff", - "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", and "opendiff". + linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", + "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", and + "opendiff". Any other value is treated is custom merge tool + and there must be a corresponing mergetool.<tool>.cmd option. merge.verbosity:: Controls the amount of output shown by the recursive merge @@ -717,6 +804,31 @@ mergetool.<tool>.path:: Override the path for the given tool. This is useful in case your tool is not in the PATH. +mergetool.<tool>.cmd:: + Specify the command to invoke the specified merge tool. The + specified command is evaluated in shell with the following + variables available: 'BASE' is the name of a temporary file + containing the common base of the files to be merged, if available; + 'LOCAL' is the name of a temporary file containing the contents of + the file on the current branch; 'REMOTE' is the name of a temporary + file containing the contents of the file from the branch being + merged; 'MERGED' contains the name of the file to which the merge + tool should write the results of a successful merge. + +mergetool.<tool>.trustExitCode:: + For a custom merge command, specify whether the exit code of + the merge command can be used to determine whether the merge was + successful. If this is not set to true then the merge target file + timestamp is checked and the merge assumed to have been successful + if the file has been updated, otherwise the user is prompted to + indicate the success of the merge. + +mergetool.keepBackup:: + After performing a merge, the original file with conflict markers + can be saved as a file with a `.orig` extension. If this variable + is set to `false` then this file is not preserved. Defaults to + `true` (i.e. keep the backup files). + pack.window:: The size of the window used by linkgit:git-pack-objects[1] when no window size is given on the command line. Defaults to 10. @@ -756,6 +868,8 @@ pack.threads:: warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and set the number of threads accordingly. pack.indexVersion:: Specify the default pack index version. Valid values are 1 for @@ -766,6 +880,12 @@ pack.indexVersion:: whenever the corresponding pack is larger than 2 GB. Otherwise the default is 1. +pack.packSizeLimit:: + The default maximum size of a pack. This setting only affects + packing to a file, i.e. the git:// protocol is unaffected. It + can be overridden by the `\--max-pack-size` option of + linkgit:git-repack[1]. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -835,6 +955,17 @@ tar.umask:: archiving user's umask will be used instead. See umask(2) and linkgit:git-archive[1]. +url.<base>.insteadOf:: + Any URL that starts with this value will be rewritten to + start, instead, with <base>. In cases where some site serves a + large number of repositories, and serves them with multiple + access methods, and some users need to use different access + methods, this feature allows people to specify any of the + equivalent URLs and have git automatically rewrite the URL to + the best alternative for the particular user, even for a + never-before-seen repository on the site. When more than one + insteadOf strings match a given URL, the longest match is used. + user.email:: Your email address to be recorded in any newly created commits. Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 8d35cbd60d..8dc5b001c4 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -170,6 +170,14 @@ endif::git-format-patch[] Swap two inputs; that is, show differences from index or on-disk file to tree contents. +--relative[=<path>]:: + When run from a subdirectory of the project, it can be + told to exclude changes outside the directory and show + pathnames relative to it with this option. When you are + not in a subdirectory (e.g. in a bare repository), you + can name which subdirectory to make the output relative + to by giving a <path> as an argument. + --text:: Treat all files as text. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index c751a17d07..35e67a06e4 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -226,6 +226,12 @@ diff:: This lets you review what will be committed (i.e. between HEAD and index). +Bugs +---- +The interactive mode does not work with files whose names contain +characters that need C-quoting. `core.quotepath` configuration can be +used to work this limitation around to some degree, but backslash, +double-quote and control characters will still have problems. See Also -------- diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index e640fc75cd..2387a8d6c2 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,7 +9,7 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8] +'git-am' [--signoff] [--keep] [--utf8 | --no-utf8] [--3way] [--interactive] [--binary] [--whitespace=<option>] [-C<n>] [-p<n>] <mbox>|<Maildir>... @@ -32,10 +32,6 @@ OPTIONS Add `Signed-off-by:` line to the commit message, using the committer identity of yourself. --d=<dir>, --dotest=<dir>:: - Instead of `.dotest` directory, use <dir> as a working - area to store extracted patches. - -k, --keep:: Pass `-k` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]). diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 7e8874acaa..6f07a17a2c 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -35,11 +35,10 @@ working tree to it; use "git checkout <newbranch>" to switch to the new branch. When a local branch is started off a remote branch, git sets up the -branch so that linkgit:git-pull[1] will appropriately merge from that -remote branch. If this behavior is not desired, it is possible to -disable it using the global `branch.autosetupmerge` configuration -flag. That setting can be overridden by using the `--track` -and `--no-track` options. +branch so that linkgit:git-pull[1] will appropriately merge from +the remote branch. This behavior may be changed via the global +`branch.autosetupmerge` configuration flag. That setting can be +overridden by using the `--track` and `--no-track` options. With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match @@ -105,20 +104,19 @@ OPTIONS Display the full sha1s in output listing rather than abbreviating them. --track:: - Set up configuration so that git-pull will automatically - retrieve data from the remote branch. Use this if you always - pull from the same remote branch into the new branch, or if you - don't want to use "git pull <repository> <refspec>" explicitly. - This behavior is the default. Set the - branch.autosetupmerge configuration variable to false if you - want git-checkout and git-branch to always behave as if - '--no-track' were given. + When creating a new branch, set up configuration so that git-pull + will automatically retrieve data from the start point, which must be + a branch. Use this if you always pull from the same upstream branch + into the new branch, and if you don't want to use "git pull + <repository> <refspec>" explicitly. This behavior is the default + when the start point is a remote branch. Set the + branch.autosetupmerge configuration variable to `false` if you want + git-checkout and git-branch to always behave as if '--no-track' were + given. Set it to `always` if you want this behavior when the + start-point is either a local or remote branch. --no-track:: - When a branch is created off a remote branch, - set up configuration so that git-pull will not retrieve data - from the remote branch, ignoring the branch.autosetupmerge - configuration variable. + Ignore the branch.autosetupmerge configuration variable. <branchname>:: The name of the branch to create or delete. diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 72f080a972..505ac056e6 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -99,36 +99,62 @@ Assume two repositories exist as R1 on machine A, and R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc). We want to update R2 with developments made on branch master in R1. + +To create the bundle you have to specify the basis. You have some options: + +- Without basis. ++ +This is useful when sending the whole history. + +------------ +$ git bundle create mybundle master +------------ + +- Using temporally tags. ++ We set a tag in R1 (lastR2bundle) after the previous such transport, and move it afterwards to help build the bundle. -in R1 on A: - ------------ $ git-bundle create mybundle master ^lastR2bundle $ git tag -f lastR2bundle master ------------ -(move mybundle from A to B by some mechanism) +- Using a tag present in both repositories + +------------ +$ git bundle create mybundle master ^v1.0.0 +------------ + +- A basis based on time. + +------------ +$ git bundle create mybundle master --since=10.days.ago +------------ -in R2 on B: +- With a limit on the number of commits ------------ -$ git-bundle verify mybundle -$ git-fetch mybundle refspec +$ git bundle create mybundle master -n 10 ------------ -where refspec is refInBundle:localRef +Then you move mybundle from A to B, and in R2 on B: +------------ +$ git-bundle verify mybundle +$ git-fetch mybundle master:localRef +------------ -Also, with something like this in your config: +With something like this in the config in R2: +------------------------ [remote "bundle"] url = /home/me/tmp/file.bdl fetch = refs/heads/*:refs/remotes/origin/* +------------------------ You can first sneakernet the bundle file to ~/tmp/file.bdl and -then these commands: +then these commands on machine B: ------------ $ git ls-remote bundle diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index b4cfa044bb..e11cddbfc9 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -3,7 +3,7 @@ git-checkout(1) NAME ---- -git-checkout - Checkout and switch to a branch +git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- @@ -48,21 +48,19 @@ OPTIONS may restrict the characters allowed in a branch name. --track:: - When -b is given and a branch is created off a remote branch, - set up configuration so that git-pull will automatically - retrieve data from the remote branch. Use this if you always - pull from the same remote branch into the new branch, or if you - don't want to use "git pull <repository> <refspec>" explicitly. - This behavior is the default. Set the - branch.autosetupmerge configuration variable to false if you - want git-checkout and git-branch to always behave as if - '--no-track' were given. + When creating a new branch, set up configuration so that git-pull + will automatically retrieve data from the start point, which must be + a branch. Use this if you always pull from the same upstream branch + into the new branch, and if you don't want to use "git pull + <repository> <refspec>" explicitly. This behavior is the default + when the start point is a remote branch. Set the + branch.autosetupmerge configuration variable to `false` if you want + git-checkout and git-branch to always behave as if '--no-track' were + given. Set it to `always` if you want this behavior when the + start-point is either a local or remote branch. --no-track:: - When -b is given and a branch is created off a remote branch, - set up configuration so that git-pull will not retrieve data - from the remote branch, ignoring the branch.autosetupmerge - configuration variable. + Ignore the branch.autosetupmerge configuration variable. -l:: Create the new branch's reflog. This activates recording of diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 488d873f43..4bb51cc06e 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -291,8 +291,8 @@ order). HOOKS ----- -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more +This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, +and `post-commit` hooks. See link:hooks.html[hooks] for more information. diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 6f91b9ea2a..58eefd42e5 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -102,13 +102,17 @@ If you need to pass multiple options, separate them with a comma. -m:: Attempt to detect merges based on the commit message. This option - will enable default regexes that try to capture the name source + will enable default regexes that try to capture the source branch name from the commit message. -M <regex>:: Attempt to detect merges based on the commit message with a custom regex. It can be used with '-m' to enable the default regexes as well. You must escape forward slashes. ++ +The regex must capture the source branch name in $1. ++ +This option can be used several times to provide several detection regexes. -S <regex>:: Skip paths matching the regex. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 0b6db864fa..b1106714b2 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -233,6 +233,11 @@ gitcvs.dbpass:: Database password. Only useful if setting `dbdriver`, since SQLite has no concept of database passwords. +gitcvs.dbTableNamePrefix:: + Database table name prefix. Supports variable substitution + (see below). Any non-alphabetic characters will be replaced + with underscores. + All variables can also be set per access method, see <<configaccessmethod,above>>. Variable substitution diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 0742152b81..d9aa2f2980 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -45,12 +45,30 @@ OPTIONS candidates to describe the input committish consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. + An <n> of 0 will cause only exact matches to be output. + +--exact-match:: + Only output exact matches (a tag directly references the + supplied commit). This is a synonym for --candidates=0. --debug:: Verbosely display information about the searching strategy being employed to standard error. The tag name will still be printed to standard out. +--long:: + Always output the long format (the tag, the number of commits + and the abbreviated commit name) even when it matches a tag. + This is useful when you want to see parts of the commit object name + in "describe" output, even when the commit in question happens to be + a tagged version. Instead of just emitting the tag name, it will + describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 + that points at object deadbeef....). + +--match <pattern>:: + Only consider tags matching the given pattern (can be used to avoid + leaking private tags made from the repository). + EXAMPLES -------- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index bd625ababf..c29a4f8126 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -385,6 +385,9 @@ new commit. Omitting the `from` command in the first commit of a new branch will cause fast-import to create that commit with no ancestor. This tends to be desired only for the initial commit of a project. +If the frontend creates all files from scratch when making a new +branch, a `merge` command may be used instead of `from` to start +the commit with an empty tree. Omitting the `from` command on existing branches is usually desired, as the current commit on that branch is automatically assumed to be the first ancestor of the new commit. @@ -427,13 +430,15 @@ existing value of the branch. `merge` ^^^^^^^ -Includes one additional ancestor commit, and makes the current -commit a merge commit. An unlimited number of `merge` commands per +Includes one additional ancestor commit. If the `from` command is +omitted when creating a new branch, the first `merge` commit will be +the first ancestor of the current commit, and the branch will start +out with no files. An unlimited number of `merge` commands per commit are permitted by fast-import, thereby establishing an n-way merge. However Git's other tools never create commits with more than 15 additional ancestors (forming a 16-way merge). For this reason it is suggested that frontends do not use more than 15 `merge` -commands per commit. +commands per commit; 16, if starting a new, empty branch. Here `<committish>` is any of the commit specification expressions also accepted by `from` (see above). @@ -805,6 +810,93 @@ Placing a `progress` command immediately after a `checkpoint` will inform the reader when the `checkpoint` has been completed and it can safely access the refs that fast-import updated. +Crash Reports +------------- +If fast-import is supplied invalid input it will terminate with a +non-zero exit status and create a crash report in the top level of +the Git repository it was importing into. Crash reports contain +a snapshot of the internal fast-import state as well as the most +recent commands that lead up to the crash. + +All recent commands (including stream comments, file changes and +progress commands) are shown in the command history within the crash +report, but raw file data and commit messages are excluded from the +crash report. This exclusion saves space within the report file +and reduces the amount of buffering that fast-import must perform +during execution. + +After writing a crash report fast-import will close the current +packfile and export the marks table. This allows the frontend +developer to inspect the repository state and resume the import from +the point where it crashed. The modified branches and tags are not +updated during a crash, as the import did not complete successfully. +Branch and tag information can be found in the crash report and +must be applied manually if the update is needed. + +An example crash: + +==== + $ cat >in <<END_OF_INPUT + # my very first test commit + commit refs/heads/master + committer Shawn O. Pearce <spearce> 19283 -0400 + # who is that guy anyway? + data <<EOF + this is my commit + EOF + M 644 inline .gitignore + data <<EOF + .gitignore + EOF + M 777 inline bob + END_OF_INPUT + + $ git-fast-import <in + fatal: Corrupt mode: M 777 inline bob + fast-import: dumping crash report to .git/fast_import_crash_8434 + + $ cat .git/fast_import_crash_8434 + fast-import crash report: + fast-import process: 8434 + parent process : 1391 + at Sat Sep 1 00:58:12 2007 + + fatal: Corrupt mode: M 777 inline bob + + Most Recent Commands Before Crash + --------------------------------- + # my very first test commit + commit refs/heads/master + committer Shawn O. Pearce <spearce> 19283 -0400 + # who is that guy anyway? + data <<EOF + M 644 inline .gitignore + data <<EOF + * M 777 inline bob + + Active Branch LRU + ----------------- + active_branches = 1 cur, 5 max + + pos clock name + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 1) 0 refs/heads/master + + Inactive Branches + ----------------- + refs/heads/master: + status : active loaded dirty + tip commit : 0000000000000000000000000000000000000000 + old tree : 0000000000000000000000000000000000000000 + cur tree : 0000000000000000000000000000000000000000 + commit clock: 0 + last pack : + + + ------------------- + END OF CRASH REPORT +==== + Tips and Tricks --------------- The following tips and tricks have been collected from various diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 2b8ffe5324..57598eb056 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -8,7 +8,7 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- -'git-fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] +'git-fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] [<host>:]<directory> [<refs>...] DESCRIPTION ----------- @@ -45,6 +45,12 @@ OPTIONS Spend extra cycles to minimize the number of objects to be sent. Use it on slower connection. +\--include-tag:: + If the remote side supports it, annotated tags objects will + be downloaded on the same connection as the other objects if + the object the tag references is downloaded. The caller must + otherwise determine the tags this option made available. + \--upload-pack=<git-upload-pack>:: Use this to specify the path to 'git-upload-pack' on the remote side, if is not found on your $PATH. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 543a1cf105..2a78549be5 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -25,7 +25,7 @@ Otherwise, all information (including original commit times or merge information) will be preserved. The command will only rewrite the _positive_ refs mentioned in the -command line (i.e. if you pass 'a..b', only 'b' will be rewritten). +command line (e.g. if you pass 'a..b', only 'b' will be rewritten). If you specify no filters, the commits will be recommitted without any changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, @@ -42,7 +42,7 @@ Always verify that the rewritten version is correct: The original refs, if different from the rewritten ones, will be stored in the namespace 'refs/original/'. -Note that since this operation is extensively I/O expensive, it might +Note that since this operation is very I/O expensive, it might be a good idea to redirect the temporary directory off-disk with the '-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable. @@ -51,14 +51,15 @@ Filters ~~~~~~~ The filters are applied in the order as listed below. The <command> -argument is always evaluated in shell using the 'eval' command (with the -notable exception of the commit filter, for technical reasons). +argument is always evaluated in the shell context using the 'eval' command +(with the notable exception of the commit filter, for technical reasons). Prior to that, the $GIT_COMMIT environment variable will be set to contain the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, -and GIT_COMMITTER_DATE are set according to the current commit. If any -evaluation of <command> returns a non-zero exit status, the whole operation -will be aborted. +and GIT_COMMITTER_DATE are set according to the current commit. The values +of these variables after the filters have run, are used for the new commit. +If any evaluation of <command> returns a non-zero exit status, the whole +operation will be aborted. A 'map' function is available that takes an "original sha1 id" argument and outputs a "rewritten sha1 id" if the commit has been already @@ -71,9 +72,9 @@ OPTIONS ------- --env-filter <command>:: - This is the filter for modifying the environment in which - the commit will be performed. Specifically, you might want - to rewrite the author/committer name/email/time environment + This filter may be used if you only need to modify the environment + in which the commit will be performed. Specifically, you might + want to rewrite the author/committer name/email/time environment variables (see linkgit:git-commit[1] for details). Do not forget to re-export the variables. @@ -149,7 +150,7 @@ definition impossible to preserve signatures at any rate.) -d <directory>:: Use this option to set the path to the temporary directory used for rewriting. When applying a tree filter, the command needs to - temporary checkout the tree to some directory, which may consume + temporarily check out the tree to some directory, which may consume considerable space in case of large projects. By default it does this in the '.git-rewrite/' directory but you can override that choice by this parameter. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 651efe6ca1..b5207b7604 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -10,13 +10,15 @@ SYNOPSIS -------- [verse] 'git-format-patch' [-k] [-o <dir> | --stdout] [--thread] - [--attach[=<boundary>] | --inline[=<boundary>]] - [-s | --signoff] [<common diff options>] - [-n | --numbered | -N | --no-numbered] - [--start-number <n>] [--numbered-files] - [--in-reply-to=Message-Id] [--suffix=.<sfx>] - [--ignore-if-in-upstream] - [--subject-prefix=Subject-Prefix] + [--attach[=<boundary>] | --inline[=<boundary>]] + [-s | --signoff] [<common diff options>] + [-n | --numbered | -N | --no-numbered] + [--start-number <n>] [--numbered-files] + [--in-reply-to=Message-Id] [--suffix=.<sfx>] + [--ignore-if-in-upstream] + [--subject-prefix=Subject-Prefix] + [--cc=<email>] + [--cover-letter] [ <since> | <revision range> ] DESCRIPTION @@ -135,6 +137,15 @@ include::diff-options.txt[] allows for useful naming of a patch series, and can be combined with the --numbered option. +--cc=<email>:: + Add a "Cc:" header to the email headers. This is in addition + to any configured headers, and may be used multiple times. + +--cover-letter:: + Generate a cover letter template. You still have to fill in + a description, but the shortlog and the diffstat will be + generated for you. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 4b2dfefa6a..d424a4ecbe 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,7 +8,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- -'git-gc' [--prune] [--aggressive] [--auto] +'git-gc' [--aggressive] [--auto] [--quiet] DESCRIPTION ----------- @@ -19,23 +19,19 @@ created from prior invocations of linkgit:git-add[1]. Users are encouraged to run this task on a regular basis within each repository to maintain good disk space utilization and good -operating performance. Some git commands may automatically run -`git-gc`; see the `--auto` flag below for details. +operating performance. + +Some git commands may automatically run `git-gc`; see the `--auto` flag +below for details. If you know what you're doing and all you want is to +disable this behavior permanently without further considerations, just do: + +---------------------- +$ git config --global gc.auto 0 +---------------------- OPTIONS ------- ---prune:: - Usually `git-gc` packs refs, expires old reflog entries, - packs loose objects, - and removes old 'rerere' records. Removal - of unreferenced loose objects is an unsafe operation - while other git operations are in progress, so it is not - done by default. Pass this option if you want it, and only - when you know nobody else is creating new objects in the - repository at the same time (e.g. never use this option - in a cron script). - --aggressive:: Usually 'git-gc' runs very quickly while providing good disk space utilization and performance. This option will cause @@ -63,6 +59,9 @@ are consolidated into a single pack by using the `-A` option of `git-repack`. Setting `gc.autopacklimit` to 0 disables automatic consolidation of packs. +--quiet:: + Suppress all progress reports. + Configuration ------------- @@ -101,6 +100,10 @@ the value, the more time is spent optimizing the delta compression. See the documentation for the --window' option in linkgit:git-repack[1] for more details. This defaults to 10. +The optional configuration variable 'gc.pruneExpire' controls how old +the unreferenced loose objects have to be before they are pruned. The +default is "2 weeks ago". + See Also -------- linkgit:git-prune[1] diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index f3cb24f252..a97f0557f4 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -75,9 +75,11 @@ OPTIONS -n:: Prefix the line number to matching lines. --l | --files-with-matches | -L | --files-without-match:: +-l | --files-with-matches | --name-only | -L | --files-without-match:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. + For better compatibility with git-diff, --name-only is a + synonym for --files-with-matches. -c | --count:: Instead of showing every matched line, show the number of diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index fb77ca3a57..be2ae53b90 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -33,45 +33,34 @@ OPTIONS option supersedes any other option. -i|--info:: - Use the 'info' program to display the manual page, instead of - the 'man' program that is used by default. + Display manual page for the command in the 'info' format. The + 'info' program will be used for that purpose. -m|--man:: - Use the 'man' program to display the manual page. This may be - used to override a value set in the 'help.format' - configuration variable. + Display manual page for the command in the 'man' format. This + option may be used to override a value set in the + 'help.format' configuration variable. ++ +By default the 'man' program will be used to display the manual page, +but the 'man.viewer' configuration variable may be used to choose +other display programs (see below). -w|--web:: - Use a web browser to display the HTML manual page, instead of - the 'man' program that is used by default. + Display manual page for the command in the 'web' (HTML) + format. A web browser will be used for that purpose. + The web browser can be specified using the configuration variable 'help.browser', or 'web.browser' if the former is not set. If none of -these config variables is set, the 'git-help--browse' helper script -(called by 'git-help') will pick a suitable default. -+ -You can explicitly provide a full path to your preferred browser by -setting the configuration variable 'browser.<tool>.path'. For example, -you can configure the absolute path to firefox by setting -'browser.firefox.path'. Otherwise, 'git-help--browse' assumes the tool -is available in PATH. -+ -Note that the script tries, as much as possible, to display the HTML -page in a new tab on an already opened browser. -+ -The following browsers are currently supported by 'git-help--browse': -+ -* firefox (this is the default under X Window when not using KDE) -* iceweasel -* konqueror (this is the default under KDE) -* w3m (this is the default outside X Window) -* links -* lynx -* dillo +these config variables is set, the 'git-web--browse' helper script +(called by 'git-help') will pick a suitable default. See +linkgit:git-web--browse[1] for more information about this. CONFIGURATION VARIABLES ----------------------- +help.format +~~~~~~~~~~~ + If no command line option is passed, the 'help.format' configuration variable will be checked. The following values are supported for this variable; they make 'git-help' behave as their corresponding command @@ -79,15 +68,47 @@ line option: * "man" corresponds to '-m|--man', * "info" corresponds to '-i|--info', -* "web" or "html" correspond to '-w|--web', +* "web" or "html" correspond to '-w|--web'. + +help.browser, web.browser and browser.<tool>.path +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also be checked if the 'web' format is chosen (either by command line option or configuration variable). See '-w|--web' in the OPTIONS -section above. +section above and linkgit:git-web--browse[1]. + +man.viewer +~~~~~~~~~~ + +The 'man.viewer' config variable will be checked if the 'man' format +is chosen. Only the following values are currently supported: + +* "man": use the 'man' program as usual, +* "woman": use 'emacsclient' to launch the "woman" mode in emacs +(this only works starting with emacsclient versions 22), +* "konqueror": use a man KIO slave in konqueror. + +Multiple values may be given to this configuration variable. Their +corresponding programs will be tried in the order listed in the +configuration file. + +For example, this configuration: + + [man] + viewer = konqueror + viewer = woman + +will try to use konqueror first. But this may fail (for example if +DISPLAY is not set) and in that case emacs' woman mode will be tried. + +If everything fails the 'man' program will be tried anyway. + +Note about git config --global +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note that these configuration variables should probably be set using -the '--global' flag, for example like this: +Note that all these configuration variables should probably be set +using the '--global' flag, for example like this: ------------------------------------------------ $ git config --global help.format web diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 72b5d00116..a7825b6144 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -75,6 +75,9 @@ OPTIONS to force the version for the generated pack index, and to force 64-bit index entries on objects located above the given offset. +--strict:: + Die, if the pack contains broken objects or links. + Note ---- diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 841e8fac7f..51f1532ef7 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -38,10 +38,11 @@ OPTIONS The port number to bind the httpd to. (Default: 1234) -b|--browser:: - - The web browser command-line to execute to view the gitweb page. - If blank, the URL of the gitweb instance will be printed to - stdout. (Default: 'firefox') + The web browser that should be used to view the gitweb + page. This will be passed to the 'git-web--browse' helper + script along with the URL of the gitweb instance. See + linkgit:git-web--browse[1] for more information about this. If + the script fails, the URL will be printed to stdout. --start:: Start the httpd instance and exit. This does not generate @@ -72,7 +73,8 @@ You may specify configuration in your .git/config ----------------------------------------------------------------------- If the configuration variable 'instaweb.browser' is not set, -'web.browser' will be used instead if it is defined. +'web.browser' will be used instead if it is defined. See +linkgit:git-web--browse[1] for more information about this. Author ------ diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 5d816d0d8b..19ee017aed 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- -'git-merge-index' [-o] [-q] <merge-program> (-a | \-- | <file>\*) +'git-merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*) DESCRIPTION ----------- diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 50f106ec5b..8ed44947ef 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -12,12 +12,12 @@ SYNOPSIS DESCRIPTION ----------- -Use 'git mergetool' to run one of several merge utilities to resolve +Use `git mergetool` to run one of several merge utilities to resolve merge conflicts. It is typically run after linkgit:git-merge[1]. If one or more <file> parameters are given, the merge tool program will be run to resolve differences on each file. If no <file> names are -specified, 'git mergetool' will run the merge tool program on every file +specified, `git mergetool` will run the merge tool program on every file with merge conflicts. OPTIONS @@ -27,16 +27,38 @@ OPTIONS Valid merge tools are: kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, and opendiff + -If a merge resolution program is not specified, 'git mergetool' -will use the configuration variable merge.tool. If the -configuration variable merge.tool is not set, 'git mergetool' +If a merge resolution program is not specified, `git mergetool` +will use the configuration variable `merge.tool`. If the +configuration variable `merge.tool` is not set, `git mergetool` will pick a suitable default. + You can explicitly provide a full path to the tool by setting the -configuration variable mergetool.<tool>.path. For example, you +configuration variable `mergetool.<tool>.path`. For example, you can configure the absolute path to kdiff3 by setting -mergetool.kdiff3.path. Otherwise, 'git mergetool' assumes the tool -is available in PATH. +`mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the +tool is available in PATH. ++ +Instead of running one of the known merge tool programs +`git mergetool` can be customized to run an alternative program +by specifying the command line to invoke in a configration +variable `mergetool.<tool>.cmd`. ++ +When `git mergetool` is invoked with this tool (either through the +`-t` or `--tool` option or the `merge.tool` configuration +variable) the configured command line will be invoked with `$BASE` +set to the name of a temporary file containing the common base for +the merge, if available; `$LOCAL` set to the name of a temporary +file containing the contents of the file on the current branch; +`$REMOTE` set to the name of a temporary file containing the +contents of the file to be merged, and `$MERGED` set to the name +of the file to which the merge tool should write the result of the +merge resolution. ++ +If the custom merge tool correctly indicates the success of a +merge resolution with its exit code then the configuration +variable `mergetool.<tool>.trustExitCode` can be set to `true`. +Otherwise, `git mergetool` will prompt the user to indicate the +success of the resolution after the custom tool has exited. Author ------ diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 74cc7c1cb8..3a1be08186 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -22,8 +22,9 @@ archive with specified base-name, or to the standard output. A packed archive is an efficient way to transfer set of objects between two repositories, and also is an archival format which is efficient to access. The packed archive format (.pack) is -designed to be unpackable without having anything else, but for -random access, accompanied with the pack index file (.idx). +designed to be self contained so that it can be unpacked without +any further information, but for fast, random access to the objects +in the pack, a pack index file (.idx) will be generated. Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) @@ -73,6 +74,11 @@ base-name:: as if all refs under `$GIT_DIR/refs` are specified to be included. +--include-tag:: + Include unasked-for annotated tags if the object they + reference was included in the resulting packfile. This + can be useful to send new tags to native git clients. + --window=[N], --depth=[N]:: These two options affect how the objects contained in the pack are stored using delta compression. The @@ -99,7 +105,8 @@ base-name:: --max-pack-size=<n>:: Maximum size of each output packfile, expressed in MiB. If specified, multiple packfiles may be created. - The default is unlimited. + The default is unlimited, unless the config variable + `pack.packSizeLimit` is set. --incremental:: This flag causes an object already in a pack ignored @@ -176,6 +183,8 @@ base-name:: This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and set the number of threads accordingly. --index-version=<version>[,<offset>]:: This is intended to be used by the test suite only. It allows diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index f7b90a326f..3405ca09e8 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -15,6 +15,7 @@ DESCRIPTION ----------- Runs `git-fetch` with the given parameters, and calls `git-merge` to merge the retrieved head(s) into the current branch. +With `--rebase`, calls `git-rebase` instead of `git-merge`. Note that you can use `.` (current directory) as the <repository> to pull from the local repository -- this is useful @@ -28,19 +29,14 @@ OPTIONS include::merge-options.txt[] :git-pull: 1 -include::fetch-options.txt[] - -include::pull-fetch-param.txt[] - -include::urls-remotes.txt[] - -include::merge-strategies.txt[] \--rebase:: Instead of a merge, perform a rebase after fetching. If there is a remote ref for the upstream branch, and this branch was rebased since last fetched, the rebase uses that information - to avoid rebasing non-local changes. + to avoid rebasing non-local changes. To make this the default + for branch `<name>`, set configuration `branch.<name>.rebase` + to `true`. + *NOTE:* This is a potentially _dangerous_ mode of operation. It rewrites history, which does not bode well when you @@ -50,6 +46,14 @@ unless you have read linkgit:git-rebase[1] carefully. \--no-rebase:: Override earlier \--rebase. +include::fetch-options.txt[] + +include::pull-fetch-param.txt[] + +include::urls-remotes.txt[] + +include::merge-strategies.txt[] + DEFAULT BEHAVIOUR ----------------- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index c11c6453ea..e0412e0866 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -9,6 +9,7 @@ SYNOPSIS -------- [verse] 'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] + [-s <strategy> | --strategy=<strategy>] [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>] 'git-rebase' --continue | --skip | --abort @@ -261,8 +262,7 @@ hook if one exists. You can use this hook to do sanity checks and reject the rebase if it isn't appropriate. Please see the template pre-rebase hook script for an example. -You must be in the top directory of your project to start (or continue) -a rebase. Upon completion, <branch> will be the current branch. +Upon completion, <branch> will be the current branch. INTERACTIVE MODE ---------------- diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index f9bba36c23..047e3ce14d 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -19,6 +19,8 @@ depending on the subcommand: git reflog expire [--dry-run] [--stale-fix] [--verbose] [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>... +git reflog delete ref@\{specifier\}... + git reflog [show] [log-options] [<ref>] Reflog is a mechanism to record when the tip of branches are @@ -43,6 +45,9 @@ two moves ago", `master@\{one.week.ago\}` means "where master used to point to one week ago", and so on. See linkgit:git-rev-parse[1] for more details. +To delete single entries from the reflog, use the subcommand "delete" +and specify the _exact_ entry (e.g. ``git reflog delete master@\{2\}''). + OPTIONS ------- @@ -75,6 +80,15 @@ them. --all:: Instead of listing <refs> explicitly, prune all refs. +--updateref:: + Update the ref with the sha1 of the top reflog entry (i.e. + <ref>@\{0\}) after expiring or deleting. + +--rewrite:: + While expiring or deleting, adjust each reflog entry to ensure + that the `old` sha1 field points to the `new` sha1 field of the + previous entry. + --verbose:: Print extra information on screen. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 5b96eabfce..d80cdf5502 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -20,6 +20,9 @@ SYNOPSIS [ \--full-history ] [ \--not ] [ \--all ] + [ \--branches ] + [ \--tags ] + [ \--remotes ] [ \--stdin ] [ \--quiet ] [ \--topo-order ] @@ -31,6 +34,7 @@ SYNOPSIS [ \--(author|committer|grep)=<pattern> ] [ \--regexp-ignore-case | \-i ] [ \--extended-regexp | \-E ] + [ \--fixed-strings | \-F ] [ \--date={local|relative|default|iso|rfc|short} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index f02f6bbb49..6513c2efe1 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -325,7 +325,7 @@ The lines after the separator describe the options. Each line of options has this format: ------------ -<opt_spec><arg_spec>? SP+ help LF +<opt_spec><flags>* SP+ help LF ------------ `<opt_spec>`:: @@ -334,10 +334,17 @@ Each line of options has this format: is necessary. `h,help`, `dry-run` and `f` are all three correct `<opt_spec>`. -`<arg_spec>`:: - an `<arg_spec>` tells the option parser if the option has an argument - (`=`), an optional one (`?` though its use is discouraged) or none - (no `<arg_spec>` in that case). +`<flags>`:: + `<flags>` are of `*`, `=`, `?` or `!`. + * Use `=` if the option takes an argument. + + * Use `?` to mean that the option is optional (though its use is discouraged). + + * Use `*` to mean that this option should not be listed in the usage + generated for the `-h` argument. It's shown for `--help-all` as + documented in linkgit:gitcli[5]. + + * Use `!` to not make the corresponding negated long option available. The remainder of the line, after stripping the spaces, is used as the help associated to the option. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 0554f2b374..9d0a10c562 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -96,11 +96,40 @@ The --cc option must be repeated for each user you want on the cc list. servers typically listen to smtp port 25 and ssmtp port 465). ---smtp-user, --smtp-pass:: - Username and password for SMTP-AUTH. Defaults are the values of - the configuration values 'sendemail.smtpuser' and - 'sendemail.smtppass', but see also 'sendemail.identity'. - If not set, authentication is not attempted. +--smtp-user:: + Username for SMTP-AUTH. In place of this option, the following + configuration variables can be specified: ++ +-- + * sendemail.smtpuser + * sendemail.<identity>.smtpuser (see sendemail.identity). +-- ++ +However, --smtp-user always overrides these variables. ++ +If a username is not specified (with --smtp-user or a +configuration variable), then authentication is not attempted. + +--smtp-pass:: + Password for SMTP-AUTH. The argument is optional: If no + argument is specified, then the empty string is used as + the password. ++ +In place of this option, the following configuration variables +can be specified: ++ +-- + * sendemail.smtppass + * sendemail.<identity>.smtppass (see sendemail.identity). +-- ++ +However, --smtp-pass always overrides these variables. ++ +Furthermore, passwords need not be specified in configuration files +or on the command line. If a username has been specified (with +--smtp-user or a configuration variable), but no password has been +specified (with --smtp-pass or a configuration variable), then the +user is prompted for a password while the input is masked for privacy. --smtp-ssl:: If set, connects to the SMTP server using SSL. @@ -117,6 +146,17 @@ The --cc option must be repeated for each user you want on the cc list. Default is the value of 'sendemail.suppressfrom' configuration value; if that is unspecified, default to --no-suppress-from. +--suppress-cc:: + Specify an additional category of recipients to suppress the + auto-cc of. 'self' will avoid including the sender, 'author' will + avoid including the patch author, 'cc' will avoid including anyone + mentioned in Cc lines in the patch, 'sob' will avoid including + anyone mentioned in Signed-off-by lines, and 'cccmd' will avoid + running the --cc-cmd. 'all' will suppress all auto cc values. + Default is the value of 'sendemail.suppresscc' configuration value; + if that is unspecified, default to 'self' if --suppress-from is + specified, as well as 'sob' if --no-signed-off-cc is specified. + --thread, --no-thread:: If this is set, the In-Reply-To header will be set on each email sent. If disabled with "--no-thread", no emails will have the In-Reply-To @@ -176,6 +216,9 @@ sendemail.chainreplyto:: sendemail.smtpserver:: Default SMTP server to use. +sendemail.smtpserverport:: + Default SMTP server port to use. + sendemail.smtpuser:: Default SMTP-AUTH username. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 48e6f5a3f7..8dc35d493e 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -8,7 +8,7 @@ git-stash - Stash the changes in a dirty working directory away SYNOPSIS -------- [verse] -'git-stash' (list | show [<stash>] | apply [<stash>] | clear) +'git-stash' (list | show [<stash>] | apply [<stash>] | clear | drop [<stash>] | pop [<stash>]) 'git-stash' [save [<message>]] DESCRIPTION @@ -85,6 +85,17 @@ clear:: Remove all the stashed states. Note that those states will then be subject to pruning, and may be difficult or impossible to recover. +drop [<stash>]:: + + Remove a single stashed state from the stash list. When no `<stash>` + is given, it removes the latest one. i.e. `stash@\{0}` + +pop [<stash>]:: + + Remove a single stashed state from the stash list and apply on top + of the current working tree state. When no `<stash>` is given, + `stash@\{0}` is assumed. See also `apply`. + DISCUSSION ---------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index e818e6e789..6ffd896fbc 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -12,14 +12,16 @@ SYNOPSIS 'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>] 'git-submodule' [--quiet] status [--cached] [--] [<path>...] 'git-submodule' [--quiet] [init|update] [--] [<path>...] +'git-submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] COMMANDS -------- add:: Add the given repository as a submodule at the given path - to the changeset to be committed next. In particular, the - repository is cloned at the specified path, added to the + to the changeset to be committed next. If path is a valid + repository within the project, it is added as is. Otherwise, + repository is cloned at the specified path. path is added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. If the repository url begins with ./ or ../, it is stored as @@ -46,6 +48,11 @@ update:: checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached. +summary:: + Show commit summary between the given commit (defaults to HEAD) and + working tree/index. For a submodule in question, a series of commits + in the submodule between the given super project commit and the + index or working tree (switched by --cached) are shown. OPTIONS ------- @@ -56,9 +63,16 @@ OPTIONS Branch of repository to add as submodule. --cached:: - Display the SHA-1 stored in the index, not the SHA-1 of the currently - checked out submodule commit. This option is only valid for the - status command. + This option is only valid for status and summary commands. These + commands typically use the commit found in the submodule HEAD, but + with this option, the commit stored in the index is used instead. + +-n, --summary-limit:: + This option is only valid for the summary command. + Limit the summary size (number of commits shown in total). + Giving 0 will disable the summary; a negative number means unlimited + (the default). This limit only applies to modified submodules. The + size is always limited to 1 for added/deleted/typechanged submodules. <path>:: Path to submodule(s). When specified this will restrict the command diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 115b8bee0d..bec9accc89 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -165,6 +165,13 @@ environment). This command has the same behaviour. + Any other arguments are passed directly to `git log' +'blame':: + Show what revision and author last modified each line of a file. This is + identical to `git blame', but SVN revision numbers are shown instead of git + commit hashes. ++ +All arguments are passed directly to `git blame'. + -- 'find-rev':: When given an SVN revision number of the form 'rN', returns the diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index b729595984..9712392f79 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -26,6 +26,9 @@ creates a 'tag' object, and requires the tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. +If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` +are absent, `-a` is implied. + Otherwise just the SHA1 object name of the commit object is written (i.e. a lightweight tag). @@ -68,10 +71,14 @@ OPTIONS Use the given tag message (instead of prompting). If multiple `-m` options are given, there values are concatenated as separate paragraphs. + Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` + is given. -F <file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. + Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` + is given. CONFIGURATION ------------- diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index db019a2b8d..ba2a157299 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -32,11 +32,11 @@ OUTPUT FORMAT ------------- When specifying the -v option the format used is: - SHA1 type size offset-in-packfile + SHA1 type size size-in-pack-file offset-in-packfile for objects that are not deltified in the pack, and - SHA1 type size offset-in-packfile depth base-SHA1 + SHA1 type size size-in-packfile offset-in-packfile depth base-SHA1 for objects that are deltified. diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt new file mode 100644 index 0000000000..ddbae5b194 --- /dev/null +++ b/Documentation/git-web--browse.txt @@ -0,0 +1,99 @@ +git-web--browse(1) +================== + +NAME +---- +git-web--browse - git helper script to launch a web browser + +SYNOPSIS +-------- +'git-web--browse' [OPTIONS] URL/FILE ... + +DESCRIPTION +----------- + +This script tries, as much as possible, to display the URLs and FILEs +that are passed as arguments, as HTML pages in new tabs on an already +opened web browser. + +The following browsers (or commands) are currently supported: + +* firefox (this is the default under X Window when not using KDE) +* iceweasel +* konqueror (this is the default under KDE) +* w3m (this is the default outside graphical environments) +* links +* lynx +* dillo +* open (this is the default under Mac OS X GUI) + +Custom commands may also be specified. + +OPTIONS +------- +-b BROWSER|--browser=BROWSER:: + Use the specified BROWSER. It must be in the list of supported + browsers. + +-t BROWSER|--tool=BROWSER:: + Same as above. + +-c CONF.VAR|--config=CONF.VAR:: + CONF.VAR is looked up in the git config files. If it's set, + then its value specify the browser that should be used. + +CONFIGURATION VARIABLES +----------------------- + +CONF.VAR (from -c option) and web.browser +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The web browser can be specified using a configuration variable passed +with the -c (or --config) command line option, or the 'web.browser' +configuration variable if the former is not used. + +browser.<tool>.path +~~~~~~~~~~~~~~~~~~~ + +You can explicitly provide a full path to your preferred browser by +setting the configuration variable 'browser.<tool>.path'. For example, +you can configure the absolute path to firefox by setting +'browser.firefox.path'. Otherwise, 'git-web--browse' assumes the tool +is available in PATH. + +browser.<tool>.cmd +~~~~~~~~~~~~~~~~~~ + +When the browser, specified by options or configuration variables, is +not among the supported ones, then the corresponding +'browser.<tool>.cmd' configuration variable will be looked up. If this +variable exists then "git web--browse" will treat the specified tool +as a custom command and will use a shell eval to run the command with +the URLs passed as arguments. + +Note about git config --global +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note that these configuration variables should probably be set using +the '--global' flag, for example like this: + +------------------------------------------------ +$ git config --global web.browser firefox +------------------------------------------------ + +as they are probably more user specific than repository specific. +See linkgit:git-config[1] for more information about this. + +Author +------ +Written by Christian Couder <chriscool@tuxfamily.org> and the git-list +<git@vger.kernel.org>, based on git-mergetool by Theodore Y. Ts'o. + +Documentation +------------- +Documentation by Christian Couder <chriscool@tuxfamily.org> and the +git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[7] suite diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 54947b6769..a6e7bd4c8b 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -38,11 +38,6 @@ OPTIONS Show git internal diff output, but for the whole tree, not just the top level. ---pretty=<format>:: - Controls the output format for the commit logs. - <format> can be one of 'raw', 'medium', 'short', 'full', - and 'oneline'. - -m:: By default, differences for merge commits are not shown. With this flag, show differences to that commit from all @@ -51,6 +46,10 @@ OPTIONS However, it is not very useful in general, although it *is* useful on a file-by-file basis. +include::pretty-options.txt[] + +include::pretty-formats.txt[] + Examples -------- git-whatchanged -p v2.6.12.. include/scsi drivers/scsi:: diff --git a/Documentation/git.txt b/Documentation/git.txt index 17aee93ec5..336fe99cc7 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,19 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.4/git.html[documentation for release 1.5.4] +* link:v1.5.5/git.html[documentation for release 1.5.5] * release notes for + link:RelNotes-1.5.5.txt[1.5.5]. + +* link:v1.5.4.5/git.html[documentation for release 1.5.4.5] + +* release notes for + link:RelNotes-1.5.4.5.txt[1.5.4.5], + link:RelNotes-1.5.4.4.txt[1.5.4.4], + link:RelNotes-1.5.4.3.txt[1.5.4.3], + link:RelNotes-1.5.4.2.txt[1.5.4.2], + link:RelNotes-1.5.4.1.txt[1.5.4.1], link:RelNotes-1.5.4.txt[1.5.4]. * link:v1.5.3.8/git.html[documentation for release 1.5.3.8] diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 970db0c732..04ca63ca3d 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -140,6 +140,26 @@ When `core.autocrlf` is set to "input", line endings are converted to LF upon checkin, but there is no conversion done upon checkout. +If `core.safecrlf` is set to "true" or "warn", git verifies if +the conversion is reversible for the current setting of +`core.autocrlf`. For "true", git rejects irreversible +conversions; for "warn", git only prints a warning but accepts +an irreversible conversion. The safety triggers to prevent such +a conversion done to the files in the work tree, but there are a +few exceptions. Even though... + +- "git add" itself does not touch the files in the work tree, the + next checkout would, so the safety triggers; + +- "git apply" to update a text file with a patch does touch the files + in the work tree, but the operation is about text files and CRLF + conversion is about fixing the line ending inconsistencies, so the + safety does not trigger; + +- "git diff" itself does not touch the files in the work tree, it is + often run to inspect the changes you intend to next "git add". To + catch potential problems early, safety triggers. + `ident` ^^^^^^^ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index ef8a272d81..613dca006f 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -69,6 +69,13 @@ Patterns have the following format: included again. If a negated pattern matches, this will override lower precedence patterns sources. + - If the pattern ends with a slash, it is removed for the + purpose of the following description, but it would only find + a match with a directory. In other words, `foo/` will match a + directory `foo` and paths underneath it, but will not match a + regular file or a symbolic link `foo` (this is consistent + with the way how pathspec works in general in git). + - If the pattern does not contain a slash '/', git treats it as a shell glob pattern and checks for a match against the pathname without leading directories. diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index ab4caf4e26..51b63532b6 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -45,9 +45,12 @@ GIT Glossary "changesets" with git. [[def_checkout]]checkout:: - The action of updating the <<def_working_tree,working tree>> to a - <<def_revision,revision>> which was stored in the - <<def_object_database,object database>>. + The action of updating all or part of the + <<def_working_tree,working tree>> with a <<def_tree_object,tree object>> + or <<def_blob_object,blob>> from the + <<def_object_database,object database>>, and updating the + <<def_index,index>> and <<def_HEAD,HEAD>> if the whole working tree has + been pointed at a new <<def_branch,branch>>. [[def_cherry-picking]]cherry-picking:: In <<def_SCM,SCM>> jargon, "cherry pick" means to choose a subset of diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index f110162b01..76b8d77460 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -61,6 +61,35 @@ The default 'pre-commit' hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when such a line is found. +All the `git-commit` hooks are invoked with the environment +variable `GIT_EDITOR=:` if the command will not bring up an editor +to modify the commit message. + +prepare-commit-msg +------------------ + +This hook is invoked by `git-commit` right after preparing the +default log message, and before the editor is started. + +It takes one to three parameters. The first is the name of the file +that the commit log message. The second is the source of the commit +message, and can be: `message` (if a `\-m` or `\-F` option was +given); `template` (if a `\-t` option was given or the +configuration option `commit.template` is set); `merge` (if the +commit is a merge or a `.git/MERGE_MSG` file exists); `squash` +(if a `.git/SQUASH_MSG` file exists); or `commit`, followed by +a commit SHA1 (if a `\-c`, `\-C` or `\--amend` option was given). + +If the exit status is non-zero, `git-commit` will abort. + +The purpose of the hook is to edit the message file in place, and +it is not suppressed by the `\--no-verify` option. A non-zero exit +means a failure of the hook and aborts the commit. It should not +be used as replacement for pre-commit hook. + +The sample `prepare-commit-msg` hook that comes with git comments +out the `Conflicts:` part of a merge's commit message. + commit-msg ---------- diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 7df0266ba8..1276f858ad 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -33,3 +33,10 @@ ours:: merge is always the current branch head. It is meant to be used to supersede old development history of side branches. + +subtree:: + This is a modified recursive strategy. When merging trees A and + B, if B corresponds to a subtree of A, B is first adjusted to + match the tree structure of A, instead of reading the trees at + the same level. This adjustment is also done to the common + ancestor tree. diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 973d8dd733..6d66c74cc1 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -4,6 +4,9 @@ where '<format>' can be one of 'oneline', 'short', 'medium', 'full', 'fuller', 'email', 'raw' and 'format:<string>'. When omitted, the format defaults to 'medium'. ++ +Note: you can specify the default pretty format in the repository +configuration (see linkgit:git-config[1]). --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index a8138e27a1..2648a55085 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -130,9 +130,11 @@ limiting may be applied. Show commits older than a specific date. +ifdef::git-rev-list[] --max-age='timestamp', --min-age='timestamp':: Limit the commits output to specified time range. +endif::git-rev-list[] --author='pattern', --committer='pattern':: @@ -153,6 +155,11 @@ limiting may be applied. Consider the limiting patterns to be extended regular expressions instead of the default basic regular expressions. +-F, --fixed-strings:: + + Consider the limiting patterns to be fixed strings (don't interpret + pattern as a regular expression). + --remove-empty:: Stop when a given path disappears from the tree. diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt new file mode 100644 index 0000000000..073b22bd83 --- /dev/null +++ b/Documentation/technical/api-remote.txt @@ -0,0 +1,123 @@ +Remotes configuration API +========================= + +The API in remote.h gives access to the configuration related to +remotes. It handles all three configuration mechanisms historically +and currently used by git, and presents the information in a uniform +fashion. Note that the code also handles plain URLs without any +configuration, giving them just the default information. + +struct remote +------------- + +`name`:: + + The user's nickname for the remote + +`url`:: + + An array of all of the url_nr URLs configured for the remote + +`push`:: + + An array of refspecs configured for pushing, with + push_refspec being the literal strings, and push_refspec_nr + being the quantity. + +`fetch`:: + + An array of refspecs configured for fetching, with + fetch_refspec being the literal strings, and fetch_refspec_nr + being the quantity. + +`fetch_tags`:: + + The setting for whether to fetch tags (as a separate rule from + the configured refspecs); -1 means never to fetch tags, 0 + means to auto-follow tags based on the default heuristic, 1 + means to always auto-follow tags, and 2 means to fetch all + tags. + +`receivepack`, `uploadpack`:: + + The configured helper programs to run on the remote side, for + git-native protocols. + +`http_proxy`:: + + The proxy to use for curl (http, https, ftp, etc.) URLs. + +struct remotes can be found by name with remote_get(), and iterated +through with for_each_remote(). remote_get(NULL) will return the +default remote, given the current branch and configuration. + +struct refspec +-------------- + +A struct refspec holds the parsed interpretation of a refspec. If it +will force updates (starts with a '+'), force is true. If it is a +pattern (sides end with '*') pattern is true. src and dest are the two +sides (if a pattern, only the part outside of the wildcards); if there +is only one side, it is src, and dst is NULL; if sides exist but are +empty (i.e., the refspec either starts or ends with ':'), the +corresponding side is "". + +This parsing can be done to an array of strings to give an array of +struct refpsecs with parse_ref_spec(). + +remote_find_tracking(), given a remote and a struct refspec with +either src or dst filled out, will fill out the other such that the +result is in the "fetch" specification for the remote (note that this +evaluates patterns and returns a single result). + +struct branch +------------- + +Note that this may end up moving to branch.h + +struct branch holds the configuration for a branch. It can be looked +up with branch_get(name) for "refs/heads/{name}", or with +branch_get(NULL) for HEAD. + +It contains: + +`name`:: + + The short name of the branch. + +`refname`:: + + The full path for the branch ref. + +`remote_name`:: + + The name of the remote listed in the configuration. + +`remote`:: + + The struct remote for that remote. + +`merge_name`:: + + An array of the "merge" lines in the configuration. + +`merge`:: + + An array of the struct refspecs used for the merge lines. That + is, merge[i]->dst is a local tracking ref which should be + merged into this branch by default. + +`merge_nr`:: + + The number of merge configurations + +branch_has_merge_config() returns true if the given branch has merge +configuration given. + +Other stuff +----------- + +There is other stuff in remote.h that is related, in general, to the +process of interacting with remotes. + +(Daniel Barkalow) diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 19d2f64f73..c364a22c8f 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -1,10 +1,172 @@ run-command API =============== -Talk about <run-command.h>, and things like: +The run-command API offers a versatile tool to run sub-processes with +redirected input and output as well as with a modified environment +and an alternate current directory. -* Environment the command runs with (e.g. GIT_DIR); -* File descriptors and pipes; -* Exit status; +A similar API offers the capability to run a function asynchronously, +which is primarily used to capture the output that the function +produces in the caller in order to process it. -(Hannes, Dscho, Shawn) + +Functions +--------- + +`start_command`:: + + Start a sub-process. Takes a pointer to a `struct child_process` + that specifies the details and returns pipe FDs (if requested). + See below for details. + +`finish_command`:: + + Wait for the completion of a sub-process that was started with + start_command(). + +`run_command`:: + + A convenience function that encapsulates a sequence of + start_command() followed by finish_command(). Takes a pointer + to a `struct child_process` that specifies the details. + +`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: + + Convenience functions that encapsulate a sequence of + start_command() followed by finish_command(). The argument argv + specifies the program and its arguments. The argument opt is zero + or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or + `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members + .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`. + The argument dir corresponds the member .dir. The argument env + corresponds to the member .env. + +`start_async`:: + + Run a function asynchronously. Takes a pointer to a `struct + async` that specifies the details and returns a pipe FD + from which the caller reads. See below for details. + +`finish_async`:: + + Wait for the completion of an asynchronous function that was + started with start_async(). + + +Data structures +--------------- + +* `struct child_process` + +This describes the arguments, redirections, and environment of a +command to run in a sub-process. + +The caller: + +1. allocates and clears (memset(&chld, '0', sizeof(chld));) a + struct child_process variable; +2. initializes the members; +3. calls start_command(); +4. processes the data; +5. closes file descriptors (if necessary; see below); +6. calls finish_command(). + +The .argv member is set up as an array of string pointers (NULL +terminated), of which .argv[0] is the program name to run (usually +without a path). If the command to run is a git command, set argv[0] to +the command name without the 'git-' prefix and set .git_cmd = 1. + +The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows: + +. Specify 0 to request no special redirection. No new file descriptor + is allocated. The child process simply inherits the channel from the + parent. + +. Specify -1 to have a pipe allocated; start_command() replaces -1 + by the pipe FD in the following way: + + .in: Returns the writable pipe end into which the caller writes; + the readable end of the pipe becomes the child's stdin. + + .out, .err: Returns the readable pipe end from which the caller + reads; the writable end of the pipe end becomes child's + stdout/stderr. + + The caller of start_command() must close the so returned FDs + after it has completed reading from/writing to it! + +. Specify a file descriptor > 0 to be used by the child: + + .in: The FD must be readable; it becomes child's stdin. + .out: The FD must be writable; it becomes child's stdout. + .err > 0 is not supported. + + The specified FD is closed by start_command(), even if it fails to + run the sub-process! + +. Special forms of redirection are available by setting these members + to 1: + + .no_stdin, .no_stdout, .no_stderr: The respective channel is + redirected to /dev/null. + + .stdout_to_stderr: stdout of the child is redirected to its + stderr. This happens after stderr is itself redirected. + So stdout will follow stderr to wherever it is + redirected. + +To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env: + +. If the string is of the form "VAR=value", i.e. it contains '=' + the variable is added to the child process's environment. + +. If the string does not contain '=', it names an environment + variable that will be removed from the child process's environment. + +To specify a new initial working directory for the sub-process, +specify it in the .dir member. + + +* `struct async` + +This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads. + +The caller: + +1. allocates and clears (memset(&asy, '0', sizeof(asy));) a + struct async variable; +2. initializes .proc and .data; +3. calls start_async(); +4. processes the data by reading from the fd in .out; +5. closes .out; +6. calls finish_async(). + +The function pointer in .proc has the following signature: + + int proc(int fd, void *data); + +. fd specifies a writable file descriptor to which the function must + write the data that it produces. The function *must* close this + descriptor before it returns. + +. data is the value that the caller has specified in the .data member + of struct async. + +. The return value of the function is 0 on success and non-zero + on failure. If the function indicates failure, finish_async() will + report failure as well. + + +There are serious restrictions on what the asynchronous function can do +because this facility is implemented by a pipe to a forked process on +UNIX, but by a thread in the same address space on Windows: + +. It cannot change the program's state (global variables, environment, + etc.) in a way that the caller notices; in other words, .out is the + only communication channel to the caller. + +. It must not change the program's state that the caller of the + facility also uses. diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index aa87756a55..1803e64e46 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -103,10 +103,24 @@ Pack file entry: <+ packed object data: If it is not DELTA, then deflated bytes (the size above is the size before compression). - If it is DELTA, then + If it is REF_DELTA, then 20-byte base object name SHA1 (the size above is the size of the delta data that follows). delta data, deflated. + If it is OFS_DELTA, then + n-byte offset (see below) interpreted as a negative + offset from the type-byte of the header of the + ofs-delta entry (the size above is the size of + the delta data that follows). + delta data, deflated. + + offset encoding: + n bytes with MSB set in all but the last one. + The offset is then the number constructed by + concatenating the lower 7 bit of each byte, and + for n >= 2 adding 2^7 + 2^14 + ... + 2^(7*(n-1)) + to the result. + = Version 2 pack-*.idx files support packs larger than 4 GiB, and diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 81ac17f32a..fa34c67471 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -44,3 +44,26 @@ endif::git-clone[] ifdef::git-clone[] They are equivalent, except the former implies --local option. endif::git-clone[] + + +If there are a large number of similarly-named remote repositories and +you want to use a different format for them (such that the URLs you +use will be rewritten into URLs that work), you can create a +configuration section of the form: + +------------ + [url "<actual url base>"] + insteadOf = <other url base> +------------ + +For example, with this: + +------------ + [url "git://git.host.xz/"] + insteadOf = host.xz:/path/to/ + insteadOf = work: +------------ + +a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be +rewritten in any context that takes a URL to be "git://git.host.xz/repo.git". + |