diff options
Diffstat (limited to 'Documentation')
30 files changed, 676 insertions, 103 deletions
diff --git a/Documentation/RelNotes/1.7.6.txt b/Documentation/RelNotes/1.7.6.txt new file mode 100644 index 0000000000..9ec498ea39 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.txt @@ -0,0 +1,136 @@ +Git v1.7.6 Release Notes +======================== + +Updates since v1.7.5 +-------------------- + + * Various git-svn updates. + + * Updates the way content tags are handled in gitweb. Also adds + a UI to choose common timezone for displaying the dates. + + * Similar to branch names, tagnames that begin with "-" are now + disallowed. + + * Clean-up of the C part of i18n (but not l10n---please wait) + continues. + + * The scripting part of the codebase is getting prepared for i18n/l10n. + + * Pushing and pulling from a repository with large number of refs that + point to identical commits are optimized by not listing the same commit + during the common ancestor negotiation exchange with the other side. + + * Adding a file larger than core.bigfilethreshold (defaults to 1/2 Gig) + using "git add" will send the contents straight to a packfile without + having to hold it and its compressed representation both at the same + time in memory. + + * Processes spawned by "[alias] <name> = !process" in the configuration + can inspect GIT_PREFIX environment variable to learn where in the + working tree the original command was invoked. + + * A magic pathspec ":/" tells a command that limits its operation to + the current directory when ran from a subdirectory to work on the + entire working tree. In general, ":/path/to/file" would be relative + to the root of the working tree hierarchy. + + After "git reset --hard; edit Makefile; cd t/", "git add -u" would + be a no-op, but "git add -u :/" would add the updated contents of + the Makefile at the top level. If you want to name a path in the + current subdirectory whose unusual name begins with ":/", you can + name it by "./:/that/path" or by "\:/that/path". + + * "git blame" learned "--abbrev[=<n>]" option to control the minimum + number of hexdigits shown for commit object names. + + * "git blame" learned "--line-porcelain" that is less efficient but is + easier to parse. + + * Aborting "git commit --interactive" discards updates to the index + made during the interactive session. + + * "git commit" learned a "--patch" option to directly jump to the + per-hunk selection UI of the interactive mode. + + * "git diff" and its family of commands learned --dirstat=0 to show + directories that contribute less than 0.1% of changes. + + * "git diff" and its family of commands learned --dirstat=lines mode to + assess damage to the directory based on number of lines in the patch + output, not based on the similarity numbers. + + * "git format-patch" learned "--quiet" option to suppress the output of + the names of generated files. + + * "git format-patch" quotes people's names when it has RFC822 special + characters in it, e.g. "Junio C. Hamano" <jch@example.com>. Earlier + it was up to the user to do this when using its output. + + * "git format-patch" can take an empty --subject-prefix now. + + * "git grep" learned the "-P" option to take pcre regular expressions. + + * "git log" and friends learned a new "--notes" option to replace the + "--show-notes" option. Unlike "--show-notes", "--notes=<ref>" does + not imply showing the default notes. + + * They also learned a log.abbrevCommit configuration variable to augment + the --abbrev-commit command line option. + + * "git ls-remote" learned "--exit-code" option to consider it a + different kind of error when no remote ref to be shown. + + * "git merge" learned "-" as a short-hand for "the previous branch", just + like the way "git checkout -" works. + + * "git merge" uses "merge.ff" configuration variable to decide to always + create a merge commit (i.e. --no-ff, aka merge.ff=no), refuse to create + a merge commit (i.e. --ff-only, aka merge.ff=only). Setting merge.ff=yes + (or not setting it at all) restores the default behaviour of allowing + fast-forward to happen when possible. + + * p4-import (from contrib) learned a new option --preserve-user. + + * "git read-tree -m" learned "--dry-run" option that reports if a merge + would fail without touching the index nor the working tree. + + * "git rebase" that does not specify on top of which branch to rebase + the current branch now uses @{upstream} of the current branch. + + * "git rebase" finished either normally or with --abort did not + update the reflog for HEAD to record the event to come back to + where it started from. + + * "git remote add -t only-this-branch --mirror=fetch" is now allowed. Earlier + a fetch-mode mirror meant mirror everything, but now it only means refs are + not renamed. + + * "git rev-list --count" used with "--cherry-mark" counts the cherry-picked + commits separately, producing more a useful output. + + * "git submodule update" learned "--force" option to get rid of local + changes in submodules and replace them with the up-to-date version. + + * "git status" and friends ignore .gitmodules file while the file is + still in a conflicted state during a merge, to avoid using information + that is not final and possibly corrupt with conflict markers. + +Also contains various documentation updates and minor miscellaneous +changes. + + +Fixes since v1.7.5 +------------------ + +Unless otherwise noted, all the fixes in 1.7.5.X maintenance track are +included in this release. + + * "git config" used to choke with an insanely long line. + (merge ef/maint-strbuf-init later) + + * "git diff --quiet" did not work well with --diff-filter. + (merge jk/diff-not-so-quick later) + + * "git status -z" did not default to --porcelain output format. + (merge bc/maint-status-z-to-use-porcelain later) diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 16e3c68576..e76195ac97 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -52,6 +52,11 @@ of lines before or after the line given by <start>. --porcelain:: Show in a format designed for machine consumption. +--line-porcelain:: + Show the porcelain format, but output commit information for + each line, not just the first time a commit is referenced. + Implies --porcelain. + --incremental:: Show the result incrementally in a format designed for machine consumption. diff --git a/Documentation/config.txt b/Documentation/config.txt index d16136210a..6b93777199 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -587,6 +587,8 @@ it will be treated as a shell command. For example, defining "gitk --all --not ORIG_HEAD". Note that shell commands will be executed from the top-level directory of a repository, which may not necessarily be the current directory. +'GIT_PREFIX' is set as returned by running 'git rev-parse --show-prefix' +from the original current directory. See linkgit:git-rev-parse[1]. am.keepcr:: If true, git-am will call git-mailsplit for patches in mbox format @@ -641,7 +643,7 @@ branch.<name>.remote:: branch.<name>.merge:: Defines, together with branch.<name>.remote, the upstream branch - for the given branch. It tells 'git fetch'/'git pull' which + for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which branch to merge and can also affect 'git push' (see push.default). When in branch <name>, it tells 'git fetch' the default refspec to be marked for merging in FETCH_HEAD. The value is @@ -1308,9 +1310,15 @@ interactive.singlekey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). Currently this is used by the `\--patch` mode of - linkgit:git-add[1], linkgit:git-reset[1], linkgit:git-stash[1] and - linkgit:git-checkout[1]. Note that this setting is silently - ignored if portable keystroke input is not available. + linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], + linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this + setting is silently ignored if portable keystroke input + is not available. + +log.abbrevCommit:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `\--abbrev-commit`. You may + override this option with `\--no-abbrev-commit`. log.date:: Set the default date-time mode for the 'log' command. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 2b1605f5c8..1aed79e7dc 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -8,6 +8,50 @@ diff.autorefreshindex:: affects only 'git diff' Porcelain, and not lower level 'diff' commands such as 'git diff-files'. +diff.dirstat:: + A comma separated list of `--dirstat` parameters specifying the + default behavior of the `--dirstat` option to linkgit:git-diff[1]` + and friends. The defaults can be overridden on the command line + (using `--dirstat=<param1,param2,...>`). The fallback defaults + (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. + The following parameters are available: ++ +-- +`changes`;; + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +`lines`;; + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive `--dirstat` + behavior than the `changes` behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other `--*stat` options. +`files`;; + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest `--dirstat` behavior, since it does + not have to look at the file contents at all. +`cumulative`;; + Count changes in a child directory for the parent directory as well. + Note that when using `cumulative`, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the `noncumulative` parameter. +<limit>;; + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +-- ++ +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +`files,10,cumulative`. + diff.external:: If this config variable is set, diff generation is not performed using the internal diff machinery, but using the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 96e0a581a1..659de6f123 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -66,19 +66,49 @@ endif::git-format-patch[] number of modified files, as well as number of added and deleted lines. ---dirstat[=<limit>]:: - Output the distribution of relative amount of changes (number of lines added or - removed) for each sub-directory. Directories with changes below - a cut-off percent (3% by default) are not shown. The cut-off percent - can be set with `--dirstat=<limit>`. Changes in a child directory are not - counted for the parent directory, unless `--cumulative` is used. +--dirstat[=<param1,param2,...>]:: + Output the distribution of relative amount of changes for each + sub-directory. The behavior of `--dirstat` can be customized by + passing it a comma separated list of parameters. + The defaults are controlled by the `diff.dirstat` configuration + variable (see linkgit:git-config[1]). + The following parameters are available: + -Note that the `--dirstat` option computes the changes while ignoring -the amount of pure code movements within a file. In other words, -rearranging lines in a file is not counted as much as other changes. - ---dirstat-by-file[=<limit>]:: - Same as `--dirstat`, but counts changed files instead of lines. +-- +`changes`;; + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +`lines`;; + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive `--dirstat` + behavior than the `changes` behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other `--*stat` options. +`files`;; + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest `--dirstat` behavior, since it does + not have to look at the file contents at all. +`cumulative`;; + Count changes in a child directory for the parent directory as well. + Note that when using `cumulative`, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the `noncumulative` parameter. +<limit>;; + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +-- ++ +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +`--dirstat=files,10,cumulative`. --summary:: Output a condensed summary of extended header information @@ -274,6 +304,19 @@ endif::git-log[] projects, so use it with caution. Giving more than one `-C` option has the same effect. +-D:: +--irreversible-delete:: + Omit the preimage for deletes, i.e. print only the header but not + the diff between the preimage and `/dev/null`. The resulting patch + is not meant to be applied with `patch` nor `git apply`; this is + solely for people who want to just concentrate on reviewing the + text after the change. In addition, the output obviously lack + enough information to apply such a patch in reverse, even manually, + hence the name of the option. ++ +When used together with `-B`, omit also the preimage in the deletion part +of a delete/create pair. + -l<num>:: The `-M` and `-C` options require O(n^2) processing time where n is the number of potential rename/copy targets. This @@ -373,6 +416,17 @@ endif::git-format-patch[] --no-ext-diff:: Disallow external diff drivers. +--textconv:: +--no-textconv:: + Allow (or disallow) external text conversion filters to be run + when comparing binary files. See linkgit:gitattributes[5] for + details. Because textconv filters are typically a one-way + conversion, the resulting diff is suitable for human + consumption, but cannot be applied. For this reason, textconv + filters are enabled by default only for linkgit:git-diff[1] and + linkgit:git-log[1], but not for linkgit:git-format-patch[1] or + diff plumbing commands. + --ignore-submodules[=<when>]:: Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index c4d1ff86c9..9516914236 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L n,m] - [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] + [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> DESCRIPTION @@ -73,6 +73,11 @@ include::blame-options.txt[] Ignore whitespace when comparing the parent's version and the child's to find where the lines came from. +--abbrev=<n>:: + Instead of using the default 7+1 hexadecimal digits as the + abbreviated object name, use <n>+1 digits. Note that 1 column + is used for a caret to mark the boundary commit. + THE PORCELAIN FORMAT -------------------- @@ -100,6 +105,19 @@ The contents of the actual line is output after the above header, prefixed by a TAB. This is to allow adding more header elements later. +The porcelain format generally suppresses commit information that has +already been seen. For example, two lines that are blamed to the same +commit will both be shown, but the details for that commit will be shown +only once. This is more efficient, but may require more state be kept by +the reader. The `--line-porcelain` option can be used to output full +commit information for each line, allowing simpler (but less efficient) +usage like: + + # count the number of lines attributed to each author + git blame --line-porcelain file | + sed -n 's/^author //p' | + sort | uniq -c | sort -rn + SPECIFYING RANGES ----------------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index d0534b8c05..7951cb7b00 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,11 +8,12 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run] - [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>] - [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] - [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] - [--status | --no-status] [-i | -o] [--] [<file>...] +'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] + [--dry-run] [(-c | -C | --fixup | --squash) <commit>] + [-F <file> | -m <msg>] [--reset-author] [--allow-empty] + [--allow-empty-message] [--no-verify] [-e] [--author=<author>] + [--date=<date>] [--cleanup=<mode>] [--status | --no-status] + [-i | -o] [--] [<file>...] DESCRIPTION ----------- @@ -39,9 +40,10 @@ The content to be added can be specified in several ways: that have been removed from the working tree, and then perform the actual commit; -5. by using the --interactive switch with the 'commit' command to decide one - by one which files should be part of the commit, before finalizing the - operation. Currently, this is done by invoking 'git add --interactive'. +5. by using the --interactive or --patch switches with the 'commit' command + to decide one by one which files or hunks should be part of the commit, + before finalizing the operation. See the ``Interactive Mode`` section of + linkgit:git-add[1] to learn how to operate these modes. The `--dry-run` option can be used to obtain a summary of what is included by any of the above for the next @@ -59,6 +61,12 @@ OPTIONS been modified and deleted, but new files you have not told git about are not affected. +-p:: +--patch:: + Use the interactive patch selection interface to chose + which changes to commit. See linkgit:git-add[1] for + details. + -C <commit>:: --reuse-message=<commit>:: Take an existing commit object, and reuse the log message diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 8804de327f..e7ecf5d803 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -50,16 +50,18 @@ The default is to assume the config file of the current repository, .git/config unless defined otherwise with GIT_DIR and GIT_CONFIG (see <<FILES>>). -This command will fail if: - -. The config file is invalid, -. Can not write to the config file, -. no section was provided, -. the section or key is invalid, -. you try to unset an option which does not exist, -. you try to unset/set an option for which multiple lines match, or -. you use '--global' option without $HOME being properly set. - +This command will fail (with exit code ret) if: + +. The config file is invalid (ret=3), +. can not write to the config file (ret=4), +. no section or name was provided (ret=2), +. the section or key is invalid (ret=1), +. you try to unset an option which does not exist (ret=5), +. you try to unset/set an option for which multiple lines match (ret=5), +. you try to use an invalid regexp (ret=6), or +. you use '--global' option without $HOME being properly set (ret=128). + +On success, the command returns the exit code 0. OPTIONS ------- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 249249aac7..3f5b9126b1 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -648,9 +648,14 @@ paths for a commit are encouraged to do so. `notemodify` ^^^^^^^^^^^^ -Included in a `commit` command to add a new note (annotating a given -commit) or change the content of an existing note. This command has -two different means of specifying the content of the note. +Included in a `commit` `<notes_ref>` command to add a new note +annotating a `<committish>` or change this annotation contents. +Internally it is similar to filemodify 100644 on `<committish>` +path (maybe split into subdirectories). It's not advised to +use any other commands to write to the `<notes_ref>` tree except +`filedeleteall` to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note. External data format:: The data content for the note was already supplied by a prior diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 9dc1f2a947..0f2f117383 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,8 +32,9 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts`. If you have any grafts -defined, running this command will make them permanent. +*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +If you have any grafts or replacement refs defined, running this command +will make them permanent. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index d7523b3e45..e150c77cff 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -12,7 +12,8 @@ SYNOPSIS 'git grep' [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] - [-F | --fixed-strings] [-n] + [-P | --perl-regexp] + [-F | --fixed-strings] [-n | --line-number] [-l | --files-with-matches] [-L | --files-without-match] [(-O | --open-files-in-pager) [<pager>]] [-z | --null] @@ -97,6 +98,11 @@ OPTIONS Use POSIX extended/basic regexp for patterns. Default is to use basic regexp. +-P:: +--perl-regexp:: + Use Perl-compatible regexp for patterns. Requires libpcre to be + compiled in. + -F:: --fixed-strings:: Use fixed strings for patterns (don't interpret pattern diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 2c84028838..de5c0d37a5 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -178,9 +178,9 @@ May be an unabbreviated ref name or a glob and may be specified multiple times. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. + -This setting can be disabled by the `--no-standard-notes` option, +This setting can be disabled by the `--no-notes` option, overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, -and supplemented by the `--show-notes` option. +and overridden by the `--notes=<ref>` option. GIT --- diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index c3df8c0ebe..7a9b86a58a 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - <repository> [<refs>...] + [--exit-code] <repository> [<refs>...] DESCRIPTION ----------- @@ -36,6 +36,12 @@ OPTIONS SSH and where the SSH daemon does not use the PATH configured by the user. +--exit-code:: + Exit with status "2" when no matching refs are found in the remote + repository. Usually the command exits with status "0" to indicate + it successfully talked with the remote repository, whether it + found any matching refs. + <repository>:: Location of the repository. The shorthand defined in $GIT_DIR/branches/ can be used. Use "." (dot) to list references in diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 296f314eae..6a187f2e23 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -17,7 +17,7 @@ SYNOPSIS 'git notes' merge [-v | -q] [-s <strategy> ] <notes_ref> 'git notes' merge --commit [-v | -q] 'git notes' merge --abort [-v | -q] -'git notes' remove [<object>] +'git notes' remove [--ignore-missing] [--stdin] [<object>...] 'git notes' prune [-n | -v] 'git notes' get-ref @@ -57,8 +57,11 @@ list:: add:: Add notes for a given object (defaults to HEAD). Abort if the - object already has notes (use `-f` to overwrite an - existing note). + object already has notes (use `-f` to overwrite existing notes). + However, if you're using `add` interactively (using an editor + to supply the notes contents), then - instead of aborting - + the existing notes will be opened in the editor (like the `edit` + subcommand). copy:: Copy the notes for the first object onto the second object. @@ -103,8 +106,9 @@ When done, the user can either finalize the merge with 'git notes merge --abort'. remove:: - Remove the notes for a given object (defaults to HEAD). - This is equivalent to specifying an empty note message to + Remove the notes for given objects (defaults to HEAD). When + giving zero or one object from the command line, this is + equivalent to specifying an empty note message to the `edit` subcommand. prune:: @@ -151,6 +155,15 @@ OPTIONS 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref is taken to be in `refs/notes/` if it is not qualified. +--ignore-missing:: + Do not consider it an error to request removing notes from an + object that does not have notes attached to it. + +--stdin:: + Also read the object names to remove notes from from the standard + input (there is no reason you cannot combine this with object + names from the command line). + -n:: --dry-run:: Do not remove anything; just report the object names whose notes diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 26fdadc642..46a96f2313 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -53,6 +53,11 @@ OPTIONS trees that are not directly related to the current working tree status into a temporary index file. +-n:: +--dry-run:: + Check if the command would error out, without updating the index + nor the files in the working tree for real. + -v:: Show the progress of checking files out. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 620d50e71f..9a075bc4d2 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git rebase' [-i | --interactive] [options] [--onto <newbase>] - <upstream> [<branch>] + [<upstream>] [<branch>] 'git rebase' [-i | --interactive] [options] --onto <newbase> --root [<branch>] @@ -21,6 +21,12 @@ If <branch> is specified, 'git rebase' will perform an automatic `git checkout <branch>` before doing anything else. Otherwise it remains on the current branch. +If <upstream> is not specified, the upstream configured in +branch.<name>.remote and branch.<name>.merge options will be used; see +linkgit:git-config[1] for details. If you are currently not on any +branch or if the current branch does not have a configured upstream, +the rebase will abort. + All changes made by commits in the current branch but that are not in <upstream> are saved to a temporary area. This is the same set of commits that would be shown by `git log <upstream>..HEAD` (or @@ -217,7 +223,8 @@ leave out at most one of A and B, in which case it defaults to HEAD. <upstream>:: Upstream branch to compare against. May be any valid commit, - not just an existing branch name. + not just an existing branch name. Defaults to the configured + upstream for the current branch. <branch>:: Working branch; defaults to HEAD. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 415f4f0b30..38fafcaa6b 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -29,6 +29,7 @@ SYNOPSIS [ \--tags[=<pattern>] ] [ \--remotes[=<pattern>] ] [ \--glob=<glob-pattern> ] + [ \--ignore-missing ] [ \--stdin ] [ \--quiet ] [ \--topo-order ] diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt new file mode 100644 index 0000000000..61e4c08dac --- /dev/null +++ b/Documentation/git-sh-i18n--envsubst.txt @@ -0,0 +1,36 @@ +git-sh-i18n--envsubst(1) +======================== + +NAME +---- +git-sh-i18n--envsubst - Git's own envsubst(1) for i18n fallbacks + +SYNOPSIS +-------- +[verse] +eval_gettext () { + printf "%s" "$1" | ( + export PATH $('git sh-i18n--envsubst' --variables "$1"); + 'git sh-i18n--envsubst' "$1" + ) +} + +DESCRIPTION +----------- + +This is not a command the end user would want to run. Ever. +This documentation is meant for people who are studying the +plumbing scripts and/or are writing new ones. + +git-sh-i18n--envsubst is Git's stripped-down copy of the GNU +`envsubst(1)` program that comes with the GNU gettext package. It's +used internally by linkgit:git-sh-i18n[1] to interpolate the variables +passed to the the `eval_gettext` function. + +No promises are made about the interface, or that this +program won't disappear without warning in the next version +of Git. Don't use it. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.txt new file mode 100644 index 0000000000..3b1f7ac7b5 --- /dev/null +++ b/Documentation/git-sh-i18n.txt @@ -0,0 +1,42 @@ +git-sh-i18n(1) +============== + +NAME +---- +git-sh-i18n - Git's i18n setup code for shell scripts + +SYNOPSIS +-------- +'. "$(git --exec-path)/git-sh-i18n"' + +DESCRIPTION +----------- + +This is not a command the end user would want to run. Ever. +This documentation is meant for people who are studying the +Porcelain-ish scripts and/or are writing new ones. + +The 'git sh-i18n scriptlet is designed to be sourced (using +`.`) by Git's porcelain programs implemented in shell +script. It provides wrappers for the GNU `gettext` and +`eval_gettext` functions accessible through the `gettext.sh` +script, and provides pass-through fallbacks on systems +without GNU gettext. + +FUNCTIONS +--------- + +gettext:: + Currently a dummy fall-through function implemented as a wrapper + around `printf(1)`. Will be replaced by a real gettext + implementation in a later version. + +eval_gettext:: + Currently a dummy fall-through function implemented as a wrapper + around `printf(1)` with variables expanded by the + linkgit:git-sh-i18n--envsubst[1] helper. Will be replaced by a + real gettext implementation in a later version. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 053df505bc..27fd8ba854 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -58,9 +58,14 @@ cd_to_toplevel:: runs chdir to the toplevel of the working tree. require_work_tree:: - checks if the repository is a bare repository, and dies - if so. Used by scripts that require working tree - (e.g. `checkout`). + checks if the current directory is within the working tree + of the repository, and otherwise dies. + +require_work_tree_exists:: + checks if the working tree associated with the repository + exists, and otherwise dies. Often done before calling + cd_to_toplevel, which is impossible to do if there is no + working tree. get_author_ident_from_commit:: outputs code for use with eval to set the GIT_AUTHOR_NAME, diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 1a16ff6044..5e7a4130ee 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -186,8 +186,10 @@ OPTIONS -f:: --force:: - This option is only valid for the add command. - Allow adding an otherwise ignored submodule path. + This option is only valid for add and update commands. + When running add, allow adding an otherwise ignored submodule path. + When running update, throw away local changes in submodules when + switching to a different commit. --cached:: This option is only valid for status and summary commands. These diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 39feb62129..713e523034 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -339,6 +339,8 @@ Any other arguments are passed directly to 'git log' Empty directories are automatically recreated when using "git svn clone" and "git svn rebase", so "mkdirs" is intended for use after commands like "git checkout" or "git reset". + (See the svn-remote.<name>.automkdirs config file option for + more information.) 'commit-diff':: Commits the diff of two tree-ish arguments from the @@ -680,6 +682,14 @@ svn.pathnameencoding:: locales to avoid corrupted file names with non-ASCII characters. Valid encodings are the ones supported by Perl's Encode module. +svn-remote.<name>.automkdirs:: + Normally, the "git svn clone" and "git svn rebase" commands + attempt to recreate empty directories that are in the + Subversion repository. If this option is set to "false", then + empty directories will only be created if the "git svn mkdirs" + command is run explicitly. If unset, 'git svn' assumes this + option to be "true". + Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps options all affect the metadata generated and used by 'git svn'; they *must* be set in the configuration file before any history is imported diff --git a/Documentation/git.txt b/Documentation/git.txt index 7fc6b88b96..0172cd7014 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,7 +9,7 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=<path>]] [--html-path] +'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [-c <name>=<value>] @@ -44,6 +44,11 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v1.7.6/git.html[documentation for release 1.7.6] + +* release notes for + link:RelNotes/1.7.6.txt[1.7.6]. + * link:v1.7.5.4/git.html[documentation for release 1.7.5.4] * release notes for @@ -291,8 +296,16 @@ help ...`. the current setting and then exit. --html-path:: - Print the path to wherever your git HTML documentation is installed - and exit. + Print the path, without trailing slash, where git's HTML + documentation is installed and exit. + +--man-path:: + Print the manpath (see `man(1)`) for the man pages for + this version of git and exit. + +--info-path:: + Print the path where the Info files documenting this + version of git are installed and exit. -p:: --paginate:: diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 15aebc6062..412c55b549 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -593,6 +593,37 @@ and now produces better output), you can remove the cache manually with `git update-ref -d refs/notes/textconv/jpg` (where "jpg" is the name of the diff driver, as in the example above). +Choosing textconv versus external diff +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to show differences between binary or specially-formatted +blobs in your repository, you can choose to use either an external diff +command, or to use textconv to convert them to a diff-able text format. +Which method you choose depends on your exact situation. + +The advantage of using an external diff command is flexibility. You are +not bound to find line-oriented changes, nor is it necessary for the +output to resemble unified diff. You are free to locate and report +changes in the most appropriate way for your data format. + +A textconv, by comparison, is much more limiting. You provide a +transformation of the data into a line-oriented text format, and git +uses its regular diff tools to generate the output. There are several +advantages to choosing this method: + +1. Ease of use. It is often much simpler to write a binary to text + transformation than it is to perform your own diff. In many cases, + existing programs can be used as textconv filters (e.g., exif, + odt2txt). + +2. Git diff features. By performing only the transformation step + yourself, you can still utilize many of git's diff features, + including colorization, word-diff, and combined diffs for merges. + +3. Caching. Textconv caching can speed up repeated diffs, such as those + you might trigger by running `git log -p`. + + Marking files as binary ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index f4fd5b046d..3595b586bc 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -277,7 +277,8 @@ This commit is referred to as a "merge commit", or sometimes just a Pattern used to specify paths. + Pathspecs are used on the command line of "git ls-files", "git -ls-tree", "git grep", "git checkout", and many other commands to +ls-tree", "git add", "git grep", "git diff", "git checkout", +and many other commands to limit the scope of operations to some subset of the tree or worktree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The @@ -296,6 +297,37 @@ For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. ++ +A pathspec that begins with a colon `:` has special meaning. In the +short form, the leading colon `:` is followed by zero or more "magic +signature" letters (which optionally is terminated by another colon `:`), +and the remainder is the pattern to match against the path. The optional +colon that terminates the "magic signature" can be omitted if the pattern +begins with a character that cannot be a "magic signature" and is not a +colon. ++ +In the long form, the leading colon `:` is followed by a open +parenthesis `(`, a comma-separated list of zero or more "magic words", +and a close parentheses `)`, and the remainder is the pattern to match +against the path. ++ +The "magic signature" consists of an ASCII symbol that is not +alphanumeric. ++ +-- +top `/`;; + The magic word `top` (mnemonic: `/`) makes the pattern match + from the root of the working tree, even when you are running + the command from inside a subdirectory. +-- ++ +Currently only the slash `/` is recognized as the "magic signature", +but it is envisioned that we will support more types of magic in later +versions of git. ++ +A pathspec with only a colon means "there is no pathspec". This form +should not be combined with other pathspec. + [[def_parent]]parent:: A <<def_commit_object,commit object>> contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 8920258baa..861bd6f553 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -16,6 +16,16 @@ merge.defaultToUpstream:: to their corresponding remote tracking branches, and the tips of these tracking branches are merged. +merge.ff:: + By default, git does not create an extra merge commit when merging + a commit that is a descendant of the current commit. Instead, the + tip of the current branch is fast-forwarded. When set to `false`, + this variable tells git to create an extra merge commit in such + a case (equivalent to giving the `--no-ff` option from the command + line). When set to `only`, only such fast-forward merges are + allowed (equivalent to giving the `--ff-only` option from the + command line). + merge.log:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 50923e2ce9..2a3dc8664f 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -19,6 +19,11 @@ configuration (see linkgit:git-config[1]). This should make "--pretty=oneline" a whole lot more readable for people using 80-column terminals. +--no-abbrev-commit:: + Show the full 40-byte hexadecimal commit object name. This negates + `--abbrev-commit` and those options which imply it such as + "--oneline". It also overrides the 'log.abbrevCommit' variable. + --oneline:: This is a shorthand for "--pretty=oneline --abbrev-commit" used together. @@ -30,19 +35,34 @@ people using 80-column terminals. preferred by the user. For non plumbing commands this defaults to UTF-8. ---no-notes:: ---show-notes[=<ref>]:: +--notes[=<ref>]:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default for `git log`, `git show` and `git whatchanged` commands when - there is no `--pretty`, `--format` nor `--oneline` option is - given on the command line. + there is no `--pretty`, `--format` nor `--oneline` option given + on the command line. ++ +By default, the notes shown are from the notes refs listed in the +'core.notesRef' and 'notes.displayRef' variables (or corresponding +environment overrides). See linkgit:git-config[1] for more details. + -With an optional argument, add this ref to the list of notes. The ref -is taken to be in `refs/notes/` if it is not qualified. +With an optional '<ref>' argument, show this notes ref instead of the +default notes ref(s). The ref is taken to be in `refs/notes/` if it +is not qualified. ++ +Multiple --notes options can be combined to control which notes are +being displayed. Examples: "--notes=foo" will show only notes from +"refs/notes/foo"; "--notes=foo --notes" will show both notes from +"refs/notes/foo" and from the default notes ref(s). + +--no-notes:: + Do not show notes. This negates the above `--notes` option, by + resetting the list of notes refs from which notes are shown. + Options are parsed in the order given on the command line, so e.g. + "--notes --notes=foo --no-notes --notes=bar" will only show notes + from "refs/notes/bar". +--show-notes[=<ref>]:: --[no-]standard-notes:: - Enable or disable populating the notes ref list from the - 'core.notesRef' and 'notes.displayRef' variables (or - corresponding environment overrides). Enabled by default. - See linkgit:git-config[1]. + These options are deprecated. Use the above --notes/--no-notes + options instead. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 73111bb051..62340a5e4c 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -139,6 +139,10 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). is automatically prepended if missing. If pattern lacks '?', '*', or '[', '/*' at the end is implied. +--ignore-missing:: + + Upon seeing an invalid object name in the input, pretend as if + the bad input was not given. ifndef::git-rev-list[] --bisect:: @@ -268,7 +272,7 @@ Default mode:: --full-history:: - As the default mode but does not prune some history. + Same as the default mode, but does not prune some history. --dense:: @@ -730,7 +734,10 @@ ifdef::git-rev-list[] Print a number stating how many commits would have been listed, and suppress all other output. When used together with '--left-right', instead print the counts for left and - right commits, separated by a tab. + right commits, separated by a tab. When used together with + '--cherry-mark', omit patch equivalent commits from these + counts and print the count for equivalent commits separated + by a tab. endif::git-rev-list[] diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 7b233ca196..8930b3fabc 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -147,8 +147,9 @@ GIT index format - 160-bit object name for the object that would result from writing this span of index as a tree. - An entry can be in an invalidated state and is represented by having -1 - in the entry_count field. + An entry can be in an invalidated state and is represented by having + -1 in the entry_count field. In this case, there is no object name + and the next entry starts immediately after the newline. The entries are written out in the top-down, depth-first order. The first entry represents the root level of the repository, followed by the diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 369f91d3b9..a7004c63e7 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -179,34 +179,36 @@ and descriptions. Packfile Negotiation -------------------- -After reference and capabilities discovery, the client can decide -to terminate the connection by sending a flush-pkt, telling the -server it can now gracefully terminate (as happens with the ls-remote -command) or it can enter the negotiation phase, where the client and -server determine what the minimal packfile necessary for transport is. - -Once the client has the initial list of references that the server -has, as well as the list of capabilities, it will begin telling the -server what objects it wants and what objects it has, so the server -can make a packfile that only contains the objects that the client needs. -The client will also send a list of the capabilities it wants to be in -effect, out of what the server said it could do with the first 'want' line. +After reference and capabilities discovery, the client can decide to +terminate the connection by sending a flush-pkt, telling the server it can +now gracefully terminate, and disconnect, when it does not need any pack +data. This can happen with the ls-remote command, and also can happen when +the client already is up-to-date. + +Otherwise, it enters the negotiation phase, where the client and +server determine what the minimal packfile necessary for transport is, +by telling the server what objects it wants, its shallow objects +(if any), and the maximum commit depth it wants (if any). The client +will also send a list of the capabilities it wants to be in effect, +out of what the server said it could do with the first 'want' line. ---- upload-request = want-list - have-list - compute-end + *shallow-line + *1depth-request + flush-pkt want-list = first-want *additional-want - flush-pkt + + shallow-line = PKT_LINE("shallow" SP obj-id) + + depth-request = PKT_LINE("deepen" SP depth) first-want = PKT-LINE("want" SP obj-id SP capability-list LF) additional-want = PKT-LINE("want" SP obj-id LF) - have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) - compute-end = flush-pkt / PKT-LINE("done") + depth = 1*DIGIT ---- Clients MUST send all the obj-ids it wants from the reference @@ -215,21 +217,64 @@ discovery phase as 'want' lines. Clients MUST send at least one obj-id in a 'want' command which did not appear in the response obtained through ref discovery. -If client is requesting a shallow clone, it will now send a 'deepen' -line with the depth it is requesting. +The client MUST write all obj-ids which it only has shallow copies +of (meaning that it does not have the parents of a commit) as +'shallow' lines so that the server is aware of the limitations of +the client's history. Clients MUST NOT mention an obj-id which +it does not know exists on the server. + +The client now sends the maximum commit history depth it wants for +this transaction, which is the number of commits it wants from the +tip of the history, if any, as a 'deepen' line. A depth of 0 is the +same as not making a depth request. The client does not want to receive +any commits beyond this depth, nor objects needed only to complete +those commits. Commits whose parents are not received as a result are +defined as shallow and marked as such in the server. This information +is sent back to the client in the next step. + +Once all the 'want's and 'shallow's (and optional 'deepen') are +transferred, clients MUST send a flush-pkt, to tell the server side +that it is done sending the list. + +Otherwise, if the client sent a positive depth request, the server +will determine which commits will and will not be shallow and +send this information to the client. If the client did not request +a positive depth, this step is skipped. -Once all the "want"s (and optional 'deepen') are transferred, -clients MUST send a flush-pkt. If the client has all the references -on the server, client flushes and disconnects. +---- + shallow-update = *shallow-line + *unshallow-line + flush-pkt -TODO: shallow/unshallow response and document the deepen command in the ABNF. + shallow-line = PKT-LINE("shallow" SP obj-id) + + unshallow-line = PKT-LINE("unshallow" SP obj-id) +---- + +If the client has requested a positive depth, the server will compute +the set of commits which are no deeper than the desired depth, starting +at the client's wants. The server writes 'shallow' lines for each +commit whose parents will not be sent as a result. The server writes +an 'unshallow' line for each commit which the client has indicated is +shallow, but is no longer shallow at the currently requested depth +(that is, its parents will now be sent). The server MUST NOT mark +as unshallow anything which the client has not indicated was shallow. Now the client will send a list of the obj-ids it has using 'have' -lines. In multi_ack mode, the canonical implementation will send up -to 32 of these at a time, then will send a flush-pkt. The canonical -implementation will skip ahead and send the next 32 immediately, -so that there is always a block of 32 "in-flight on the wire" at a -time. +lines, so the server can make a packfile that only contains the objects +that the client needs. In multi_ack mode, the canonical implementation +will send up to 32 of these at a time, then will send a flush-pkt. The +canonical implementation will skip ahead and send the next 32 immediately, +so that there is always a block of 32 "in-flight on the wire" at a time. + +---- + upload-haves = have-list + compute-end + + have-list = *have-line + have-line = PKT-LINE("have" SP obj-id LF) + compute-end = flush-pkt / PKT-LINE("done") +---- If the server reads 'have' lines, it then will respond by ACKing any of the obj-ids the client said it had that the server also has. The |