diff options
Diffstat (limited to 'Documentation')
39 files changed, 374 insertions, 184 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 1b1c45df5c..fe1c1e5bc2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -152,12 +152,12 @@ Writing Documentation: when writing or modifying command usage strings and synopsis sections in the manual pages: - Placeholders are enclosed in angle brackets: + Placeholders are spelled in lowercase and enclosed in angle brackets: <file> --sort=<key> --abbrev[=<n>] - Possibility of multiple occurences is indicated by three dots: + Possibility of multiple occurrences is indicated by three dots: <file>... (One or more of <file>.) diff --git a/Documentation/RelNotes/1.7.3.5.txt b/Documentation/RelNotes/1.7.3.5.txt new file mode 100644 index 0000000000..40f3ba5795 --- /dev/null +++ b/Documentation/RelNotes/1.7.3.5.txt @@ -0,0 +1,34 @@ +Git 1.7.3.5 Release Notes +========================= + + * The xfuncname pattern used by "git diff" and "git grep" to show the + last notable line in context were broken for python and ruby for a long + time. + + * "git merge" into an unborn branch removed an untracked file "foo" from + the working tree when merged branch had "foo" (this fix was already in + 1.7.3.3 but was omitted from the release notes by mistake). + + * "git status -s" did not quote unprintable characters in paths as + documented. + + * "git am --abort" used to always reset to the commit at the beginning of + the last "am" invocation that has stopped, losing any unrelated commits + that may have been made since then. Now it refrains from doing so and + instead issues a warning. + + * "git blame" incorrectly reused bogusly cached result of textconv + filter for files from the working tree. + + * "git commit" used to abort after the user edited the log message + when the committer information was not correctly set up. It now + aborts before starting the editor. + + * "git commit --date=invalid" used to silently ignore the incorrectly + specified date; it is now diagnosed as an error. + + * "git rebase --skip" to skip the last commit in a series used to fail + to run post-rewrite hook and to copy notes from old commits that have + successfully been rebased so far. Now it do (backmerge ef88ad2). + + * "gitweb" tried to show a wrong feed logo when none was specified. diff --git a/Documentation/RelNotes/1.7.4.1.txt b/Documentation/RelNotes/1.7.4.1.txt new file mode 100644 index 0000000000..79923a6d2f --- /dev/null +++ b/Documentation/RelNotes/1.7.4.1.txt @@ -0,0 +1,27 @@ +Git v1.7.4.1 Release Notes +========================== + +Fixes since v1.7.4 +------------------ + + * On Windows platform, the codepath to spawn a new child process forgot + to first flush the output buffer. + + * "git bundle" did not use OFS_DELTA encoding, making its output a few + per-cent larger than necessarily. + + * The option to tell "git clone" to recurse into the submodules was + misspelled with an underscore "--recurse_submodules". + + * "git diff --cached HEAD" before the first commit does what an end user + would expect (namely, show what would be committed without further "git + add"). + + * "git fast-import" didn't accept the command to ask for "notes" feature + to be present in its input stream, even though it was capable of the + feature. + + * "git fsck" gave up scanning loose object files in directories with + garbage files. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.2.txt b/Documentation/RelNotes/1.7.4.2.txt new file mode 100644 index 0000000000..afb387161b --- /dev/null +++ b/Documentation/RelNotes/1.7.4.2.txt @@ -0,0 +1,42 @@ +Git v1.7.4.2 Release Notes +========================== + +Fixes since v1.7.4.1 +-------------------- + + * Many documentation updates to match "git cmd -h" output and the + git-cmd manual page. + + * "git clone /no/such/path" did not fail correctly. + + * "git commit" did not correctly error out when the user asked to use a + non existent file as the commit message template. + + * "git diff --stat -B" ran on binary files counted the changes in lines, + which was nonsensical. + + * "git diff -M" opportunistically detected copies, which was not + necessarily a good thing, especially when it is internally run by + recursive merge. + + * "git difftool" didn't tell (g)vimdiff that the files it is reading are + to be opened read-only. + + * "git merge" didn't pay attention to prepare-commit-msg hook, even + though if a merge is conflicted and manually resolved, the subsequent + "git commit" would have triggered the hook, which was inconsistent. + + * "git patch-id" (and commands like "format-patch --ignore-in-upstream" + that use it as their internal logic) handled changes to files that end + with incomplete lines incorrectly. + + * The official value to tell "git push" to push the current branch back + to update the upstream branch it forked from is now called "upstream". + The old name "tracking" is and will be supported. + + * gitweb's "highlight" interface mishandled tabs. + + * gitweb had a few forward-incompatible syntactic constructs and + also used incorrect variable when showing the file mode in a diff. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.txt index ace061f5fe..d5bca731b5 100644 --- a/Documentation/RelNotes/1.7.4.txt +++ b/Documentation/RelNotes/1.7.4.txt @@ -1,5 +1,5 @@ -Git v1.7.4 Release Notes (draft) -================================ +Git v1.7.4 Release Notes +======================== Updates since v1.7.3 -------------------- @@ -8,15 +8,14 @@ Updates since v1.7.3 docbook-xsl >= 1.73. If you have older versions, you can set ASCIIDOC7 and ASCIIDOC_ROFF, respectively. - * The option parsers of various commands that create new branch (or + * The option parsers of various commands that create new branches (or rename existing ones to a new name) were too loose and users were - allowed to call a branch with a name that begins with a dash by - creative abuse of their command line options, which only lead to - burn themselves. The name of a branch cannot begin with a dash - now. + allowed to give a branch a name that begins with a dash by creative + abuse of their command line options, which only led to burning + themselves. The name of a branch cannot begin with a dash now. * System-wide fallback default attributes can be stored in - /etc/gitattributes; core.attributesfile configuration variable can + /etc/gitattributes; the core.attributesfile configuration variable can be used to customize the path to this file. * The thread structure generated by "git send-email" has changed @@ -26,33 +25,39 @@ Updates since v1.7.3 cover letter of the previous series; this has been changed to make the patches in the new series replies to the new cover letter. - * Bash completion script in contrib/ has been adjusted to be also - usable by zsh. + * The Bash completion script in contrib/ has been adjusted to be usable with + Bash 4 (options with '=value' didn't complete). It has been also made + usable with zsh. * Different pagers can be chosen depending on which subcommand is - being run under the pager, using "pager.<subcommand>" variable. + being run under the pager, using the "pager.<subcommand>" variable. - * The hardcoded tab-width of 8 used in whitespace breakage checks is now + * The hardcoded tab-width of 8 that is used in whitespace breakage checks is now configurable via the attributes mechanism. * Support of case insensitive filesystems (i.e. "core.ignorecase") has been improved. For example, the gitignore mechanism didn't pay attention - to the case insensitivity. + to case insensitivity. - * The <tree>:<path> syntax to name a blob in a tree, and :<path> - syntax to name a blob in the index (e.g. "master:Makefile", + * The <tree>:<path> syntax for naming a blob in a tree, and the :<path> + syntax for naming a blob in the index (e.g. "master:Makefile", ":hello.c") have been extended. You can start <path> with "./" to implicitly have the (sub)directory you are in prefixed to the lookup. Similarly, ":../Makefile" from a subdirectory would mean "the Makefile of the parent directory in the index". - * "git blame" learned --show-email option to display the e-mail + * "git blame" learned the --show-email option to display the e-mail addresses instead of the names of authors. - * "git commit" learned --fixup and --squash options to help later invocation - of the interactive rebase. + * "git commit" learned the --fixup and --squash options to help later invocation + of interactive rebase. - * "git daemon" can be built in MinGW environment. + * Command line options to "git cvsimport" whose names are in capital + letters (-A, -M, -R and -S) can now be specified as the default in + the .git/config file by their longer names (cvsimport.authorsFile, + cvsimport.mergeRegex, cvsimport.trackRevisions, cvsimport.ignorePaths). + + * "git daemon" can be built in the MinGW environment. * "git daemon" can take more than one --listen option to listen to multiple addresses. @@ -60,13 +65,13 @@ Updates since v1.7.3 * "git describe --exact-match" was optimized not to read commit objects unnecessarily. - * "git diff" and "git grep" learned how functions and subroutines - in Fortran look like. + * "git diff" and "git grep" learned what functions and subroutines + in Fortran, Pascal and Perl look like. - * "git fetch" learned "--recurse-submodules" option. + * "git fetch" learned the "--recurse-submodules" option. - * "git mergetool" tells vim/gvim to show three-way diff by default - (use vimdiff2/gvimdiff2 as the tool name for old behaviour). + * "git mergetool" tells vim/gvim to show a three-way diff by default + (use vimdiff2/gvimdiff2 as the tool name for old behavior). * "git log -G<pattern>" limits the output to commits whose change has added or deleted lines that match the given pattern. @@ -76,8 +81,8 @@ Updates since v1.7.3 use the new --empty option to be more explicit instead. * "git repack -f" does not spend cycles to recompress objects in the - non-delta representation anymore (use -F if you really mean it when - e.g. you changed the compression level). + non-delta representation anymore (use -F if you really mean it + e.g. after you changed the core.compression variable setting). * "git merge --log" used to limit the resulting merge log to 20 entries; this is now customizable by giving e.g. "--log=47". @@ -86,33 +91,42 @@ Updates since v1.7.3 directory in one branch while a new file is created in place of that directory in the other branch. - * "git rebase --autosquash" can use SHA-1 object names to name which - commit to fix up (e.g. "fixup! e83c5163"). + * "git merge" learned the "--abort" option, synonymous to + "git reset --merge" when a merge is in progress. + + * "git notes" learned the "merge" subcommand to merge notes refs. + In addition to the default manual conflict resolution, there are + also several notes merge strategies for automatically resolving + notes merge conflicts. + + * "git rebase --autosquash" can use SHA-1 object names to name the + commit which is to be fixed up (e.g. "fixup! e83c5163"). - * The default "recursive" merge strategy learned --rename-threshold + * The default "recursive" merge strategy learned the --rename-threshold option to influence the rename detection, similar to the -M option - of "git diff". E.g. "git merge -Xrename-threshold=50% ..." to use - this. + of "git diff". From the "git merge" frontend, the "-X<strategy option>" + interface, e.g. "git merge -Xrename-threshold=50% ...", can be used + to trigger this. * The "recursive" strategy also learned to ignore various whitespace changes; the most notable is -Xignore-space-at-eol. * "git send-email" learned "--to-cmd", similar to "--cc-cmd", to read - recipient list from a command output. + the recipient list from a command output. * "git send-email" learned to read and use "To:" from its input files. * you can extend "git shell", which is often used on boxes that allow - git-only login over ssh as login shell, with custom set of + git-only login over ssh as login shell, with a custom set of commands. * The current branch name in "git status" output can be colored differently - from the generic header color by setting "color.status.branch" variable. + from the generic header color by setting the "color.status.branch" variable. * "git submodule sync" updates metainformation for all submodules, not just the ones that have been checked out. - * gitweb can use custom 'highlight' command with its configuration file. + * gitweb can use a custom 'highlight' command with its configuration file. * other gitweb updates. @@ -123,26 +137,20 @@ Also contains various documentation updates. Fixes since v1.7.3 ------------------ -All of the fixes in v1.7.3.X maintenance series are included in this +All of the fixes in the v1.7.3.X maintenance series are included in this release, unless otherwise noted. * "git log --author=me --author=her" did not find commits written by me or by her; instead it looked for commits written by me and by her, which is impossible. - * "git merge" into an unborn branch removed an untracked file "foo" - from the working tree when merged branch had "foo" (2caf20c..172b642). - * "git push --progress" shows progress indicators now. + * "git rebase -i" showed a confusing error message when given a + branch name that does not exist. + * "git repack" places its temporary packs under $GIT_OBJECT_DIRECTORY/pack instead of $GIT_OBJECT_DIRECTORY/ to avoid cross directory renames. * "git submodule update --recursive --other-flags" passes flags down to its subinvocations. - ---- -exec >/var/tmp/1 -O=v1.7.3.4-567-g38a5932 -echo O=$(git describe master) -git shortlog --no-merges ^maint ^$O master diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 72741ebda1..c3b0816ed7 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,10 +10,18 @@ Checklist (and a short version for the impatient): description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - - uses the imperative, present tense: "change", - not "changed" or "changes". - - includes motivation for the change, and contrasts - its implementation with previous behaviour + . explains the problem the change tries to solve, iow, what + is wrong with the current code without the change. + . justifies the way the change solves the problem, iow, why + the result with the change is better. + . alternate solutions considered but discarded, if any. + - describe changes in imperative mood, e.g. "make xyzzy do frotz" + instead of "[This patch] makes xyzzy do frotz" or "[I] changed + xyzzy to do frotz", as if you are giving orders to the codebase + to change its behaviour. + - try to make sure your explanation can be understood without + external resources. Instead of giving a URL to a mailing list + archive, summarize the relevant points of the discussion. - add a "Signed-off-by: Your Name <you@example.com>" line to the commit message (or just use the option "-s" when committing) to confirm that you agree to the Developer's Certificate of Origin @@ -90,7 +98,10 @@ your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline. -Describe the technical detail of the change(s). +Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do. If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. @@ -99,9 +110,8 @@ help reviewers check the patch, and future maintainers understand the code, are the most beautiful patches. Descriptions that summarise the point in the subject well, and describe the motivation for the change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, can be found on Usenet -archives back into the late 80's. Consider it like good Netiquette, -but for code. +differs substantially from the prior version, are all good things +to have. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped diff --git a/Documentation/config.txt b/Documentation/config.txt index 54597f1897..701fba92dc 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -317,24 +317,26 @@ false), while all other repositories are assumed to be bare (bare = true). core.worktree:: - Set the path to the root of the work tree. + Set the path to the root of the working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command line option. It can be - an absolute path or a relative path to the .git directory, - either specified by --git-dir or GIT_DIR, or automatically - discovered. - If --git-dir or GIT_DIR are specified but none of + variable and the '--work-tree' command line option. + The value can an absolute path or relative to the path to + the .git directory, which is either specified by --git-dir + or GIT_DIR, or automatically discovered. + If --git-dir or GIT_DIR is specified but none of --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the root of the - work tree. + the current working directory is regarded as the top level + of your working tree. + Note that this variable is honored even when set in a configuration -file in a ".git" subdirectory of a directory, and its value differs +file in a ".git" subdirectory of a directory and its value differs from the latter directory (e.g. "/path/to/.git/config" has core.worktree set to "/different/path"), which is most likely a -misconfiguration. Running git commands in "/path/to" directory will +misconfiguration. Running git commands in the "/path/to" directory will still use "/different/path" as the root of the work tree and can cause -great confusion to the users. +confusion unless you know what you are doing (e.g. you are creating a +read-only snapshot of the same index to a location different from the +repository's usual working tree). core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file @@ -374,15 +376,6 @@ core.warnAmbiguousRefs:: If true, git will warn you if the ref name you passed it is ambiguous and might match multiple refs in the .git/refs/ tree. True by default. -core.abbrevguard:: - Even though git makes sure that it uses enough hexdigits to show - an abbreviated object name unambiguously, as more objects are - added to the repository over time, a short name that used to be - unique will stop being unique. Git uses this many extra hexdigits - that are more than necessary to make the object name currently - unique, in the hope that its output will stay unique a bit longer. - Defaults to 0. - core.compression:: An integer -1..9, indicating a default compression level. -1 is the zlib default. 0 means no compression, @@ -899,7 +892,7 @@ diff.wordRegex:: fetch.recurseSubmodules:: A boolean value which changes the behavior for fetch and pull, the - default is to not recursively fetch populated sumodules unless + default is to not recursively fetch populated submodules unless configured otherwise. fetch.unpackLimit:: @@ -1589,7 +1582,8 @@ push.default:: * `matching` - push all matching branches. All branches having the same name in both ends are considered to be matching. This is the default. -* `tracking` - push the current branch to its upstream branch. +* `upstream` - push the current branch to its upstream branch. +* `tracking` - deprecated synonym for `upstream`. * `current` - push the current branch to a branch of the same name. rebase.stat:: @@ -1818,7 +1812,7 @@ submodule.<name>.update:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to enable/disable recursive fetching of this - submodule. It can be overriden by using the --[no-]recurse-submodules + submodule. It can be overridden by using the --[no-]recurse-submodules command line option to "git fetch" and "git pull". This setting will override that from in the linkgit:gitmodules[5] file. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 3ac2beac62..c57460c03d 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -74,10 +74,13 @@ separate lines indicate the old and the new mode. combined diff format -------------------- -"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or -'--cc' option to produce 'combined diff'. For showing a merge commit -with "git log -p", this is the default format; you can force showing -full diff with the '-m' option. +Any diff-generating command can take the `-c` or `--cc` option to +produce a 'combined diff' when showing a merge. This is the default +format when showing merges with linkgit:git-diff[1] or +linkgit:git-show[1]. Note also that you can give the `-m' option to any +of these commands to force generation of diffs with individual parents +of a merge. + A 'combined diff' format looks like this: ------------ diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 695696da1b..f37276e5ad 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -64,13 +64,11 @@ ifndef::git-pull[] downloaded. The default behavior for a remote may be specified with the remote.<name>.tagopt setting. See linkgit:git-config[1]. -endif::git-pull[] --[no-]recurse-submodules:: This option controls if new commits of all populated submodules should be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]). -ifndef::git-pull[] --submodule-prefix=<path>:: Prepend <path> to paths printed in informative messages such as "Fetching submodule foo". This option is used diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 54aaaeb41b..a03448f923 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -333,7 +333,7 @@ likely to introduce confusing changes to the index. There are also more complex operations that can be performed. But beware that because the patch is applied only to the index and not the working tree, the working tree will appear to "undo" the change in the index. -For example, introducing a a new line into the index that is in neither +For example, introducing a new line into the index that is in neither the HEAD nor the working tree will stage the new line for commit, but the line will appear to be reverted in the working tree. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 881652f490..2dcfc097d3 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -22,7 +22,7 @@ DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. With the `--index` option the patch is also applied to the index, and -with the `--cache` option the patch is only applied to the index. +with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a git repository. diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 4163a1bcb1..bf5037ab2a 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -116,7 +116,7 @@ Note that attributes are by default taken from the `.gitattributes` files in the tree that is being archived. If you want to tweak the way the output is generated after the fact (e.g. you committed without adding an appropriate export-ignore in its `.gitattributes`), adjust the checked out -`.gitattributes` file as necessary and use `--work-tree-attributes` +`.gitattributes` file as necessary and use `--worktree-attributes` option. Alternatively you can keep necessary attributes that should apply while archiving any tree in your `$GIT_DIR/info/attributes` file. diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index c39d957c3a..1701e42e4a 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -241,7 +241,12 @@ exit(3) manual page), as the value is chopped with "& 0377". The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current -revision will be skipped (see `git bisect skip` above). +revision will be skipped (see `git bisect skip` above). 125 was chosen +as the highest sensible value to use for this purpose, because 126 and 127 +are used by POSIX shells to signal specific error status (127 is for +command not found, 126 is for command found but not executable---these +details do not matter, as they are normal errors in the script, as far as +"bisect run" is concerned). You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 6266a3a602..299007b206 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -59,7 +59,7 @@ unbundle <file>:: <git-rev-list-args>:: A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list' (and containg a named ref, see SPECIFYING REFERENCES + 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES below), that specifies the specific objects and references to transport. For example, `master{tilde}10..master` causes the current master reference to be packaged along with all objects diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index b586c0f442..8f89f6f08c 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -214,10 +214,11 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. + The possible options are: + @@ -225,9 +226,8 @@ The possible options are: - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. -v:: --verbose:: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index f6ac847507..49105102db 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -38,6 +38,8 @@ directories. This behavior can be forced by --no-index. commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. + If HEAD does not exist (e.g. unborned branches) and + <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. 'git diff' [--options] <commit> [--] [<path>...]:: diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index f56dfcabb9..02bb49886c 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -534,9 +534,6 @@ start with double quote (`"`). If an `LF` or double quote must be encoded into `<path>` shell-style quoting should be used, e.g. `"path/with\n and \" in it"`. -Additionally, in `040000` mode, `<path>` may also be an empty string -(`""`) to specify the root of the tree. - The value of `<path>` must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), @@ -545,6 +542,8 @@ The value of `<path>` must be in canonical form. That is it must not: * contain the special component `.` or `..` (e.g. `foo/./bar` and `foo/../bar` are invalid). +The root of the tree can be represented by an empty string as `<path>`. + It is recommended that `<path>` always be encoded using UTF-8. `filedelete` @@ -905,7 +904,7 @@ The `<dataref>` can be either a mark reference (`:<idnum>`) set previously or a full 40-byte SHA-1 of a Git blob, preexisting or ready to be written. -output uses the same format as `git cat-file --batch`: +Output uses the same format as `git cat-file --batch`: ==== <sha1> SP 'blob' SP <size> LF @@ -949,6 +948,13 @@ cat-blob:: rather than wasting time on the early part of an import before the unsupported command is detected. +notes:: + Require that the backend support the 'notemodify' (N) + subcommand to the 'commit' command. + Versions of fast-import not supporting notes will exit + with a message indicating so. + + `option` ~~~~~~~~ Processes the specified option so that git fast-import behaves in a diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 40dba8c0a9..75adf7a502 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -57,7 +57,7 @@ merge.log:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the actual commits that are being merged. Defaults to false, and - true is a synoym for 20. + true is a synonym for 20. merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index fac1cf55e5..152e695c81 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -123,7 +123,7 @@ EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/bin/sh @@ -140,7 +140,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads:: +demonstrating the use of --shell. List the prefixes of all heads: ------------ #!/bin/sh @@ -154,7 +154,7 @@ done A bit more elaborate report on tags, demonstrating that the format -may be an entire script:: +may be an entire script: ------------ #!/bin/sh @@ -204,3 +204,15 @@ eval=`git for-each-ref --shell --format="$fmt" \ refs/tags` eval "$eval" ------------ + +Author +------ +Written by Junio C Hamano <gitster@pobox.com>. + +Documentation +------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index abe7bf9ff9..3422765827 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>... + <repository> [<refs>...] DESCRIPTION ----------- diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 30466917da..b33e6be872 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -84,6 +84,15 @@ must be given before the options meant for 'git fetch'. --verbose:: Pass --verbose to git-fetch and git-merge. +--[no-]recurse-submodules:: + This option controls if new commits of all populated submodules should + be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]). + That might be necessary to get the data needed for merging submodule + commits, a feature git learned in 1.7.3. Notice that the result of a + merge will not be checked out in the submodule, "git submodule update" + has to be called afterwards to bring the work tree up to date with the + merge result. + Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index e88e9c2d55..634423a69e 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -416,13 +416,6 @@ turn `core.sparseCheckout` on in order to have sparse checkout support. -BUGS ----- -In order to match a directory with $GIT_DIR/info/sparse-checkout, -trailing slash must be used. The form without trailing slash, while -works with .gitignore, does not work with sparse checkout. - - SEE ALSO -------- linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index f4fbf67209..68263a6a53 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -7,20 +7,20 @@ git-remote-ext - Bridge smart transport to external command. SYNOPSIS -------- -git remote add nick "ext::<command>[ <arguments>...]" +git remote add <nick> "ext::<command>[ <arguments>...]" DESCRIPTION ----------- -This remote helper uses the specified 'program' to connect +This remote helper uses the specified '<command>' to connect to a remote git server. -Data written to stdin of this specified 'program' is assumed -to be sent to git:// server, git-upload-pack, git-receive-pack +Data written to stdin of the specified '<command>' is assumed +to be sent to a git:// server, git-upload-pack, git-receive-pack or git-upload-archive (depending on situation), and data read -from stdout of this program is assumed to be received from +from stdout of <command> is assumed to be received from the same service. -Command and arguments are separated by unescaped space. +Command and arguments are separated by an unescaped space. The following sequences have a special meaning: @@ -39,19 +39,19 @@ The following sequences have a special meaning: git-upload-pack, or git-upload-archive) of the service git wants to invoke. -'%G' (must be first characters in argument):: - This argument will not be passed to 'program'. Instead, it - will cause helper to start by sending git:// service request to - remote side with service field set to approiate value and - repository field set to rest of the argument. Default is not to send - such request. +'%G' (must be the first characters in an argument):: + This argument will not be passed to '<command>'. Instead, it + will cause the helper to start by sending git:// service requests to + the remote side with the service field set to an appropriate value and + the repository field set to rest of the argument. Default is not to send + such a request. + This is useful if remote side is git:// server accessed over some tunnel. '%V' (must be first characters in argument):: - This argument will not be passed to 'program'. Instead it sets - the vhost field in git:// service request (to rest of the argument). + This argument will not be passed to '<command>'. Instead it sets + the vhost field in the git:// service request (to rest of the argument). Default is not to send vhost in such request (if sent). ENVIRONMENT VARIABLES: @@ -76,7 +76,7 @@ EXAMPLES: --------- This remote helper is transparently used by git when you use commands such as "git fetch <URL>", "git clone <URL>", -, "git push <URL>" or "git remote add nick <URL>", where <URL> +, "git push <URL>" or "git remote add <nick> <URL>", where <URL> begins with `ext::`. Examples: "ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'":: diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index abc49441be..4aecd4d187 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -11,20 +11,20 @@ SYNOPSIS DESCRIPTION ----------- -This helper uses specified file descriptors to connect to remote git server. +This helper uses specified file descriptors to connect to a remote git server. This is not meant for end users but for programs and scripts calling git fetch, push or archive. -If only <infd> is given, it is assumed to be bidirectional socket connected +If only <infd> is given, it is assumed to be a bidirectional socket connected to remote git server (git-upload-pack, git-receive-pack or git-upload-achive). If both <infd> and <outfd> are given, they are assumed -to be pipes connected to remote git server (<infd> being the inbound pipe +to be pipes connected to a remote git server (<infd> being the inbound pipe and <outfd> being the outbound pipe. It is assumed that any handshaking procedures have already been completed (such as sending service request for git://) before this helper is started. -<anything> can be any string. It is ignored. It is meant for provoding +<anything> can be any string. It is ignored. It is meant for providing information to user in the URL in case that URL is displayed in some context. diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 3a23477ce7..51de895822 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -201,12 +201,12 @@ REF LIST ATTRIBUTES OPTIONS ------- -'option verbosity' <N>:: +'option verbosity' <n>:: Changes the verbosity of messages displayed by the helper. - A value of 0 for N means that processes operate + A value of 0 for <n> means that processes operate quietly, and the helper produces only error output. 1 is the default level of verbosity, and higher values - of N correspond to the number of -v flags passed on the + of <n> correspond to the number of -v flags passed on the command line. 'option progress' \{'true'|'false'\}:: diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index fd72976371..927ecee2f2 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -76,15 +76,10 @@ In other words, --merge does something like a 'git read-tree -u -m <commit>', but carries forward unmerged index entries. --keep:: - Resets the index, updates files in the working tree that are - different between <commit> and HEAD, but keeps those - which are different between HEAD and the working tree (i.e. - which have local changes). + Resets index entries and updates files in the working tree that are + different between <commit> and HEAD. If a file that is different between <commit> and HEAD has local changes, reset is aborted. -+ -In other words, --keep does a 2-way merge between <commit> and HEAD followed by -'git reset --mixed <commit>'. -- If you want to undo a commit other than the latest on a branch, diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4a27643c1e..ff23cb0219 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -136,7 +136,12 @@ appending `/{asterisk}`. directory (typically a sequence of "../", or an empty string). --git-dir:: - Show `$GIT_DIR` if defined else show the path to the .git directory. + Show `$GIT_DIR` if defined. Otherwise show the path to + the .git directory, relative to the current directory. ++ +If `$GIT_DIR` is not defined and the current directory +is not detected to lie in a git repository or work tree +print a message to stderr and exit with nonzero status. --is-inside-git-dir:: When the current working directory is below the repository diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index dae190a5f2..5102a23f8e 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -38,20 +38,20 @@ OPTIONS -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. The possible options are: +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. ++ +The possible options are: + --- - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. --- + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. --ignore-submodules[=<when>]:: Ignore changes to submodules when looking for changes. <when> can be diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 139d314ba5..e161a40a73 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -66,7 +66,7 @@ COMMANDS Set the 'rewriteRoot' option in the [svn-remote] config. --rewrite-uuid=<UUID>;; Set the 'rewriteUUID' option in the [svn-remote] config. ---username=<USER>;; +--username=<user>;; For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other transports (eg svn+ssh://), you must include the username in @@ -443,8 +443,8 @@ OPTIONS Only used with the 'init' command. These are passed directly to 'git init'. --r <ARG>:: ---revision <ARG>:: +-r <arg>:: +--revision <arg>:: Used with the 'fetch' command. + This allows revision ranges for partial/cauterized history @@ -613,7 +613,7 @@ old references to SVN revision numbers in existing documentation, bug reports and archives. If you plan to eventually migrate from SVN to git and are certain about dropping SVN history, consider linkgit:git-filter-branch[1] instead. filter-branch also allows -reformating of metadata for ease-of-reading and rewriting authorship +reformatting of metadata for ease-of-reading and rewriting authorship info for non-"svn.authorsFile" users. svn.useSvmProps:: @@ -729,8 +729,11 @@ have each person clone that repository with 'git clone': cd project git init git remote add origin server:/pub/project - git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' + git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*' git fetch +# Prevent fetch/pull from remote git server in the future, +# we only want to use git svn for future updates + git config --remove-section remote.origin # Create a local branch from one of the branches just fetched git checkout -b master FETCH_HEAD # Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server) diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 8b169e364a..65f76c5440 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -18,21 +18,22 @@ SYNOPSIS DESCRIPTION ----------- -Adds a tag reference in `.git/refs/tags/`. +Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +to delete, list or verify tags. -Unless `-f` is given, the tag must not yet exist in +Unless `-f` is given, the tag to be created must not yet exist in the `.git/refs/tags/` directory. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command -creates a 'tag' object, and requires the tag message. Unless +creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. -Otherwise just the SHA1 object name of the commit object is -written (i.e. a lightweight tag). +Otherwise just a tag reference for the SHA1 object name of the commit object is +created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u <key-id>` is used. When `-u <key-id>` is not used, the diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 916a38aa99..0f848de8b2 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,7 +8,7 @@ git-verify-pack - Validate packed git archive files SYNOPSIS -------- -'git verify-pack' [-v|--verbose] [--] <pack>.idx ... +'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... DESCRIPTION diff --git a/Documentation/git.txt b/Documentation/git.txt index 012837145e..0c32d45248 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,9 +44,16 @@ 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.3.4/git.html[documentation for release 1.7.3.4] +* link:v1.7.4.1/git.html[documentation for release 1.7.4.1] * release notes for + link:RelNotes/1.7.4.1.txt[1.7.4.1], + link:RelNotes/1.7.4.txt[1.7.4]. + +* link:v1.7.3.5/git.html[documentation for release 1.7.3.5] + +* release notes for + link:RelNotes/1.7.3.5.txt[1.7.3.5], link:RelNotes/1.7.3.4.txt[1.7.3.4], link:RelNotes/1.7.3.3.txt[1.7.3.3], link:RelNotes/1.7.3.2.txt[1.7.3.2], @@ -290,17 +297,12 @@ help ...`. path or relative path to current working directory. --work-tree=<path>:: - Set the path to the working tree. The value will not be - used in combination with repositories found automatically in - a .git directory (i.e. $GIT_DIR is not set). + Set the path to the working tree. It can be an absolute path + or a path relative to the current working directory. This can also be controlled by setting the GIT_WORK_TREE environment variable and the core.worktree configuration - variable. It can be an absolute path or relative path to - the directory specified by --git-dir or GIT_DIR. - Note: If --git-dir or GIT_DIR are specified but none of - --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the top directory - of your working tree. + variable (see core.worktree in linkgit:git-config[1] for a + more detailed discussion). --bare:: Treat the repository as a bare repository. If GIT_DIR diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 5a7f936429..15aebc6062 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -335,6 +335,16 @@ input that is already correctly indented. In this case, the lack of a smudge filter means that the clean filter _must_ accept its own output without modifying it. +Sequence "%f" on the filter command line is replaced with the name of +the file the filter is working on. A filter might use this in keyword +substitution. For example: + +------------------------ +[filter "p4"] + clean = git-p4-filter --clean %f + smudge = git-p4-filter --smudge %f +------------------------ + Interaction between checkin/checkout attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -494,6 +504,8 @@ patterns are available: - `pascal` suitable for source code in the Pascal/Delphi language. +- `perl` suitable for source code in the Perl language. + - `php` suitable for source code in the PHP language. - `python` suitable for source code in the Python language. @@ -581,13 +593,46 @@ 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). +Marking files as binary +^^^^^^^^^^^^^^^^^^^^^^^ + +Git usually guesses correctly whether a blob contains text or binary +data by examining the beginning of the contents. However, sometimes you +may want to override its decision, either because a blob contains binary +data later in the file, or because the content, while technically +composed of text characters, is opaque to a human reader. For example, +many postscript files contain only ascii characters, but produce noisy +and meaningless diffs. + +The simplest way to mark a file as binary is to unset the diff +attribute in the `.gitattributes` file: + +------------------------ +*.ps -diff +------------------------ + +This will cause git to generate `Binary files differ` (or a binary +patch, if binary patches are enabled) instead of a regular diff. + +However, one may also want to specify other diff driver attributes. For +example, you might want to use `textconv` to convert postscript files to +an ascii representation for human viewing, but otherwise treat them as +binary files. You cannot specify both `-diff` and `diff=ps` attributes. +The solution is to use the `diff.*.binary` config option: + +------------------------ +[diff "ps"] + textconv = ps2ascii + binary = true +------------------------ + Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `merge` ^^^^^^^ -The attribute `merge` affects how three versions of a file is +The attribute `merge` affects how three versions of a file are merged when a file-level merge is necessary during `git merge`, and other commands such as `git revert` and `git cherry-pick`. @@ -601,15 +646,15 @@ Unset:: Take the version from the current branch as the tentative merge result, and declare that the merge has - conflicts. This is suitable for binary files that does + conflicts. This is suitable for binary files that do not have a well-defined merge semantics. Unspecified:: By default, this uses the same built-in 3-way merge - driver as is the case the `merge` attribute is set. - However, `merge.default` configuration variable can name - different merge driver to be used for paths to which the + driver as is the case when the `merge` attribute is set. + However, the `merge.default` configuration variable can name + different merge driver to be used with paths for which the `merge` attribute is unspecified. String:: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 7183aa9abb..28edefa202 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -350,10 +350,6 @@ rebase:: The commits are guaranteed to be listed in the order that they were processed by rebase. -There is no default 'post-rewrite' hook, but see the -`post-receive-copy-notes` script in `contrib/hooks` for an example -that copies your git-notes to the rewritten commits. - GIT --- diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 6c93202e73..68977943e7 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -49,7 +49,7 @@ submodule.<name>.fetchRecurseSubmodules:: submodule. If this option is also present in the submodules entry in .git/config of the superproject, the setting there will override the one found in .gitmodules. - Both settings can be overriden on the command line by using the + Both settings can be overridden on the command line by using the "--[no-]recurse-submodules" option to "git fetch" and "git pull".. submodule.<name>.ignore:: diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 0953a50b69..2933056120 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -71,5 +71,5 @@ Additional tips relevant parts of your tree. - Please note that if the other project merges from you, then it will - connects its history to yours, which can be something they don't want + connect its history to yours, which can be something they don't want to. diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 92772e7c4e..1e5c22c5e5 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -10,7 +10,7 @@ merge.log:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the actual commits that are being merged. Defaults to false, and - true is a synoym for 20. + true is a synonym for 20. merge.renameLimit:: The number of files to consider when performing rename detection diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 44a2ef1de1..9c47ad885b 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -165,7 +165,7 @@ limiting may be applied. -n 'number':: --max-count=<number>:: - Limit the number of commits output. + Limit the number of commits to output. --skip=<number>:: diff --git a/Documentation/technical/api-sigchain.txt b/Documentation/technical/api-sigchain.txt index 535cdff164..9e1189ef01 100644 --- a/Documentation/technical/api-sigchain.txt +++ b/Documentation/technical/api-sigchain.txt @@ -32,7 +32,7 @@ and installation code should look something like: } ------------------------------------------ -Handlers are given the typdef of sigchain_fun. This is the same type +Handlers are given the typedef of sigchain_fun. This is the same type that is given to signal() or sigaction(). It is perfectly reasonable to push SIG_DFL or SIG_IGN onto the stack. |