diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/1.8.0.2.txt | 34 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.8.1.txt | 82 | ||||
| -rw-r--r-- | Documentation/config.txt | 5 | ||||
| -rw-r--r-- | Documentation/diff-config.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-fast-import.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-stash.txt | 2 | ||||
| -rw-r--r-- | Documentation/git.txt | 9 | ||||
| -rw-r--r-- | Documentation/technical/api-command.txt | 99 |
9 files changed, 218 insertions, 41 deletions
diff --git a/Documentation/RelNotes/1.8.0.2.txt b/Documentation/RelNotes/1.8.0.2.txt new file mode 100644 index 0000000000..8497e051de --- /dev/null +++ b/Documentation/RelNotes/1.8.0.2.txt @@ -0,0 +1,34 @@ +Git v1.8.0.2 Release Notes +========================== + +Fixes since v1.8.0.1 +-------------------- + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. + + * We failed to mention a file without any content change but whose + permission bit was modified, or (worse yet) a new file without any + content in the "git diff --stat" output. + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. + + * "git p4" used to try expanding malformed "$keyword$" that spans + across multiple lines. + + * "git update-ref -d --deref SYM" to delete a ref through a symbolic + ref that points to it did not remove it correctly. + + * Syntax highlighting in "gitweb" was not quite working. + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.1.txt b/Documentation/RelNotes/1.8.1.txt index 34c5b26977..6aa24c64c0 100644 --- a/Documentation/RelNotes/1.8.1.txt +++ b/Documentation/RelNotes/1.8.1.txt @@ -19,7 +19,7 @@ variable in this release. "git branch --set-upstream" is deprecated and may be removed in a relatively distant future. "git branch [-u|--set-upstream-to]" has -been introduced with a saner order of arguments. +been introduced with a saner order of arguments to replace it. Updates since v1.8.0 @@ -27,7 +27,10 @@ Updates since v1.8.0 UI, Workflows & Features - * Command-line completion for tcsh has been added. + * Command-line completion scripts for tcsh and zsh have been added. + + * A new remote-helper interface for Mercurial has been added to + contrib/remote-helpers. * We used to have a workaround for a bug in ancient "less" that causes it to exit without any output when the terminal is resized. @@ -44,6 +47,12 @@ UI, Workflows & Features give the default number of context lines in the patch output, to override the hardcoded default of 3 lines. + * When "git checkout" checks out a branch, it tells the user how far + behind (or ahead) the new branch is relative to the remote tracking + branch it builds upon. The message now also advises how to sync + them up by pushing or pulling. This can be disabled with the + advice.statusHints configuration variable. + * "git config --get" used to diagnose presence of multiple definitions of the same variable in the same configuration file as an error, but it now applies the "last one wins" rule used by the @@ -51,20 +60,39 @@ UI, Workflows & Features API regression but it is expected that nobody will notice it in practice. + * "git log -p -S<string>" now looks for the <string> after applying + the textconv filter (if defined); earlier it inspected the contents + of the blobs without filtering. + * "git format-patch" learned the "--notes=<ref>" option to give notes for the commit after the three-dash lines in its output. * "git log --grep=<pcre>" learned to honor the "grep.patterntype" configuration set to "perl". - * "git replace -d <object>" now interprets <object>, instead of only - accepting full hex object name. + * "git replace -d <object>" now interprets <object> as an extended + SHA-1 (e.g. HEAD~4 is allowed), instead of only accepting full hex + object name. * "git rm $submodule" used to punt on removing a submodule working tree to avoid losing the repository embedded in it. Because recent git uses a mechanism to separate the submodule repository from the submodule working tree, "git rm" learned to detect this - case and removes the submodule working tree when it is safe. + case and removes the submodule working tree when it is safe to do so. + + * "git send-email" used to prompt for the sender address, even when + the committer identity is well specified (e.g. via user.name and + user.email configuration variables). The command no longer gives + this prompt when not necessary. + + * "git send-email" did not allow non-address garbage strings to + appear after addresses on Cc: lines in the patch files (and when + told to pick them up to find more recipients), e.g. + + Cc: Stable Kernel <stable@k.org> # for v3.2 and up + + The command now strips " # for v3.2 and up" part before adding the + remainder of this line to the list of recipients. * "git submodule add" learned to add a new submodule at the same path as the path where an unrelated submodule was bound to in an @@ -77,7 +105,7 @@ UI, Workflows & Features * "git symbolic-ref" learned the "-d $symref" option to delete the named symbolic ref, which is more intuitive way to spell it than - "update-ref -d --no-deref". + "update-ref -d --no-deref $symref". Foreign Interface @@ -93,10 +121,10 @@ Performance, Internal Implementation, etc. * Compilation on Cygwin with newer header files are supported now. - * The logic to generate the initial advertisement from - "upload-pack" (what is invoked by "git fetch" on the other side - of the connection) to list what refs are available in the - repository has been optimized. + * The logic to generate the initial advertisement from "upload-pack" + (i.e. what is invoked by "git fetch" on the other side of the + connection) to list what refs are available in the repository has + been optimized. * The logic to find set of attributes that match a given path has been optimized. @@ -118,55 +146,44 @@ details). * The configuration parser had an unnecessary hardcoded limit on variable names that was not checked consistently. - (merge 0971e99 bw/config-lift-variable-name-length-limit later to maint). * The "say" function in the test scaffolding incorrectly allowed "echo" to interpret "\a" as if it were a C-string asking for a BEL output. - (merge 7bc0911 jc/test-say-color-avoid-echo-escape later to maint). * "git mergetool" feeds /dev/null as a common ancestor when dealing with an add/add conflict, but p4merge backend cannot handle it. Work it around by passing a temporary empty file. - (merge 3facc60 da/mergetools-p4 later to maint). * "git log -F -E --grep='<ere>'" failed to use the given <ere> pattern as extended regular expression, and instead looked for the string literally. - (merge 727b6fc jc/grep-pcre-loose-ends~1 later to maint). * "git grep -e pattern <tree>" asked the attribute system to read "<tree>:.gitattributes" file in the working tree, which was nonsense. - (merge 55c6168 nd/grep-true-path later to maint). * A symbolic ref refs/heads/SYM was not correctly removed with "git branch -d SYM"; the command removed the ref pointed by SYM instead. - (merge 13baa9f rs/branch-del-symref later to maint). * Update "remote tracking branch" in the documentation to "remote-tracking branch". - (merge a6d3bde mm/maint-doc-remote-tracking later to maint). * "git pull --rebase" run while the HEAD is detached tried to find the upstream branch of the detached HEAD (which by definition does not exist) and emitted unnecessary error messages. - (merge e980765 ph/pull-rebase-detached later to maint). * The refs/replace hierarchy was not mentioned in the repository-layout docs. - (merge 11fbe18 po/maint-refs-replace-docs later to maint). * Various rfc2047 quoting issues around a non-ASCII name on the From: line in the output from format-patch have been corrected. - (merge 25dc8da js/format-2047 later to maint). * Sometimes curl_multi_timeout() function suggested a wrong timeout value when there is no file descriptor to wait on and the http transport ended up sleeping for minutes in select(2) system call. A workaround has been added for this. - (merge 7202b81 sz/maint-curl-multi-timeout later to maint). * For a fetch refspec (or the result of applying wildcard on one), we always want the RHS to map to something inside "refs/" @@ -175,7 +192,6 @@ details). * "git diff -G<pattern>" did not honor textconv filter when looking for changes. - (merge b1c2f57 jk/maint-diff-grep-textconv later to maint). * Some HTTP servers ask for auth only during the actual packing phase (not in ls-remote phase); this is not really a recommended @@ -185,27 +201,35 @@ details). * "git p4" used to try expanding malformed "$keyword$" that spans across multiple lines. - (merge 6b2bf41 pw/maint-p4-rcs-expansion-newline later to maint). * Syntax highlighting in "gitweb" was not quite working. - (merge 048b399 rh/maint-gitweb-highlight-ext later to maint). * RSS feed from "gitweb" had a xss hole in its title output. - (merge 0f0ecf6 jk/maint-gitweb-xss later to maint). * "git config --path $key" segfaulted on "[section] key" (a boolean "true" spelled without "=", not "[section] key = true"). - (merge 962c38e cn/config-missing-path later to maint). * "git checkout -b foo" while on an unborn branch did not say "Switched to a new branch 'foo'" like other cases. - (merge afa8c07 jk/checkout-out-of-unborn later to maint). + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. * We failed to mention a file without any content change but whose permission bit was modified, or (worse yet) a new file without any content in the "git diff --stat" output. - (merge 74faaa1 lt/diff-stat-show-0-lines later to maint). + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. * "update-ref -d --deref SYM" to delete a ref through a symbolic ref that points to it did not remove it correctly. - (merge b274a71 jh/update-ref-d-through-symref later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index e70216dfe6..bf8f911e1f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -160,9 +160,10 @@ advice.*:: it resulted in a non-fast-forward error. statusHints:: Show directions on how to proceed from the current - state in the output of linkgit:git-status[1] and in + state in the output of linkgit:git-status[1], in the template shown when writing commit messages in - linkgit:git-commit[1]. + linkgit:git-commit[1], and in the help message shown + by linkgit:git-checkout[1] when switching branch. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 89dd634674..4314ad0fbb 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -57,8 +57,8 @@ diff.statGraphWidth:: to all commands generating --stat output except format-patch. diff.context:: - Generate diffs with <n> lines of context instead of the default of - 3. This value is overridden by the -U option. + Generate diffs with <n> lines of context instead of the default + of 3. This value is overridden by the -U option. diff.external:: If this config variable is set, diff generation is not diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 959e4d3aee..d1844ead4a 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -562,8 +562,12 @@ A `<path>` string must use UNIX-style directory separators (forward slash `/`), may contain any byte other than `LF`, and must not 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"`. +A path can use C-style string quoting; this is accepted in all cases +and mandatory if the filename starts with double quote or contains +`LF`. In C-style quoting, the complete name should be surrounded with +double quotes, and any `LF`, backslash, or double quote characters +must be escaped by preceding them with a backslash (e.g., +`"path/with\n, \\ and \" in it"`). The value of `<path>` must be in canonical form. That is it must not: diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 6d19d59ce5..8b637d339f 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -385,11 +385,23 @@ the ones in the examples below) can be configured as the default for A handy way to push the current branch to the same name on the remote. -`git push origin master:satellite/master dev:satellite/dev`:: +`git push mothership master:satellite/master dev:satellite/dev`:: Use the source ref that matches `master` (e.g. `refs/heads/master`) to update the ref that matches `satellite/master` (most probably - `refs/remotes/satellite/master`) in the `origin` repository, then + `refs/remotes/satellite/master`) in the `mothership` repository; do the same for `dev` and `satellite/dev`. ++ +This is to emulate `git fetch` run on the `mothership` using `git +push` that is run in the opposite direction in order to integrate +the work done on `satellite`, and is often necessary when you can +only make connection in one way (i.e. satellite can ssh into +mothership but mothership cannot initiate connection to satellite +because the latter is behind a firewall or does not run sshd). ++ +After running this `git push` on the `satellite` machine, you would +ssh into the `mothership` and run `git merge` there to complete the +emulation of `git pull` that were run on `mothership` to pull changes +made on `satellite`. `git push origin HEAD:master`:: Push the current branch to the remote ref matching `master` in the diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 0aa4e20eae..711ffe17a7 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -144,7 +144,7 @@ drop [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` is given, it removes the latest one. i.e. `stash@{0}`, otherwise - `<stash>` must a valid stash log reference of the form + `<stash>` must be a valid stash log reference of the form `stash@{<revision>}`. create:: diff --git a/Documentation/git.txt b/Documentation/git.txt index cbe0883534..25e2f3a60e 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,10 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.8.0.1/git.html[documentation for release 1.8.0.1] +* link:v1.8.0.2/git.html[documentation for release 1.8.0.2] * release notes for + link:RelNotes/1.8.0.2.txt[1.8.0.2], link:RelNotes/1.8.0.1.txt[1.8.0.1], link:RelNotes/1.8.0.txt[1.8.0]. @@ -868,8 +869,10 @@ Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the git mailing list -<git@vger.kernel.org>. For a more complete list of contributors, see -http://git-scm.com/about. If you have a clone of git.git itself, the +<git@vger.kernel.org>. http://www.ohloh.net/p/git/contributors/summary +gives you a more complete list of contributors. + +If you have a clone of git.git itself, the output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you the authors for specific parts of the project. diff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt new file mode 100644 index 0000000000..ea9b2eda31 --- /dev/null +++ b/Documentation/technical/api-command.txt @@ -0,0 +1,99 @@ +Integrating new subcommands +=========================== + +This is how-to documentation for people who want to add extension +commands to git. It should be read alongside api-builtin.txt. + +Runtime environment +------------------- + +git subcommands are standalone executables that live in the git exec +path, normally /usr/lib/git-core. The git executable itself is a +thin wrapper that knows where the subcommands live, and runs them by +passing command-line arguments to them. + +(If "git foo" is not found in the git exec path, the wrapper +will look in the rest of your $PATH for it. Thus, it's possible +to write local git extensions that don't live in system space.) + +Implementation languages +------------------------ + +Most subcommands are written in C or shell. A few are written in +Perl. + +While we strongly encourage coding in portable C for portability, +these specific scripting languages are also acceptable. We won't +accept more without a very strong technical case, as we don't want +to broaden the git suite's required dependencies. Import utilities, +surgical tools, remote helpers and other code at the edges of the +git suite are more lenient and we allow Python (and even Tcl/tk), +but they should not be used for core functions. + +This may change in the future. Especially Python is not allowed in +core because we need better Python integration in the git Windows +installer before we can be confident people in that environment +won't experience an unacceptably large loss of capability. + +C commands are normally written as single modules, named after the +command, that link a collection of functions called libgit. Thus, +your command 'git-foo' would normally be implemented as a single +"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main +binary); this organization makes it easy for people reading the code +to find things. + +See the CodingGuidelines document for other guidance on what we consider +good practice in C and shell, and api-builtin.txt for the support +functions available to built-in commands written in C. + +What every extension command needs +---------------------------------- + +You must have a man page, written in asciidoc (this is what git help +followed by your subcommand name will display). Be aware that there is +a local asciidoc configuration and macros which you should use. It's +often helpful to start by cloning an existing page and replacing the +text content. + +You must have a test, written to report in TAP (Test Anything Protocol). +Tests are executables (usually shell scripts) that live in the 't' +subdirectory of the tree. Each test name begins with 't' and a sequence +number that controls where in the test sequence it will be executed; +conventionally the rest of the name stem is that of the command +being tested. + +Read the file t/README to learn more about the conventions to be used +in writing tests, and the test support library. + +Integrating a command +--------------------- + +Here are the things you need to do when you want to merge a new +subcommand into the git tree. + +0. Don't forget to sign off your patch! + +1. Append your command name to one of the variables BUILTIN_OBJS, +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON. + +2. Drop its test in the t directory. + +3. If your command is implemented in an interpreted language with a +p-code intermediate form, make sure .gitignore in the main directory +includes a pattern entry that ignores such files. Python .pyc and +.pyo files will already be covered. + +4. If your command has any dependency on a particular version of +your language, document it in the INSTALL file. + +5. There is a file command-list.txt in the distribution main directory +that categorizes commands by type, so they can be listed in appropriate +subsections in the documentation's summary command list. Add an entry +for yours. To understand the categories, look at git-cmmands.txt +in the main directory. + +6. Give the maintainer one paragraph to include in the RelNotes file +to describe the new feature; a good place to do so is in the cover +letter [PATCH 0/n]. + +That's all there is to it. |