diff options
Diffstat (limited to 'Documentation')
30 files changed, 989 insertions, 215 deletions
diff --git a/Documentation/RelNotes-1.7.1.1.txt b/Documentation/RelNotes-1.7.1.1.txt new file mode 100644 index 000000000..3f6b3148a --- /dev/null +++ b/Documentation/RelNotes-1.7.1.1.txt @@ -0,0 +1,96 @@ +Git v1.7.1.1 Release Notes +========================== + +Fixes since v1.7.1 +------------------ + + * Authentication over http transport can now be made lazily, in that the + request can first go to a URL without username, get a 401 response and + then the client will ask for the username to use. + + * We used to mistakenly think "../work" is a subdirectory of the current + directory when we are in "../work-xyz". + + * The attribute mechanism now allows an entry that uses an attribute + macro that set/unset one attribute, immediately followed by an + overriding setting; this makes attribute macros much easier to use. + + * We didn't recognize timezone "Z" as a synonym for "UTC" (75b37e70). + + * In 1.7.0, read-tree and user commands that use the mechanism such as + checkout and merge were fixed to handle switching between branches one + of which has a file while the other has a directory at the same path + correctly even when there are some "confusing" pathnames in them. But + the algorithm used for this fix was suboptimal and had a terrible + performance degradation especially in larger trees. + + * "git am -3" did not show diagnosis when the patch in the message was corrupt. + + * After "git apply --whitespace=fix" removed trailing blank lines in an + patch in a patch series, it failed to apply later patches that depend + on the presence of such blank lines. + + * "git bundle --stdin" segfaulted. + + * "git checkout" and "git rebase" overwrote paths that are marked "assume + unchanged". + + * "git commit --amend" on a commit with an invalid author-name line that + lacks the display name didn't work. + + * "git describe" did not tie-break tags that point at the same commit + correctly; newer ones are preferred by paying attention to the + tagger date now. + + * "git diff" used to tell underlying xdiff machinery to work very hard to + minimize the output, but this often was spending too many extra cycles + for very little gain. + + * "git diff --color" did not paint extended diff headers per line + (i.e. the coloring escape sequence didn't end at the end of line), + which confused "less -R". + + * "git fetch" over HTTP verifies the downloaded packfiles more robustly. + + * The memory usage by "git index-pack" (run during "git fetch" and "git + push") got leaner. + + * "GIT_DIR=foo.git git init --bare bar.git" created foo.git instead of bar.git. + + * "git log --abbrev=$num --format='%h' ignored --abbrev=$num. + + * "git ls-files ../out/side/cwd" refused to work. + + * "git merge --log" used to replace the custom message given by "-m" with + the shortlog, instead of appending to it. + + * "git notes copy" without any other argument segfaulted. + + * "git pull" accepted "--dry-run", gave it to underlying "git fetch" but + ignored the option itself, resulting in a bogus attempt to merge + unrelated commit. + + * "git rebase" did not faithfully reproduce a malformed author ident, that + is often seen in a repository converted from foreign SCMs. + + * "git reset --hard" started from a wrong directory and a working tree in + a nonstandard location is in use got confused. + + * "git send-email" lacked a way to specify the domainname used in the + EHLO/HELO exchange, causing rejected connection from picky servers. + It learned --smtp-domain option to solve this issue. + + * "git send-email" did not declare a content-transfer-encoding and + content-type even when its payload needs to be sent in 8-bit. + + * "git show -C -C" and other corner cases lost diff metainfo output + in 1.7.0. + + * "git stash" incorrectly lost paths in the working tree that were + previously removed from the index. + + * "git status" stopped refreshing the index by mistake in 1.7.1. + + * "git status" showed excess "hints" even when advice.statusHints is set to false. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.2.txt b/Documentation/RelNotes-1.7.2.txt index 37781b4f1..8ed740626 100644 --- a/Documentation/RelNotes-1.7.2.txt +++ b/Documentation/RelNotes-1.7.2.txt @@ -4,37 +4,151 @@ Git v1.7.2 Release Notes (draft) Updates since v1.7.1 -------------------- - * After "git apply --whitespace=fix" removed trailing blank lines in an - patch in a patch series, it failed to apply later patches that depend - on the presense of such blank lines. + * core.eol configuration and eol attribute are the new way to control + the end of line conventions for files in the working tree; + core.autocrlf overrides it, keeping the traditional behaviour by + default. + + * The whitespace rules used in "git apply --whitespace" and "git diff" + gained a new member in the family (tab-in-indent) to help projects with + policy to indent only with spaces. + + * When working from a subdirectory, by default, git does not look for its + metadirectory ".git" across filesystems, primarily to help people who + have invocations of git in their custom PS1 prompts, as being outside + of a git repository would look for ".git" all the way up to the root + directory, and NFS mounts are often slow. DISCOVERY_ACROSS_FILESYSTEM + environment variable can be used to tell git not to stop at a + filesystem boundary. + + * Usage help messages generated by parse-options library (i.e. most + of the Porcelain commands) are sent to the standard output now. + + * ':/<string>' notation to look for a commit now takes regular expression + and it is not anchored at the beginning of the commit log message + anymore (this is a backward incompatible change). + + * "git" wrapper learned "-c name=value" option to override configuration + variable from the command line. + + * Improved portability for various platforms including older SunOS, + HP-UX 10/11, AIX, Tru64, etc. and platforms with Python 2.4. + + * The message from "git am -3" has been improved when conflict + resolution ended up making the patch a no-op. + + * "git blame" applies the textconv filter to the contents it works + on, when available. + + * "git checkout --orphan newbranch" is similar to "-b newbranch" but + prepares to create a root commit that is not connected to any existing + commit. + + * "git cherry-pick" learned to pick a range of commits (e.g. "cherry-pick + A..B"); this does not have nicer sequencing control "rebase [-i]" has, + though. + + * "git cvsserver" can be told to use pserver; its password file can be + stored outside the repository. * The output from the textconv filter used by "git diff" can be cached to speed up their reuse. - * "git send-email" learned --smtp-domain option to specify the domainname - used in the EHLO/HELO exchange. + * "git diff --word-diff=<mode>" extends the existing "--color-words" + option, making it more useful in color-challenged environments. + + * The regexp to detect function headers used by "git diff" for PHP has + been enhanced for visibility modifiers (public, protected, etc.) to + better support PHP5. + + * "diff.noprefix" configuration variable can be used to implicitly + ask for "diff --no-prefix" behaviour. + + * "git for-each-ref" learned "%(objectname:short)" that gives the object + name abbreviated. + + * "git format-patch" learned --signature option and format.signature + configuration variable to customize the e-mail signature used in the + output. + + * Various options to "git grep" (e.g. --count, --name-only) work better + with binary files. + + * "git help -w" learned "chrome" and "chromium" browsers. + + * "git log --follow <path>" follows across copies (it used to only follow + renames). This may make the processing more expensive. + + * "git log --pretty=format:<template>" specifier learned "% <something>" + magic that inserts a space only when %<something> expands to a + non-empty string; this is similar to "%+<something>" magic, but is + useful in a context to generate a single line output. + + * "git notes prune" learned "-n" (dry-run) and "-v" options, similar to + what "git prune" has. + + * "git patch-id" can be fed a mbox without getting confused by the + signature line in the format-patch output. + + * "git remote" learned "set-branches" subcommand. * "git revert" learned --strategy option to specify the merge strategy. - * The whitespace rules used in "git apply --whitespace" and "git diff" - gained a new member in the family (tab-in-indent) to help projects with - policy to indent only with spaces. + * "git rev-list A..B" learned --ancestry-path option to further limit + the result to the commits that are on the ancestry chain between A and + B (i.e. commits that are not descendants of A are excluded). + + * "git show -5" is equivalent to "git show --do-walk 5"; this is similar + to the update to make "git show master..next" walk the history, + introduced in 1.6.4. + + * "git status [-s] --ignored" can be used to list ignored paths. + + * "git status -s -b" shows the current branch in the output. - * Authentication over http transport can now be made lazily, in that the - request can first go to a URL without username, get a 401 response and - then the client will ask for the username to use. + * Various "gitweb" enhancements and clean-ups, including syntax + highlighting, "plackup" support for instaweb, .fcgi suffix to run + it as FastCGI script, etc. Fixes since v1.7.1 ------------------ - * In 1.7.1, "git status" stopped refreshing the index by mistake. - All of the fixes in v1.7.1.X maintenance series are included in this release, unless otherwise noted. + * We didn't URL decode "file:///path/to/repo" correctly when path/to/repo + had percent-encoded characters (638794c, 9d2e942). + + * "git commit" did not honor GIT_REFLOG_ACTION environment variable, resulting + reflog messages for cherry-pick and revert actions to be recorded as "commit". + + * "git clone/fetch/pull" issued an incorrect error message when a ref and + a symref that points to the ref were updated at the same time. This + obviously would update them to the same value, and should not result in + an error condition (0e71bc3). + + * "git clone" did not configure remote.origin.url correctly for bare + clones (df61c889). + + * "git diff" inside a tree with many pathnames that have certain + characters has become very slow in 1.7.0 by mistake (will merge + e53e6b443 to 'maint'). + + * "git diff --graph" works better with "--color-words" and other options + (81fa024..4297c0a). + + * "git diff" could show ambiguous abbreviation of blob object names on + its "index" line (3e5a188). + + * "git rebase" did not faithfully reproduce a malformed author ident, that + is often seen in a repository converted from foreign SCMs (43c23251). + + * "git reset --hard" started from a wrong directory and a working tree in + a nonstandard location is in use got confused (560fb6a1). + -- exec >/var/tmp/1 -O=v1.7.1-77-gb751157 -echo O=$(git describe master) -git shortlog --no-merges master ^maint ^$O +O=v1.7.1-592-gcf4403a +echo O=$(git describe HEAD) +git shortlog --no-merges HEAD ^maint ^$O diff --git a/Documentation/config.txt b/Documentation/config.txt index 85f763c4d..4c491045c 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -196,20 +196,17 @@ core.quotepath:: quoted without `-z` regardless of the setting of this variable. -core.autocrlf:: - If true, makes git convert `CRLF` at the end of lines in text files to - `LF` when reading from the work tree, and convert in reverse when - writing to the work tree. The variable can be set to - 'input', in which case the conversion happens only while - reading from the work tree but files are written out to the work - tree with `LF` at the end of lines. A file is considered - "text" (i.e. be subjected to the autocrlf mechanism) based on - the file's `crlf` attribute, or if `crlf` is unspecified, - based on the file's contents. See linkgit:gitattributes[5]. +core.eol:: + Sets the line ending type to use in the working directory for + files that have the `text` property set. Alternatives are + 'lf', 'crlf' and 'native', which uses the platform's native + line ending. The default value is `native`. See + linkgit:gitattributes[5] for more information on end-of-line + conversion. core.safecrlf:: - If true, makes git check if converting `CRLF` as controlled by - `core.autocrlf` is reversible. Git will verify if a command + If true, makes git check if converting `CRLF` is reversible when + end-of-line conversion is active. 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 @@ -219,7 +216,7 @@ core.safecrlf:: 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 +When it is enabled, git 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 @@ -243,15 +240,25 @@ 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 +`core.eol` and `core.autocrlf`, but only for the current one. For +example, a text file with `LF` would be accepted with `core.eol=lf` +and could later be checked out with `core.eol=crlf`, 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.autocrlf:: + Setting this variable to "true" is almost the same as setting + the `text` attribute to "auto" on all files except that text + files are not guaranteed to be normalized: files that contain + `CRLF` in the repository will not be touched. Use this + setting if you want to have `CRLF` line endings in your + working directory even though the repository does not have + normalized line endings. This variable can be set to 'input', + in which case no output conversion is performed. + core.symlinks:: If false, symbolic links are checked out as small plain files that contain the link text. linkgit:git-update-index[1] and @@ -520,18 +527,12 @@ check that makes sure that existing object files will not get overwritten. core.notesRef:: When showing commit messages, also show notes which are stored in - the given ref. This ref is expected to contain files named - after the full SHA-1 of the commit they annotate. The ref - must be fully qualified. + the given ref. The ref must be fully qualified. If the given + ref does not exist, it is not an error but means that no + notes should be printed. + -If such a file exists in the given ref, the referenced blob is read, and -appended to the commit message, separated by a "Notes (<refname>):" -line (shortened to "Notes:" in the case of "refs/notes/commits"). If the -given ref itself does not exist, it is not an error, but means that no -notes should be printed. -+ -This setting defaults to "refs/notes/commits", and can be overridden by -the `GIT_NOTES_REF` environment variable. +This setting defaults to "refs/notes/commits", and it can be overridden by +the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1]. core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in @@ -798,6 +799,8 @@ diff.mnemonicprefix:: standard "a/" and "b/" depending on what is being compared. When this configuration is in effect, reverse diff output also swaps the order of the prefixes: +diff.noprefix:: + If set, 'git diff' does not show any source or destination prefix. `git diff`;; compares the (i)ndex and the (w)ork tree; `git diff HEAD`;; @@ -886,6 +889,12 @@ format.subjectprefix:: The default for format-patch is to output files with the '[PATCH]' subject prefix. Use this variable to change that prefix. +format.signature:: + The default for format-patch is to output a signature containing + the git version number. Use this variable to change that default. + Set this variable to the empty string ("") to suppress + signature generation. + format.suffix:: The default for format-patch is to output files with the suffix `.patch`. Use this variable to change that suffix (make sure to @@ -983,13 +992,15 @@ gitcvs.logfile:: various stuff. See linkgit:git-cvsserver[1]. gitcvs.usecrlfattr:: - If true, the server will look up the `crlf` attribute for - files to determine the '-k' modes to use. If `crlf` is set, - the '-k' mode will be left blank, so cvs clients will - treat it as text. If `crlf` is explicitly unset, the file + If true, the server will look up the end-of-line conversion + attributes for files to determine the '-k' modes to use. If + the attributes force git to treat a file as text, + the '-k' mode will be left blank so cvs clients will + treat it as text. If they suppress text conversion, the file will be set with '-kb' mode, which suppresses any newline munging - the client might otherwise do. If `crlf` is not specified, - then 'gitcvs.allbinary' is used. See linkgit:gitattributes[5]. + the client might otherwise do. If the attributes do not allow + the file type to be determined, then 'gitcvs.allbinary' is + used. See linkgit:gitattributes[5]. gitcvs.allbinary:: This is used if 'gitcvs.usecrlfattr' does not resolve @@ -1481,6 +1492,16 @@ pager.<cmd>:: it takes precedence over this option. To disable pagination for all commands, set `core.pager` or `GIT_PAGER` to `cat`. +pretty.<name>:: + Alias for a --pretty= format string, as specified in + linkgit:git-log[1]. Any aliases defined here can be used just + as the built-in pretty formats could. For example, + running `git config pretty.changelog "format:{asterisk} %H %s"` + would cause the invocation `git log --pretty=changelog` + to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + Note that an alias with the same name as a built-in format + will be silently ignored. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 0d89aaaf2..2371262b1 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -210,7 +210,14 @@ endif::git-format-patch[] Break complete rewrite changes into pairs of delete and create. -M:: +ifndef::git-log[] Detect renames. +endif::git-log[] +ifdef::git-log[] + If generating diffs, detect and report renames for each commit. + For following files across renames while traversing history, see + `--follow`. +endif::git-log[] -C:: Detect copies as well as renames. See also `--find-copies-harder`. @@ -321,8 +328,14 @@ endif::git-format-patch[] --no-ext-diff:: Disallow external diff drivers. ---ignore-submodules:: - Ignore changes to submodules in the diff generation. +--ignore-submodules[=<when>]:: + Ignore changes to submodules in the diff generation. <when> can be + either "untracked", "dirty" or "all", which is the default. When + "untracked" is used submodules are not considered dirty when they only + contain untracked content (but they are still scanned for modified + content). Using "dirty" ignores all changes to the work tree of submodules, + only changes to the commits stored in the superproject are shown (this was + the behavior until 1.7.0). Using "all" hides all changes to submodules. --src-prefix=<prefix>:: Show the given source prefix instead of "a/". diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 51cbeb703..74741a42f 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -266,9 +266,9 @@ patch:: y - stage this hunk n - do not stage this hunk - q - quit, do not stage this hunk nor any of the remaining ones - a - stage this and all the remaining hunks in the file - d - do not stage this hunk nor any of the remaining hunks in the file + q - quit; do not stage this hunk nor any of the remaining ones + a - stage this hunk and all later hunks in the file + d - do not stage this hunk nor any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 58c8d6577..9ebbe9402 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,14 +9,15 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' (-t | -s | -e | -p | <type>) <object> +'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object> 'git cat-file' (--batch | --batch-check) < <list-of-objects> DESCRIPTION ----------- In its first form, the command provides the content or the type of an object in the repository. The type is required unless '-t' or '-p' is used to find the -object type, or '-s' is used to find the object size. +object type, or '-s' is used to find the object size, or '--textconv' is used +(which implies type "blob"). In the second form, a list of objects (separated by linefeeds) is provided on stdin, and the SHA1, type, and size of each object is printed on stdout. @@ -51,6 +52,11 @@ OPTIONS or to ask for a "blob" with <object> being a tag object that points at it. +--textconv:: + Show the content as transformed by a textconv filter. In this case, + <object> has be of the form <treeish>:<path>, or :<path> in order + to apply the filter to the content recorded in the index at <path>. + --batch:: Print the SHA1, type, size, and contents of each object provided on stdin. May not be combined with any other options or arguments. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index afda5c36b..261dd90c3 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -15,33 +15,41 @@ SYNOPSIS DESCRIPTION ----------- - -When <paths> are not given, this command switches branches by -updating the index, working tree, and HEAD to reflect the specified +Updates files in the working tree to match the version in the index +or the specified tree. If no paths are given, 'git checkout' will +also update `HEAD` to set the specified branch as the current branch. -If `-b` is given, a new branch is created and checked out, as if -linkgit:git-branch[1] were called; in this case you can -use the --track or --no-track options, which will be passed to `git -branch`. As a convenience, --track without `-b` implies branch -creation; see the description of --track below. - -When <paths> or --patch are given, this command does *not* switch -branches. It updates the named paths in the working tree from -the index file, or from a named <tree-ish> (most often a commit). In -this case, the `-b` and `--track` options are meaningless and giving -either of them results in an error. The <tree-ish> argument can be -used to specify a specific tree-ish (i.e. commit, tag or tree) -to update the index for the given paths before updating the -working tree. - -The index may contain unmerged entries after a failed merge. By -default, if you try to check out such an entry from the index, the +'git checkout' [<branch>]:: +'git checkout' -b <new branch> [<start point>]:: + + This form switches branches by updating the index, working + tree, and HEAD to reflect the specified branch. ++ +If `-b` is given, a new branch is created as if linkgit:git-branch[1] +were called and then checked out; in this case you can +use the `--track` or `--no-track` options, which will be passed to +'git branch'. As a convenience, `--track` without `-b` implies branch +creation; see the description of `--track` below. + +'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...:: + + When <paths> or `--patch` are given, 'git checkout' *not* switch + branches. It updates the named paths in the working tree from + the index file or from a named <tree-ish> (most often a commit). In + this case, the `-b` and `--track` options are meaningless and giving + either of them results in an error. The <tree-ish> argument can be + used to specify a specific tree-ish (i.e. commit, tag or tree) + to update the index for the given paths before updating the + working tree. ++ +The index may contain unmerged entries because of a previous failed merge. +By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. -Using -f will ignore these unmerged entries. The contents from a +Using `-f` will ignore these unmerged entries. The contents from a specific side of the merge can be checked out of the index by -using --ours or --theirs. With -m, changes made to the working tree -file can be discarded to recreate the original conflicted merge result. +using `--ours` or `--theirs`. With `-m`, changes made to the working tree +file can be discarded to re-create the original conflicted merge result. OPTIONS ------- @@ -91,22 +99,29 @@ explicitly give a name with '-b' in such a case. details. --orphan:: - Create a new branch named <new_branch>, unparented to any other - branch. The new branch you switch to does not have any commit - and after the first one it will become the root of a new history - completely unconnected from all the other branches. + Create a new 'orphan' branch, named <new_branch>, started from + <start_point> and switch to it. The first commit made on this + new branch will have no parents and it will be the root of a new + history totally disconnected from all the other branches and + commits. ++ +The index and the working tree are adjusted as if you had previously run +"git checkout <start_point>". This allows you to start a new history +that records a set of paths similar to <start_point> by easily running +"git commit -a" to make the root commit. + -When you use "--orphan", the index and the working tree are kept intact. -This allows you to start a new history that records set of paths similar -to that of the start-point commit, which is useful when you want to keep -different branches for different audiences you are working to like when -you have an open source and commercial versions of a software, for example. +This can be useful when you want to publish the tree from a commit +without exposing its full history. You might want to do this to publish +an open source branch of a project whose current tree is "clean", but +whose full history contains proprietary or otherwise encumbered bits of +code. + -If you want to start a disconnected history that records set of paths -totally different from the original branch, you may want to first clear -the index and the working tree, by running "git rm -rf ." from the -top-level of the working tree, before preparing your files (by copying -from elsewhere, extracting a tarball, etc.) in the working tree. +If you want to start a disconnected history that records a set of paths +that is totally different from the one of <start_point>, then you should +clear the index and the working tree right after creating the orphan +branch by running "git rm -rf ." from the top level of the working tree. +Afterwards you will be ready to prepare your new files, repopulating the +working tree, by copying them from elsewhere, extracting a tarball, etc. -m:: --merge:: diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index d71607a85..bcb4c758b 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -3,24 +3,28 @@ git-cherry-pick(1) NAME ---- -git-cherry-pick - Apply the change introduced by an existing commit +git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit> +'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>... DESCRIPTION ----------- -Given one existing commit, apply the change the patch introduces, and record a -new commit that records it. This requires your working tree to be clean (no -modifications from the HEAD commit). + +Given one or more existing commits, apply the change each one +introduces, recording a new commit for each. This requires your +working tree to be clean (no modifications from the HEAD commit). OPTIONS ------- -<commit>:: - Commit to cherry-pick. +<commit>...:: + Commits to cherry-pick. For a more complete list of ways to spell commits, see the "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + Sets of commits can be passed but no traversal is done by + default, as if the '--no-walk' option was specified, see + linkgit:git-rev-list[1]. -e:: --edit:: @@ -55,10 +59,10 @@ OPTIONS -n:: --no-commit:: - Usually the command automatically creates a commit. - This flag applies the change necessary to cherry-pick - the named commit to your working tree and the index, - but does not make the commit. In addition, when this + Usually the command automatically creates a sequence of commits. + This flag applies the changes necessary to cherry-pick + each named commit to your working tree and the index, + without making any commit. In addition, when this option is used, your index does not have to match the HEAD commit. The cherry-pick is done against the beginning state of your index. @@ -75,6 +79,40 @@ effect to your index in a row. cherry-pick'ed commit, then a fast forward to this commit will be performed. +EXAMPLES +-------- +git cherry-pick master:: + + Apply the change introduced by the commit at the tip of the + master branch and create a new commit with this change. + +git cherry-pick ..master:: +git cherry-pick ^HEAD master:: + + Apply the changes introduced by all commits that are ancestors + of master but not of HEAD to produce new commits. + +git cherry-pick master\~4 master~2:: + + Apply the changes introduced by the fifth and third last + commits pointed to by master and create 2 new commits with + these changes. + +git cherry-pick -n master~1 next:: + + Apply to the working tree and the index the changes introduced + by the second last commit pointed to by master and by the last + commit pointed to by next, but do not create any commit with + these changes. + +git cherry-pick --ff ..next:: + + If history is linear and HEAD is an ancestor of next, update + the working tree and advance the HEAD pointer to match next. + Otherwise, apply the changes introduced by those commits that + are in next but not HEAD to the current branch, creating a new + commit for each new change. + Author ------ Written by Junio C Hamano <gitster@pobox.com> @@ -83,6 +121,10 @@ Documentation -------------- Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-revert[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 32c482f33..c28603ecf 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -95,10 +95,11 @@ OPTIONS read the message from the standard input. --author=<author>:: - Override the author name used in the commit. You can use the - standard `A U Thor <author@example.com>` format. Otherwise, - an existing commit that matches the given string and its author - name is used. + Override the commit author. Specify an explicit author using the + standard `A U Thor <author@example.com>` format. Otherwise <author> + is assumed to be a pattern and is used to search for an existing + commit by that author (i.e. rev-list --all -i --author=<author>); + the commit author is then copied from the first such commit found. --date=<date>:: Override the author date used in the commit. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index dbb053ee1..7004dd2de 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -72,9 +72,6 @@ plugin. Most functionality works fine with both of these clients. LIMITATIONS ----------- -Currently cvsserver works over SSH connections for read/write clients, and -over pserver for anonymous CVS access. - CVS clients cannot tag, branch or perform GIT merges. 'git-cvsserver' maps GIT branches to CVS modules. This is very different @@ -84,7 +81,7 @@ one or more directories. INSTALLATION ------------ -1. If you are going to offer anonymous CVS access via pserver, add a line in +1. If you are going to offer CVS access via pserver, add a line in /etc/inetd.conf like + -- @@ -101,6 +98,38 @@ looks like cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver ------ + +Only anonymous access is provided by pserve by default. To commit you +will have to create pserver accounts, simply add a gitcvs.authdb +setting in the config file of the repositories you want the cvsserver +to allow writes to, for example: + +------ + + [gitcvs] + authdb = /etc/cvsserver/passwd + +------ +The format of these files is username followed by the crypted password, +for example: + +------ + myuser:$1Oyx5r9mdGZ2 + myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./ +------ +You can use the 'htpasswd' facility that comes with Apache to make these +files, but Apache's MD5 crypt method differs from the one used by most C +library's crypt() function, so don't use the -m option. + +Alternatively you can produce the password with perl's crypt() operator: +----- + perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password +----- + +Then provide your password via the pserver method, for example: +------ + cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name> +------ No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename 'git-cvsserver' to `cvs`. @@ -340,16 +369,13 @@ By default the server leaves the '-k' mode blank for all files, which causes the cvs client to treat them as a text files, subject to crlf conversion on some platforms. -You can make the server use `crlf` attributes to set the '-k' modes -for files by setting the `gitcvs.usecrlfattr` config variable. -In this case, if `crlf` is explicitly unset ('-crlf'), then the -server will set '-kb' mode for binary files. If `crlf` is set, -then the '-k' mode will explicitly be left blank. See -also linkgit:gitattributes[5] for more information about the `crlf` -attribute. +You can make the server use the end-of-line conversion attributes to +set the '-k' modes for files by setting the `gitcvs.usecrlfattr` +config variable. See linkgit:gitattributes[5] for more information +about end-of-line conversion. Alternatively, if `gitcvs.usecrlfattr` config is not enabled -or if the `crlf` attribute is unspecified for a filename, then +or the attributes do not allow automatic detection for a filename, then the server uses the `gitcvs.allbinary` config for the default setting. If `gitcvs.allbinary` is set, then file not otherwise specified will default to '-kb' mode. Otherwise the '-k' mode diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 835fb7135..c8c81e843 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -13,6 +13,7 @@ SYNOPSIS [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] + [--signature=<signature> | --no-signature] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] @@ -180,6 +181,12 @@ will want to ensure that threading is disabled for `git send-email`. containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--[no]-signature=<signature>:: + Add a signature to each message produced. Per RFC 3676 the signature + is separated from the body by a line with '-- ' on it. If the + signature option is omitted the signature defaults to the git version + number. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 4b32322a6..912bddd7b 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -183,7 +183,7 @@ OPTIONS Examples -------- -git grep 'time_t' -- '*.[ch]':: +git grep 'time_t' \-- '*.[ch]':: Looks for `time_t` in all tracked .c and .h files in the working directory and its subdirectories. diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index a1f17df07..2c3c4d299 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -29,7 +29,7 @@ OPTIONS The HTTP daemon command-line that will be executed. Command-line options may be specified here, and the configuration file will be added at the end of the command-line. - Currently apache2, lighttpd, mongoose and webrick are supported. + Currently apache2, lighttpd, mongoose, plackup and webrick are supported. (Default: lighttpd) -m:: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index a2d55f974..0e6ff3182 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -133,6 +133,48 @@ Discussion include::i18n.txt[] +Configuration +------------- + +See linkgit:git-config[1] for core variables and linkgit:git-diff[1] +for settings related to diff generation. + +format.pretty:: + Default for the `--format` option. (See "PRETTY FORMATS" above.) + Defaults to "medium". + +i18n.logOutputEncoding:: + Encoding to use when displaying logs. (See "Discussion", above.) + Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + otherwise. + +log.date:: + Default format for human-readable dates. (Compare the + `--date` option.) Defaults to "default", which means to write + dates like `Sat May 8 19:35:34 2010 -0500`. + +log.showroot:: + If `false`, 'git log' and related commands will not treat the + initial commit as a big creation event. Any root commits in + `git log -p` output would be shown without a diff attached. + The default is `true`. + +mailmap.file:: + See linkgit:git-shortlog[1]. + +notes.displayRef:: + Which refs, in addition to the default set by `core.notesRef` + or 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'log' family of commands. See + linkgit:git-notes[1]. ++ +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, +overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, +and supplemented by the `--show-notes` option. Author ------ diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index e3d58cbac..3ea5aad56 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -40,16 +40,16 @@ OPTIONS -u:: The commit log message, author name and author email are taken from the e-mail, and after minimally decoding MIME - transfer encoding, re-coded in UTF-8 by transliterating + transfer encoding, re-coded in the charset specified by + i18n.commitencoding (defaulting to UTF-8) by transliterating them. This used to be optional but now it is the default. + Note that the patch is always used as-is without charset conversion, even with this flag. --encoding=<encoding>:: - Similar to -u but if the local convention is different - from what is specified by i18n.commitencoding, this flag - can be used to override it. + Similar to -u. But when re-coding, the charset specified here is + used instead of the one specified by i18n.commitencoding or UTF-8. -n:: Disable all charset re-coding of the metadata. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index c2325ef90..84043cc5b 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -58,7 +58,12 @@ include::merge-options.txt[] -m <msg>:: Set the commit message to be used for the merge commit (in - case one is created). The 'git fmt-merge-msg' command can be + case one is created). + + If `--log` is specified, a shortlog of the commits being merged + will be appended to the specified message. + + The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' invocations. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 4e5113b83..5540af5d1 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -3,7 +3,7 @@ git-notes(1) NAME ---- -git-notes - Add/inspect object notes +git-notes - Add or inspect object notes SYNOPSIS -------- @@ -15,29 +15,31 @@ SYNOPSIS 'git notes' edit [<object>] 'git notes' show [<object>] 'git notes' remove [<object>] -'git notes' prune +'git notes' prune [-n | -v] DESCRIPTION ----------- -This command allows you to add/remove notes to/from objects, without -changing the objects themselves. +Adds, removes, or reads notes attached to objects, without touching +the objects themselves. -A typical use of notes is to extend a commit message without having -to change the commit itself. Such commit notes can be shown by `git log` -along with the original commit message. To discern these notes from the +By default, notes are saved to and read from `refs/notes/commits`, but +this default can be overridden. See the OPTIONS, CONFIGURATION, and +ENVIRONMENT sections below. If this ref does not exist, it will be +quietly created when it is first needed to store a note. + +A typical use of notes is to supplement a commit message without +changing the commit itself. Notes can be shown by 'git log' along with +the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or -"Notes:" for the default setting). +"Notes:" for `refs/notes/commits`). -This command always manipulates the notes specified in "core.notesRef" -(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF. -To change which notes are shown by 'git-log', see the -"notes.displayRef" configuration. +To change which notes are shown by 'git log', see the +"notes.displayRef" configuration in linkgit:git-log[1]. -See the description of "notes.rewrite.<command>" in -linkgit:git-config[1] for a way of carrying your notes across commands -that rewrite commits. +See the "notes.rewrite.<command>" configuration for a way to carry +notes across commands that rewrite commits. SUBCOMMANDS @@ -101,15 +103,20 @@ OPTIONS Use the given note message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -F <file>:: --file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -C <object>:: --reuse-message=<object>:: - Reuse the note message from the given note object. + Take the note message from the given blob object (for + example, another note). -c <object>:: --reedit-message=<object>:: @@ -117,22 +124,151 @@ OPTIONS the user can further edit the note message. --ref <ref>:: - Manipulate the notes tree in <ref>. This overrides both - GIT_NOTES_REF and the "core.notesRef" configuration. The ref + Manipulate the notes tree in <ref>. This overrides + 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref is taken to be in `refs/notes/` if it is not qualified. +-n:: + Do not remove anything; just report the object names whose notes + would be removed. + +-v:: + Report all object names whose notes are removed. + + +DISCUSSION +---------- -NOTES ------ +Commit notes are blobs containing extra information about an object +(usually information to supplement a commit's message). These blobs +are taken from notes refs. A notes ref is usually a branch which +contains "files" whose paths are the object names for the objects +they describe, with some directory separators included for performance +reasons footnote:[Permitted pathnames have the form +'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory +names of two hexadecimal digits each followed by a filename with the +rest of the object ID.]. Every notes change creates a new commit at the specified notes ref. You can therefore inspect the history of the notes by invoking, e.g., -`git log -p notes/commits`. +`git log -p notes/commits`. Currently the commit message only records +which operation triggered the update, and the commit authorship is +determined according to the usual rules (see linkgit:git-commit[1]). +These details may change in the future. + +It is also permitted for a notes ref to point directly to a tree +object, in which case the history of the notes can be read with +`git log -p -g <refname>`. + + +EXAMPLES +-------- + +You can use notes to add annotations with information that was not +available at the time a commit was written. + +------------ +$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano <gitster@pobox.com> + +Notes: + Tested-by: Johannes Sixt <j6t@kdbg.org> +------------ + +In principle, a note is a regular Git blob, and any kind of +(non-)format is accepted. You can binary-safely create notes from +arbitrary files using 'git hash-object': + +------------ +$ cc *.c +$ blob=$(git hash-object -w a.out) +$ git notes --ref=built add -C "$blob" HEAD +------------ + +Of course, it doesn't make much sense to display non-text-format notes +with 'git log', so if you use such notes, you'll probably need to write +some special-purpose tools to do something useful with them. + + +CONFIGURATION +------------- -Currently the commit message only records which operation triggered -the update, and the commit authorship is determined according to the -usual rules (see linkgit:git-commit[1]). These details may change in -the future. +core.notesRef:: + Notes ref to read and manipulate instead of + `refs/notes/commits`. Must be an unabbreviated ref name. + This setting can be overridden through the environment and + command line. + +notes.displayRef:: + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'git log' family of commands. + This setting can be overridden on the command line or by the + 'GIT_NOTES_DISPLAY_REF' environment variable. + See linkgit:git-log[1]. + +notes.rewrite.<command>:: + When rewriting commits with <command> (currently `amend` or + `rebase`), if this variable is `false`, git will not copy + notes from the original to the rewritten commit. Defaults to + `true`. See also "`notes.rewriteRef`" below. ++ +This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' +environment variable. + +notes.rewriteMode:: + When copying notes during a rewrite, what to do if the target + commit already has a note. Must be one of `overwrite`, + `concatenate`, and `ignore`. Defaults to `concatenate`. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` +environment variable. + +notes.rewriteRef:: + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. ++ +Does not have a default value; you must configure this variable to +enable note rewriting. ++ +Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. + + +ENVIRONMENT +----------- + +'GIT_NOTES_REF':: + Which ref to manipulate notes from, instead of `refs/notes/commits`. + This overrides the `core.notesRef` setting. + +'GIT_NOTES_DISPLAY_REF':: + Colon-delimited list of refs or globs indicating which refs, + in addition to the default from `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages. + This overrides the `notes.displayRef` setting. ++ +A warning will be issued for refs that do not exist, but a glob that +does not match any refs is silently ignored. + +'GIT_NOTES_REWRITE_MODE':: + When copying notes during a rewrite, what to do if the target + commit already has a note. + Must be one of `overwrite`, `concatenate`, and `ignore`. + This overrides the `core.rewriteMode` setting. + +'GIT_NOTES_REWRITE_REF':: + When rewriting commits, which notes to copy from the original + to the rewritten commit. Must be a colon-delimited list of + refs or globs. ++ +If not set in the environment, the list of notes to copy depends +on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. Author diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 50ba2e469..be23ad235 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -310,6 +310,11 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). -p:: --preserve-merges:: Instead of ignoring merges, try to recreate them. ++ +This uses the `--interactive` machinery internally, but combining it +with the `--interactive` option explicitly is generally not a good +idea unless you know what you are doing (see BUGS below). + --root:: Rebase all commits reachable from <branch>, instead of @@ -611,6 +616,28 @@ The ripple effect of a "hard case" recovery is especially bad: case" recovery too! +BUGS +---- +The todo list presented by `--preserve-merges --interactive` does not +represent the topology of the revision graph. Editing commits and +rewording their commit messages should work fine, but attempts to +reorder commits tend to produce counterintuitive results. + +For example, an attempt to rearrange +------------ +1 --- 2 --- 3 --- 4 --- 5 +------------ +to +------------ +1 --- 2 --- 4 --- 3 --- 5 +------------ +by moving the "pick 4" line will result in the following history: +------------ + 3 + / +1 --- 2 --- 4 --- 5 +------------ + Authors ------ Written by Junio C Hamano <gitster@pobox.com> and diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index ebaaadc17..aa021b0cb 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -14,6 +14,7 @@ SYNOPSIS 'git remote rename' <old> <new> 'git remote rm' <name> 'git remote set-head' <name> (-a | -d | <branch>) +'git remote set-branches' <name> [--add] <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> @@ -110,6 +111,18 @@ remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/master` already exists; if not it must be fetched first. + +'set-branches':: + +Changes the list of branches tracked by the named remote. +This can be used to track a subset of the available remote branches +after the initial setup for a remote. ++ +The named branches will be interpreted as if specified with the +`-t` option on the 'git remote add' command line. ++ +With `--add`, instead of replacing the list of currently tracked +branches, adds to that list. + 'set-url':: Changes URL remote points to. Sets first URL remote points to matching diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index c66bf8072..dea4f5352 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -3,20 +3,22 @@ git-revert(1) NAME ---- -git-revert - Revert an existing commit +git-revert - Revert some existing commits SYNOPSIS -------- -'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit> +'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>... DESCRIPTION ----------- -Given one existing commit, revert the change the patch introduces, and record a -new commit that records it. This requires your working tree to be clean (no -modifications from the HEAD commit). -Note: 'git revert' is used to record a new commit to reverse the -effect of an earlier commit (often a faulty one). If you want to +Given one or more existing commits, revert the changes that the +related patches introduce, and record some new commits that record +them. This requires your working tree to be clean (no modifications +from the HEAD commit). + +Note: 'git revert' is used to record some new commits to reverse the +effect of some earlier commits (often only a faulty one). If you want to throw away all uncommitted changes in your working directory, you should see linkgit:git-reset[1], particularly the '--hard' option. If you want to extract specific files as they were in another commit, you @@ -26,10 +28,13 @@ both will discard uncommitted changes in your working directory. OPTIONS ------- -<commit>:: - Commit to revert. +<commit>...:: + Commits to revert. For a more complete list of ways to spell commit names, see "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. + Sets of commits can also be given but no traversal is done by + default, see linkgit:git-rev-list[1] and its '--no-walk' + option. -e:: --edit:: @@ -59,11 +64,11 @@ more details. -n:: --no-commit:: - Usually the command automatically creates a commit with - a commit log message stating which commit was - reverted. This flag applies the change necessary - to revert the named commit to your working tree - and the index, but does not make the commit. In addition, + Usually the command automatically creates some commits with + commit log messages stating which commits were + reverted. This flag applies the changes necessary + to revert the named commits to your working tree + and the index, but does not make the commits. In addition, when this option is used, your index does not have to match the HEAD commit. The revert is done against the beginning state of your index. @@ -75,6 +80,20 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. +EXAMPLES +-------- +git revert HEAD~3:: + + Revert the changes specified by the fourth last commit in HEAD + and create a new commit with the reverted changes. + +git revert -n master\~5..master~2:: + + Revert the changes done by commits from the fifth last commit + in master (included) to the third last commit in master + (included), but do not create any commit with the reverted + changes. The revert only modifies the working tree and the + index. Author ------ @@ -84,6 +103,10 @@ Documentation -------------- Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-cherry-pick[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 12622fc49..c28308427 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -101,6 +101,15 @@ See the CONFIGURATION section for 'sendemail.multiedit'. + The --to option must be repeated for each user you want on the to list. +--8bit-encoding=<encoding>:: + When encountering a non-ASCII message or subject that does not + declare its encoding, add headers/quoting to indicate it is + encoded in <encoding>. Default is the value of the + 'sendemail.assume8bitEncoding'; if that is unspecified, this + will be prompted for if any non-ASCII files are encountered. ++ +Note that no attempts whatsoever are made to validate the encoding. + Sending ~~~~~~~ diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 2d4bbfcaf..fd0fe7cb5 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -27,6 +27,10 @@ OPTIONS --short:: Give the output in the short-format. +-b:: +--branch:: + Show the branch and tracking info even in short-format. + --porcelain:: Give the output in a stable, easy-to-parse format for scripts. Currently this is identical to --short output, but is guaranteed @@ -120,6 +124,10 @@ Ignored files are not listed. ? ? untracked ------------------------------------------------- +If -b is used the short-format status is preceded by a line + +## branchname tracking info + There is an alternate -z format recommended for machine parsing. In that format, the status field is the same, but some other things change. First, the '->' is omitted from rename entries and the field @@ -128,7 +136,7 @@ order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL and the terminating newline (but a space still separates the status field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or -backslash-escaping is performed. +backslash-escaping is performed. Fourth, there is no branch line. CONFIGURATION ------------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2502531a3..cdabfd29a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -145,10 +145,12 @@ summary:: foreach:: Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $path and $sha1: + The command has access to the variables $name, $path, $sha1 and + $toplevel: $name is the name of the relevant submodule section in .gitmodules, $path is the name of the submodule directory relative to the - superproject, and $sha1 is the commit as recorded in the superproject. + superproject, $sha1 is the commit as recorded in the superproject, + and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are ignored by this command. Unless given --quiet, foreach prints the name of each submodule before evaluating the command. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 68dc1879f..765d4b312 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -93,8 +93,6 @@ OPTIONS This option can be also used as a coarse file-level mechanism to ignore uncommitted changes in tracked files (akin to what `.gitignore` does for untracked files). -You should remember that an explicit 'git add' operation will -still cause the file to be refreshed from the working tree. Git will fail (gracefully) in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream, diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 0523a5769..564586b94 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -92,53 +92,154 @@ such as 'git checkout' and 'git merge' run. They also affect how git stores the contents you prepare in the working tree in the repository upon 'git add' and 'git commit'. -`crlf` +`text` ^^^^^^ -This attribute controls the line-ending convention. +This attribute enables and controls end-of-line normalization. When a +text file is normalized, its line endings are converted to LF in the +repository. To control what line ending style is used in the working +directory, use the `eol` attribute for a single file and the +`core.eol` configuration variable for all text files. Set:: - Setting the `crlf` attribute on a path is meant to mark - the path as a "text" file. 'core.autocrlf' conversion - takes place without guessing the content type by - inspection. + Setting the `text` attribute on a path enables end-of-line + normalization and marks the path as a text file. End-of-line + conversion takes place without guessing the content type. Unset:: - Unsetting the `crlf` attribute on a path tells git not to + Unsetting the `text` attribute on a path tells git not to attempt any end-of-line conversion upon checkin or checkout. +Set to string value "auto":: + + When `text` is set to "auto", the path is marked for automatic + end-of-line normalization. If git decides that the content is + text, its line endings are normalized to LF on checkin. + Unspecified:: - Unspecified `crlf` attribute tells git to apply the - `core.autocrlf` conversion when the file content looks - like text. + If the `text` attribute is unspecified, git uses the + `core.autocrlf` configuration variable to determine if the + file should be converted. -Set to string value "input":: +Any other value causes git to act as if `text` has been left +unspecified. - This is similar to setting the attribute to `true`, but - also forces git to act as if `core.autocrlf` is set to - `input` for the path. +`eol` +^^^^^ -Any other value set to `crlf` attribute is ignored and git acts -as if the attribute is left unspecified. +This attribute sets a specific line-ending style to be used in the +working directory. It enables end-of-line normalization without any +content checks, effectively setting the `text` attribute. +Set to string value "crlf":: -The `core.autocrlf` conversion -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + This setting forces git to normalize line endings for this + file on checkin and convert them to CRLF when the file is + checked out. + +Set to string value "lf":: + + This setting forces git to normalize line endings to LF on + checkin and prevents conversion to CRLF when the file is + checked out. + +Backwards compatibility with `crlf` attribute +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For backwards compatibility, the `crlf` attribute is interpreted as +follows: + +------------------------ +crlf text +-crlf -text +crlf=input eol=lf +------------------------ + +End-of-line conversion +^^^^^^^^^^^^^^^^^^^^^^ + +While git normally leaves file contents alone, it can be configured to +normalize line endings to LF in the repository and, optionally, to +convert them to CRLF when files are checked out. + +Here is an example that will make git normalize .txt, .vcproj and .sh +files, ensure that .vcproj files have CRLF and .sh files have LF in +the working directory, and prevent .jpg files from being normalized +regardless of their content. + +------------------------ +*.txt text +*.vcproj eol=crlf +*.sh eol=lf +*.jpg -text +------------------------ + +Other source code management systems normalize all text files in their +repositories, and there are two ways to enable similar automatic +normalization in git. + +If you simply want to have CRLF line endings in your working directory +regardless of the repository you are working with, you can set the +config variable "core.autocrlf" without changing any attributes. + +------------------------ +[core] + autocrlf = true +------------------------ + +This does not force normalization of all text files, but does ensure +that text files that you introduce to the repository have their line +endings normalized to LF when they are added, and that files that are +already normalized in the repository stay normalized. + +If you want to interoperate with a source code management system that +enforces end-of-line normalization, or you simply want all text files +in your repository to be normalized, you should instead set the `text` +attribute to "auto" for _all_ files. -If the configuration variable `core.autocrlf` is false, no -conversion is done. +------------------------ +* text=auto +------------------------ + +This ensures that all files that git considers to be text will have +normalized (LF) line endings in the repository. The `core.eol` +configuration variable controls which line endings git will use for +normalized files in your working directory; the default is to use the +native line ending for your platform, or CRLF if `core.autocrlf` is +set. + +NOTE: When `text=auto` normalization is enabled in an existing +repository, any text files containing CRLFs should be normalized. If +they are not they will be normalized the next time someone tries to +change them, causing unfortunate misattribution. From a clean working +directory: + +------------------------------------------------- +$ echo "* text=auto" >>.gitattributes +$ rm .git/index # Remove the index to force git to +$ git reset # re-scan the working directory +$ git status # Show files that will be normalized +$ git add -u +$ git add .gitattributes +$ git commit -m "Introduce end-of-line normalization" +------------------------------------------------- + +If any files that should not be normalized show up in 'git status', +unset their `text` attribute before running 'git add -u'. + +------------------------ +manual.pdf -text +------------------------ -When `core.autocrlf` is true, it means that the platform wants -CRLF line endings for files in the working tree, and you want to -convert them back to the normal LF line endings when checking -in to the repository. +Conversely, text files that git does not detect can have normalization +enabled manually. -When `core.autocrlf` is set to "input", line endings are -converted to LF upon checkin, but there is no conversion done -upon checkout. +------------------------ +weirdchars.txt text +------------------------ If `core.safecrlf` is set to "true" or "warn", git verifies if the conversion is reversible for the current setting of @@ -223,11 +324,11 @@ Interaction between checkin/checkout attributes In the check-in codepath, the worktree file is first converted with `filter` driver (if specified and corresponding driver defined), then the result is processed with `ident` (if -specified), and then finally with `crlf` (again, if specified +specified), and then finally with `text` (again, if specified and applicable). In the check-out codepath, the blob content is first converted -with `crlf`, and then `ident` and fed to `filter`. +with `text`, and then `ident` and fed to `filter`. Generating diff text @@ -651,7 +752,7 @@ You do not want any end-of-line conversions applied to, nor textual diffs produced for, any binary file you track. You would need to specify e.g. ------------ -*.jpg -crlf -diff +*.jpg -text -diff ------------ but that may become cumbersome, when you have many attributes. Using @@ -664,7 +765,7 @@ the same time. The system knows a built-in attribute macro, `binary`: which is equivalent to the above. Note that the attribute macros can only be "Set" (see the above example that sets "binary" macro as if it were an -ordinary attribute --- setting it in turn unsets "crlf" and "diff"). +ordinary attribute --- setting it in turn unsets "text" and "diff"). DEFINING ATTRIBUTE MACROS @@ -675,7 +776,7 @@ at the toplevel (i.e. not in any subdirectory). The built-in attribute macro "binary" is equivalent to: ------------ -[attr]binary -diff -crlf +[attr]binary -diff -text ------------ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 98c459dc8..e10fa88b8 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -83,16 +83,20 @@ Patterns have the following format: - 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. + pathname relative to the location of the `.gitignore` file + (relative to the toplevel of the work tree if not from a + `.gitignore` file). - Otherwise, git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, "Documentation/\*.html" matches - "Documentation/git.html" but not - "Documentation/ppc/ppc.html". A leading slash matches the - beginning of the pathname; for example, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". + + - A leading slash matches the beginning of the pathname. + For example, "/*.c" matches "cat-file.c" but not + "mozilla-sha1/sha1.c". An example: diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh index 2135a8ee1..34d02a241 100755 --- a/Documentation/install-webdoc.sh +++ b/Documentation/install-webdoc.sh @@ -12,7 +12,7 @@ do then : did not match elif test -f "$T/$h" && - diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" + $DIFF -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" then :; # up to date else diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index b055a673d..561cc9f7d 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -11,7 +11,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file. -Here are some additional details for each format: +There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +'format:' string, as described below (see +linkgit:git-config[1]). Here are the details of the +built-in formats: * 'oneline' @@ -154,6 +159,10 @@ If you add a `-` (minus sign) after '%' of a placeholder, line-feeds that immediately precede the expansion are deleted if and only if the placeholder expands to an empty string. +If you add a ` ` (space) after '%' of a placeholder, a space +is inserted immediately before the expansion if and only if the +placeholder expands to a non-empty string. + * 'tformat:' + The 'tformat:' format works exactly like 'format:', except that it diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index b9fb7a86b..cc562a057 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -98,6 +98,15 @@ you would get an output like this: This implies the '--topo-order' option by default, but the '--date-order' option may also be specified. +ifdef::git-rev-list[] +--count:: + 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. +endif::git-rev-list[] + + ifndef::git-rev-list[] Diff Formatting ~~~~~~~~~~~~~~~ @@ -384,6 +393,14 @@ Default mode:: merges from the resulting history, as there are no selected commits contributing to this merge. +--ancestry-path:: + + When given a range of commits to display (e.g. 'commit1..commit2' + or 'commit2 {caret}commit1'), only display commits that exist + directly on the ancestry chain between the 'commit1' and + 'commit2', i.e. commits that are both descendants of 'commit1', + and ancestors of 'commit2'. + A more detailed explanation follows. Suppose you specified `foo` as the <paths>. We shall call commits @@ -440,7 +457,7 @@ This results in: + ----------------------------------------------------------------------- .-A---N---O - / / + / / / I---------D ----------------------------------------------------------------------- + @@ -511,8 +528,6 @@ Note that without '\--full-history', this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked. -Finally, there is a fourth simplification mode available: - --simplify-merges:: First, build a history graph in the same way that @@ -554,6 +569,46 @@ Note the major differences in `N` and `P` over '\--full-history': removed completely, because it had one parent and is TREESAME. -- +Finally, there is a fifth simplification mode available: + +--ancestry-path:: + + Limit the displayed commits to those directly on the ancestry + chain between the "from" and "to" commits in the given commit + range. I.e. only display commits that are ancestor of the "to" + commit, and descendants of the "from" commit. ++ +As an example use case, consider the following commit history: ++ +----------------------------------------------------------------------- + D---E-------F + / \ \ + B---C---G---H---I---J + / \ + A-------K---------------L--M +----------------------------------------------------------------------- ++ +A regular 'D..M' computes the set of commits that are ancestors of `M`, +but excludes the ones that are ancestors of `D`. This is useful to see +what happened to the history leading to `M` since `D`, in the sense +that "what does `M` have that did not exist in `D`". The result in this +example would be all the commits, except `A` and `B` (and `D` itself, +of course). ++ +When we want to find out what commits in `M` are contaminated with the +bug introduced by `D` and need fixing, however, we might want to view +only the subset of 'D..M' that are actually descendants of `D`, i.e. +excluding `C` and `K`. This is exactly what the '\--ancestry-path' +option does. Applied to the 'D..M' range, it results in: ++ +----------------------------------------------------------------------- + E-------F + \ \ + G---H---I---J + \ + L--M +----------------------------------------------------------------------- + The '\--simplify-by-decoration' option allows you to view only the big picture of the topology of the history, by omitting commits that are not referenced by tags. Commits are marked as !TREESAME diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 44876fa70..f18b4f481 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -231,8 +231,9 @@ The function pointer in .proc has the following signature: 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: +because this facility is implemented by a thread in the same address +space on most platforms (when pthreads is available), but by a pipe to +a forked process otherwise: . It cannot change the program's state (global variables, environment, etc.) in a way that the caller notices; in other words, .in and .out |