diff options
Diffstat (limited to 'Documentation')
23 files changed, 451 insertions, 138 deletions
diff --git a/Documentation/RelNotes/1.8.5.4.txt b/Documentation/RelNotes/1.8.5.4.txt new file mode 100644 index 0000000000..d18c40389e --- /dev/null +++ b/Documentation/RelNotes/1.8.5.4.txt @@ -0,0 +1,48 @@ +Git v1.8.5.4 Release Notes +========================== + +Fixes since v1.8.5.3 +-------------------- + + * "git fetch --depth=0" was a no-op, and was silently ignored. + Diagnose it as an error. + + * Remote repository URL expressed in scp-style host:path notation are + parsed more carefully (e.g. "foo/bar:baz" is local, "[::1]:/~user" asks + to connect to user's home directory on host at address ::1. + + * SSL-related options were not passed correctly to underlying socket + layer in "git send-email". + + * "git commit -v" appends the patch to the log message before + editing, and then removes the patch when the editor returned + control. However, the patch was not stripped correctly when the + first modified path was a submodule. + + * "git mv A B/", when B does not exist as a directory, should error + out, but it didn't. + + * When we figure out how many file descriptors to allocate for + keeping packfiles open, a system with non-working getrlimit() could + cause us to die(), but because we make this call only to get a + rough estimate of how many is available and we do not even attempt + to use up all file descriptors available ourselves, it is nicer to + fall back to a reasonable low value rather than dying. + + * "git log --decorate" did not handle a tag pointed by another tag + nicely. + + * "git add -A" (no other arguments) in a totally empty working tree + used to emit an error. + + * There is no reason to have a hardcoded upper limit of the number of + parents for an octopus merge, created via the graft mechanism, but + there was. + + * The implementation of 'git stash $cmd "stash@{...}"' did not quote + the stash argument properly and left it split at IFS whitespace. + + * The documentation to "git pull" hinted there is an "-m" option + because it incorrectly shared the documentation with "git merge". + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/1.8.5.5.txt b/Documentation/RelNotes/1.8.5.5.txt new file mode 100644 index 0000000000..9191ce948f --- /dev/null +++ b/Documentation/RelNotes/1.8.5.5.txt @@ -0,0 +1,37 @@ +Git v1.8.5.5 Release Notes +========================== + +Fixes since v1.8.5.4 +-------------------- + + * The pathspec matching code, while comparing two trees (e.g. "git + diff A B -- path1 path2") was too aggressive and failed to match + some paths when multiple pathspecs were involved. + + * "git repack --max-pack-size=8g" stopped being parsed correctly when + the command was reimplemented in C. + + * A recent update to "git send-email" broke platforms where + /etc/ssl/certs/ directory exists but cannot be used as SSL_ca_path + (e.g. Fedora rawhide). + + * A handful of bugs around interpreting $branch@{upstream} notation + and its lookalike, when $branch part has interesting characters, + e.g. "@", and ":", have been fixed. + + * "git clone" would fail to clone from a repository that has a ref + directly under "refs/", e.g. "refs/stash", because different + validation paths do different things on such a refname. Loosen the + client side's validation to allow such a ref. + + * "git log --left-right A...B" lost the "leftness" of commits + reachable from A when A is a tag as a side effect of a recent + bugfix. This is a regression in 1.8.4.x series. + + * "git merge-base --octopus" used to leave cleaning up suboptimal + result to the caller, but now it does the clean-up itself. + + * "git mv A B/", when B does not exist as a directory, should error + out, but it didn't. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/1.9.txt b/Documentation/RelNotes/1.9.0.txt index 43c7b682a6..752d79127a 100644 --- a/Documentation/RelNotes/1.9.txt +++ b/Documentation/RelNotes/1.9.0.txt @@ -1,5 +1,5 @@ -Git v1.9 Release Notes -====================== +Git v1.9.0 Release Notes +======================== Backward compatibility notes ---------------------------- @@ -7,19 +7,19 @@ Backward compatibility notes "git submodule foreach $cmd $args" used to treat "$cmd $args" the same way "ssh" did, concatenating them into a single string and letting the shell unquote. Careless users who forget to sufficiently quote $args -gets their argument split at $IFS whitespaces by the shell, and got +get their argument split at $IFS whitespaces by the shell, and got unexpected results due to this. Starting from this release, the command line is passed directly to the shell, if it has an argument. Read-only support for experimental loose-object format, in which users -could optionally choose to write in their loose objects for a short -while between v1.4.3 to v1.5.3 era, has been dropped. +could optionally choose to write their loose objects for a short +while between v1.4.3 and v1.5.3 era, has been dropped. -The meanings of "--tags" option to "git fetch" has changed; the -command fetches tags _in addition to_ what are fetched by the same +The meanings of the "--tags" option to "git fetch" has changed; the +command fetches tags _in addition to_ what is fetched by the same command line without the option. -The way "git push $there $what" interprets $what part given on the +The way "git push $there $what" interprets the $what part given on the command line, when it does not have a colon that explicitly tells us what ref at the $there repository is to be updated, has been enhanced. @@ -27,8 +27,8 @@ A handful of ancient commands that have long been deprecated are finally gone (repo-config, tar-tree, lost-found, and peek-remote). -Backward compatibility notes (for Git 2.0) ------------------------------------------- +Backward compatibility notes (for Git 2.0.0) +-------------------------------------------- When "git push [$there]" does not say what to push, we have used the traditional "matching" semantics so far (all your branches were sent @@ -96,7 +96,7 @@ UI, Workflows & Features primarily because the codepaths involved were not carefully vetted and we did not bother supporting such usage. This release attempts to allow object transfer out of a shallowly-cloned repository in a - more controlled way (i.e. the receiver become a shallow repository + more controlled way (i.e. the receiver becomes a shallow repository with a truncated history). * Just like we give a reasonable default for "less" via the LESS @@ -107,12 +107,12 @@ UI, Workflows & Features hierarchies, whose variables are predominantly three-level, were not completed by hitting a <TAB> in bash and zsh completions. - * Fetching 'frotz' branch with "git fetch", while 'frotz/nitfol' + * Fetching a 'frotz' branch with "git fetch", while a 'frotz/nitfol' remote-tracking branch from an earlier fetch was still there, would error out, primarily because the command was not told that it is allowed to lose any information on our side. "git fetch --prune" - now can be used to remove 'frotz/nitfol' to make room to fetch and - store 'frotz' remote-tracking branch. + now can be used to remove 'frotz/nitfol' to make room for fetching and + storing the 'frotz' remote-tracking branch. * "diff.orderfile=<file>" configuration variable can be used to pretend as if the "-O<file>" option were given from the command @@ -218,42 +218,35 @@ track are contained in this release (see the maintenance releases' notes for details). * The pathspec matching code, while comparing two trees (e.g. "git - diff A B -- path1 path2") was too agrresive and failed to match + diff A B -- path1 path2") was too aggressive and failed to match some paths when multiple pathspecs were involved. - (merge e4ddb05 as/tree-walk-fix-aggressive-short-cut later to maint). * "git repack --max-pack-size=8g" stopped being parsed correctly when the command was reimplemented in C. - (merge b861e23 sb/repack-in-c later to maint). * An earlier update in v1.8.4.x to "git rev-list --objects" with - negative ref had performance regression. + negative ref had a performance regression. (merge 200abe7 jk/mark-edges-uninteresting later to maint). * A recent update to "git send-email" broke platforms where - /etc/ssl/certs/ directory exists, but it cannot used as SSL_ca_path + /etc/ssl/certs/ directory exists but cannot be used as SSL_ca_path (e.g. Fedora rawhide). - (merge 01645b7 rk/send-email-ssl-cert later to maint). * A handful of bugs around interpreting $branch@{upstream} notation and its lookalike, when $branch part has interesting characters, e.g. "@", and ":", have been fixed. - (merge 9892d5d jk/interpret-branch-name-fix later to maint). * "git clone" would fail to clone from a repository that has a ref directly under "refs/", e.g. "refs/stash", because different validation paths do different things on such a refname. Loosen the client side's validation to allow such a ref. - (merge 4c22408 jk/allow-fetch-onelevel-refname later to maint). * "git log --left-right A...B" lost the "leftness" of commits reachable from A when A is a tag as a side effect of a recent bugfix. This is a regression in 1.8.4.x series. - (merge a743528 jc/revision-range-unpeel later to maint). * documentations to "git pull" hinted there is an "-m" option because it incorrectly shared the documentation with "git merge". - (merge 08f19cf jc/maint-pull-docfix later to maint). * "git diff A B submod" and "git diff A B submod/" ought to have done the same for a submodule "submod", but didn't. @@ -268,17 +261,14 @@ for details). * The implementation of 'git stash $cmd "stash@{...}"' did not quote the stash argument properly and left it split at IFS whitespace. - (merge 2a07e43 ow/stash-with-ifs later to maint). * The "--[no-]informative-errors" options to "git daemon" were parsed a bit too loosely, allowing any other string after these option names. - (merge 82246b7 nd/daemon-informative-errors-typofix later to maint). - * There is no reason to have a hardcoded upper limit of the number of - parents for an octopus merge, created via the graft mechanism, but + * There is no reason to have a hardcoded upper limit for the number of + parents of an octopus merge, created via the graft mechanism, but there was. - (merge e228c17 js/lift-parent-count-limit later to maint). * The basic test used to leave unnecessary trash directories in the t/ directory. @@ -286,30 +276,24 @@ for details). * "git merge-base --octopus" used to leave cleaning up suboptimal result to the caller, but now it does the clean-up itself. - (merge 8f29299 bm/merge-base-octopus-dedup later to maint). * A "gc" process running as a different user should be able to stop a new "gc" process from starting, but it didn't. - (merge ed7eda8 km/gc-eperm later to maint). * An earlier "clean-up" introduced an unnecessary memory leak. - (merge e1c1a32 jk/credential-plug-leak later to maint). * "git add -A" (no other arguments) in a totally empty working tree used to emit an error. - (merge 64ed07c nd/add-empty-fix later to maint). * "git log --decorate" did not handle a tag pointed by another tag nicely. - (merge 5e1361c bc/log-decoration later to maint). * When we figure out how many file descriptors to allocate for keeping packfiles open, a system with non-working getrlimit() could cause us to die(), but because we make this call only to get a - rough estimate of how many is available and we do not even attempt - to use up all file descriptors available ourselves, it is nicer to + rough estimate of how many are available and we do not even attempt + to use up all available file descriptors ourselves, it is nicer to fall back to a reasonable low value rather than dying. - (merge 491a8de jh/rlimit-nofile-fallback later to maint). * read_sha1_file(), that is the workhorse to read the contents given an object name, honoured object replacements, but there was no @@ -320,16 +304,13 @@ for details). * "git cat-file --batch=", an admittedly useless command, did not behave very well. - (merge 6554dfa jk/cat-file-regression-fix later to maint). * "git rev-parse <revs> -- <paths>" did not implement the usual disambiguation rules the commands in the "git log" family used in the same way. - (merge 62f162f jk/rev-parse-double-dashes later to maint). * "git mv A B/", when B does not exist as a directory, should error out, but it didn't. - (merge c57f628 mm/mv-file-to-no-such-dir-with-slash later to maint). * A workaround to an old bug in glibc prior to glibc 2.17 has been retired; this would remove a side effect of the workaround that @@ -337,36 +318,28 @@ for details). * SSL-related options were not passed correctly to underlying socket layer in "git send-email". - (merge 5508f3e tr/send-email-ssl later to maint). * "git commit -v" appends the patch to the log message before editing, and then removes the patch when the editor returned control. However, the patch was not stripped correctly when the first modified path was a submodule. - (merge 1a72cfd jl/commit-v-strip-marker later to maint). * "git fetch --depth=0" was a no-op, and was silently ignored. Diagnose it as an error. - (merge 5594bca nd/transport-positive-depth-only later to maint). - * Remote repository URL expressed in scp-style host:path notation are + * Remote repository URLs expressed in scp-style host:path notation are parsed more carefully (e.g. "foo/bar:baz" is local, "[::1]:/~user" asks to connect to user's home directory on host at address ::1. - (merge a2036d7 tb/clone-ssh-with-colon-for-port later to maint). * "git diff -- ':(icase)makefile'" was unnecessarily rejected at the command line parser. - (merge 887c6c1 nd/magic-pathspec later to maint). * "git cat-file --batch-check=ok" did not check the existence of the named object. - (merge 4ef8d1d sb/sha1-loose-object-info-check-existence later to maint). * "git am --abort" sometimes complained about not being able to write a tree with an 0{40} object in it. - (merge 77b43ca jk/two-way-merge-corner-case-fix later to maint). * Two processes creating loose objects at the same time could have failed unnecessarily when the name of their new objects started with the same byte value, due to a race condition. - (merge b2476a6 jh/loose-object-dirs-creation-race later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 5f4d7939ed..7eec746950 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -992,6 +992,14 @@ commit.cleanup:: have to remove the help lines that begin with `#` in the commit log template yourself, if you do this). +commit.gpgsign:: + + A boolean to specify whether all commits should be GPG signed. + Use of this option when doing operations such as rebase can + result in a large number of commits being signed. It may be + convenient to use an agent to avoid typing your GPG passphrase + several times. + commit.status:: A boolean to enable/disable inclusion of status information in the commit message template when using an editor to prepare the commit @@ -1881,6 +1889,16 @@ pretty.<name>:: Note that an alias with the same name as a built-in format will be silently ignored. +pull.ff:: + By default, Git does not create an extra merge commit when merging + a commit that is a descendant of the current commit. Instead, the + tip of the current branch is fast-forwarded. When set to `false`, + this variable tells Git to create an extra merge commit in such + a case (equivalent to giving the `--no-ff` option from the command + line). When set to `only`, only such fast-forward merges are + allowed (equivalent to giving the `--ff-only` option from the + command line). + pull.rebase:: When true, rebase branches on top of the fetched branch, instead of merging the default branch from the default remote when "git diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 8e70a61840..9f23a861ce 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -35,7 +35,8 @@ Apart from supporting file annotation, Git also supports searching the development history for when a code snippet occurred in a change. This makes it possible to track when a code snippet was added to a file, moved or copied between files, and eventually deleted or replaced. It works by searching for -a text string in the diff. A small example: +a text string in the diff. A small example of the pickaxe interface +that searches for `blame_usage`: ----------------------------------------------------------------------------- $ git log --pretty=oneline -S'blame_usage' diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 49878570bf..0363d0039b 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -55,15 +55,12 @@ repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular Git transport instead. -+ -To force copying instead of hardlinking (which may be desirable if you -are trying to make a back-up of your repository), but still avoid the -usual "Git aware" transport mechanism, `--no-hardlinks` can be used. --no-hardlinks:: - Optimize the cloning process from a repository on a - local filesystem by copying files under `.git/objects` - directory. + Force the cloning process from a repository on a local + filesystem to copy the files under the `.git/objects` + directory instead of using hardlinks. This may be desirable + if you are trying to make a back-up of your repository. --shared:: -s:: @@ -208,7 +205,7 @@ objects from the source repository into a pack in the cloned repository. --separate-git-dir=<git dir>:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, - then make a filesytem-agnostic Git symbolic link to there. + then make a filesystem-agnostic Git symbolic link to there. The result is Git repository can be separated from working tree. diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index cafdc9642d..a469eab066 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -55,8 +55,13 @@ OPTIONS from the standard input. -S[<keyid>]:: +--gpg-sign[=<keyid>]:: GPG-sign commit. +--no-gpg-sign:: + Countermand `commit.gpgsign` configuration variable that is + set to force each and every commit to be signed. + Commit Information ------------------ diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 1a7616c73a..7c42e9cabc 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -302,6 +302,10 @@ configuration variable documented in linkgit:git-config[1]. --gpg-sign[=<keyid>]:: GPG-sign commit. +--no-gpg-sign:: + Countermand `commit.gpgsign` configuration variable that is + set to force each and every commit to be signed. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 33fbd8c56f..56fb7e5322 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -44,7 +44,7 @@ two blob objects, or changes between two files on disk. 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 + If HEAD does not exist (e.g. unborn branches) and <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 2507c8bd91..cb103c8b6f 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -3,7 +3,7 @@ git-remote(1) NAME ---- -git-remote - manage set of tracked repositories +git-remote - Manage set of tracked repositories SYNOPSIS diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index f445cb38fa..a077ba0ddc 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git reset' [-q] [<tree-ish>] [--] <paths>... 'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...] -'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] +'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- @@ -60,6 +60,9 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action. ++ +If `-N` is specified, removed paths are marked as intent-to-add (see +linkgit:git-add[1]). --hard:: Resets the index and working tree. Any changes to tracked files in the diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bfef8a0c62..21cb59a6d6 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -15,8 +15,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] [--] <path>... 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>] - [--merge] [--recursive] [--] [<path>...] + [-f|--force] [--rebase|--merge|--checkout] [--reference <repository>] + [--depth <depth>] [--recursive] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> @@ -155,13 +155,31 @@ it contains local modifications. update:: Update the registered submodules, i.e. clone missing submodules and - checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached unless `--rebase` or - `--merge` is specified or the key `submodule.$name.update` is set to - `rebase`, `merge` or `none`. `none` can be overridden by specifying - `--checkout`. Setting the key `submodule.$name.update` to `!command` - will cause `command` to be run. `command` can be any arbitrary shell - command that takes a single argument, namely the sha1 to update to. + checkout the commit specified in the index of the containing + repository. The update mode defaults to `checkout`, but can be + configured with the `submodule.<name>.update` setting or the + `--rebase`, `--merge`, or `--checkout` options. ++ +For updates that clone missing submodules, checkout-mode updates will +create submodules with detached HEADs; all other modes will create +submodules with a local branch named after `submodule.<path>.branch`. ++ +For updates that do not clone missing submodules, the submodule's HEAD +is only touched when the remote reference does not match the +submodule's HEAD (for none-mode updates, the submodule is never +touched). The remote reference is usually the gitlinked commit from +the superproject's tree, but with `--remote` it is the upstream +subproject's `submodule.<name>.branch`. This remote reference is +integrated with the submodule's HEAD using the specified update mode. +For checkout-mode updates, that will result in a detached HEAD. For +rebase- and merge-mode updates, the commit referenced by the +submodule's HEAD may change, but the symbolic reference will remain +unchanged (i.e. checked-out branches will still be checked-out +branches, and detached HEADs will still be detached HEADs). If none +of the builtin modes fit your needs, set `submodule.<name>.update` to +`!command` to configure a custom integration command. `command` can +be any arbitrary shell command that takes a single argument, namely +the sha1 to update to. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -281,6 +299,16 @@ In order to ensure a current tracking branch state, `update --remote` fetches the submodule's remote repository before calculating the SHA-1. If you don't want to fetch, you should use `submodule update --remote --no-fetch`. ++ +Use this option to integrate changes from the upstream subproject with +your submodule's current HEAD. Alternatively, you can run `git pull` +from the submodule, which is equivalent except for the remote branch +name: `update --remote` uses the default upstream repository and +`submodule.<name>.branch`, while `git pull` uses the submodule's +`branch.<name>.merge`. Prefer `submodule.<name>.branch` if you want +to distribute the default upstream branch with the superproject and +`branch.<name>.merge` if you want a more native feel while working in +the submodule itself. -N:: --no-fetch:: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index c418c44d40..404257df9f 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -103,8 +103,9 @@ OPTIONS + This option is only applicable when listing tags without annotation lines. ---contains <commit>:: - Only list tags which contain the specified commit. +--contains [<commit>]:: + Only list tags which contain the specified commit (HEAD if not + specified). --points-at <object>:: Only list tags of the given object. diff --git a/Documentation/git.txt b/Documentation/git.txt index 274d816b43..02bbc084b8 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,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.8.5.3/git.html[documentation for release 1.8.5.3] +* link:v1.9.0/git.html[documentation for release 1.9.0] * release notes for + link:RelNotes/1.9.0.txt[1.9.0]. + +* link:v1.8.5.5/git.html[documentation for release 1.8.5.5] + +* release notes for + link:RelNotes/1.8.5.5.txt[1.8.5.5], + link:RelNotes/1.8.5.4.txt[1.8.5.4], link:RelNotes/1.8.5.3.txt[1.8.5.3], link:RelNotes/1.8.5.2.txt[1.8.5.2], link:RelNotes/1.8.5.1.txt[1.8.5.1], diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 3f33ca5507..1c3e109cb3 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -28,7 +28,7 @@ arguments. Here are the rules: they can be disambiguated by placing `--` between them. E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work tree. Please show changes between the version I staged in the index - and what I have in the work tree for that file". not "show difference + and what I have in the work tree for that file", not "show difference between the HEAD commit and the work tree as a whole". You can say `git diff HEAD --` to ask for the latter. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index d48bf4d6fa..d954bf6ba8 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -251,7 +251,7 @@ three parameters: - the name of the ref being updated, - the old object name stored in the ref, - - and the new objectname to be stored in the ref. + - and the new object name to be stored in the ref. A zero exit from the update hook allows the ref to be updated. Exiting with a non-zero status prevents 'git-receive-pack' diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 347a9f76ee..f539e3f66a 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -55,6 +55,10 @@ submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. If the option is not specified, it defaults to 'master'. See the `--remote` documentation in linkgit:git-submodule[1] for details. ++ +This branch name is also used for the local branch created by +non-checkout cloning updates. See the `update` documentation in +linkgit:git-submodule[1] for details. submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index db4154f9d5..952f503afb 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -630,13 +630,13 @@ need to set this element to empty list i.e. `[]`. override:: If this field has a true value then the given feature is - overriddable, which means that it can be configured + overridable, which means that it can be configured (or enabled/disabled) on a per-repository basis. + Usually given "<feature>" is configurable via the `gitweb.<feature>` config variable in the per-repository Git configuration file. + -*Note* that no feature is overriddable by default. +*Note* that no feature is overridable by default. sub:: Internal detail of implementation. What is important is that diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index 33ae69c11f..ca4378740c 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -39,26 +39,26 @@ The policy on Integration is informally mentioned in "A Note from the maintainer" message, which is periodically posted to this mailing list after each feature release is made. - - Feature releases are numbered as vX.Y.Z and are meant to + - Feature releases are numbered as vX.Y.0 and are meant to contain bugfixes and enhancements in any area, including functionality, performance and usability, without regression. - One release cycle for a feature release is expected to last for eight to ten weeks. - - Maintenance releases are numbered as vX.Y.Z.W and are meant - to contain only bugfixes for the corresponding vX.Y.Z feature - release and earlier maintenance releases vX.Y.Z.V (V < W). + - Maintenance releases are numbered as vX.Y.Z and are meant + to contain only bugfixes for the corresponding vX.Y.0 feature + release and earlier maintenance releases vX.Y.W (W < Z). - 'master' branch is used to prepare for the next feature release. In other words, at some point, the tip of 'master' - branch is tagged with vX.Y.Z. + branch is tagged with vX.Y.0. - 'maint' branch is used to prepare for the next maintenance - release. After the feature release vX.Y.Z is made, the tip + release. After the feature release vX.Y.0 is made, the tip of 'maint' branch is set to that release, and bugfixes will accumulate on the branch, and at some point, the tip of the - branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on. + branch is tagged with vX.Y.1, vX.Y.2, and so on. - 'next' branch is used to publish changes (both enhancements and fixes) that (1) have worthwhile goal, (2) are in a fairly @@ -86,6 +86,10 @@ this mailing list after each feature release is made. users are encouraged to test it so that regressions and bugs are found before new topics are merged to 'master'. +Note that before v1.9.0 release, the version numbers used to be +structured slightly differently. vX.Y.Z were feature releases while +vX.Y.Z.W were maintenance releases for vX.Y.Z. + A Typical Git Day ----------------- diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index fb6e593e7c..350949810e 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -20,7 +20,7 @@ recursive:: merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without - causing mis-merges by tests done on actual merge commits + causing mismerges by tests done on actual merge commits taken from Linux 2.6 kernel development history. Additionally this can detect and handle merges involving renames. This is the default merge strategy when diff --git a/Documentation/technical/api-hash.txt b/Documentation/technical/api-hash.txt deleted file mode 100644 index e5061e0677..0000000000 --- a/Documentation/technical/api-hash.txt +++ /dev/null @@ -1,52 +0,0 @@ -hash API -======== - -The hash API is a collection of simple hash table functions. Users are expected -to implement their own hashing. - -Data Structures ---------------- - -`struct hash_table`:: - - The hash table structure. The `array` member points to the hash table - entries. The `size` member counts the total number of valid and invalid - entries in the table. The `nr` member keeps track of the number of - valid entries. - -`struct hash_table_entry`:: - - An opaque structure representing an entry in the hash table. The `hash` - member is the entry's hash key and the `ptr` member is the entry's - value. - -Functions ---------- - -`init_hash`:: - - Initialize the hash table. - -`free_hash`:: - - Release memory associated with the hash table. - -`insert_hash`:: - - Insert a pointer into the hash table. If an entry with that hash - already exists, a pointer to the existing entry's value is returned. - Otherwise NULL is returned. This allows callers to implement - chaining, etc. - -`lookup_hash`:: - - Lookup an entry in the hash table. If an entry with that hash exists - the entry's value is returned. Otherwise NULL is returned. - -`for_each_hash`:: - - Call a function for each entry in the hash table. The function is - expected to take the entry's value as its only argument and return an - int. If the function returns a negative int the loop is aborted - immediately. Otherwise, the return value is accumulated and the sum - returned upon completion of the loop. diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt new file mode 100644 index 0000000000..42ca2347ed --- /dev/null +++ b/Documentation/technical/api-hashmap.txt @@ -0,0 +1,235 @@ +hashmap API +=========== + +The hashmap API is a generic implementation of hash-based key-value mappings. + +Data Structures +--------------- + +`struct hashmap`:: + + The hash table structure. ++ +The `size` member keeps track of the total number of entries. The `cmpfn` +member is a function used to compare two entries for equality. The `table` and +`tablesize` members store the hash table and its size, respectively. + +`struct hashmap_entry`:: + + An opaque structure representing an entry in the hash table, which must + be used as first member of user data structures. Ideally it should be + followed by an int-sized member to prevent unused memory on 64-bit + systems due to alignment. ++ +The `hash` member is the entry's hash code and the `next` member points to the +next entry in case of collisions (i.e. if multiple entries map to the same +bucket). + +`struct hashmap_iter`:: + + An iterator structure, to be used with hashmap_iter_* functions. + +Types +----- + +`int (*hashmap_cmp_fn)(const void *entry, const void *entry_or_key, const void *keydata)`:: + + User-supplied function to test two hashmap entries for equality. Shall + return 0 if the entries are equal. ++ +This function is always called with non-NULL `entry` / `entry_or_key` +parameters that have the same hash code. When looking up an entry, the `key` +and `keydata` parameters to hashmap_get and hashmap_remove are always passed +as second and third argument, respectively. Otherwise, `keydata` is NULL. + +Functions +--------- + +`unsigned int strhash(const char *buf)`:: +`unsigned int strihash(const char *buf)`:: +`unsigned int memhash(const void *buf, size_t len)`:: +`unsigned int memihash(const void *buf, size_t len)`:: + + Ready-to-use hash functions for strings, using the FNV-1 algorithm (see + http://www.isthe.com/chongo/tech/comp/fnv). ++ +`strhash` and `strihash` take 0-terminated strings, while `memhash` and +`memihash` operate on arbitrary-length memory. ++ +`strihash` and `memihash` are case insensitive versions. + +`void hashmap_init(struct hashmap *map, hashmap_cmp_fn equals_function, size_t initial_size)`:: + + Initializes a hashmap structure. ++ +`map` is the hashmap to initialize. ++ +The `equals_function` can be specified to compare two entries for equality. +If NULL, entries are considered equal if their hash codes are equal. ++ +If the total number of entries is known in advance, the `initial_size` +parameter may be used to preallocate a sufficiently large table and thus +prevent expensive resizing. If 0, the table is dynamically resized. + +`void hashmap_free(struct hashmap *map, int free_entries)`:: + + Frees a hashmap structure and allocated memory. ++ +`map` is the hashmap to free. ++ +If `free_entries` is true, each hashmap_entry in the map is freed as well +(using stdlib's free()). + +`void hashmap_entry_init(void *entry, unsigned int hash)`:: + + Initializes a hashmap_entry structure. ++ +`entry` points to the entry to initialize. ++ +`hash` is the hash code of the entry. + +`void *hashmap_get(const struct hashmap *map, const void *key, const void *keydata)`:: + + Returns the hashmap entry for the specified key, or NULL if not found. ++ +`map` is the hashmap structure. ++ +`key` is a hashmap_entry structure (or user data structure that starts with +hashmap_entry) that has at least been initialized with the proper hash code +(via `hashmap_entry_init`). ++ +If an entry with matching hash code is found, `key` and `keydata` are passed +to `hashmap_cmp_fn` to decide whether the entry matches the key. + +`void *hashmap_get_next(const struct hashmap *map, const void *entry)`:: + + Returns the next equal hashmap entry, or NULL if not found. This can be + used to iterate over duplicate entries (see `hashmap_add`). ++ +`map` is the hashmap structure. ++ +`entry` is the hashmap_entry to start the search from, obtained via a previous +call to `hashmap_get` or `hashmap_get_next`. + +`void hashmap_add(struct hashmap *map, void *entry)`:: + + Adds a hashmap entry. This allows to add duplicate entries (i.e. + separate values with the same key according to hashmap_cmp_fn). ++ +`map` is the hashmap structure. ++ +`entry` is the entry to add. + +`void *hashmap_put(struct hashmap *map, void *entry)`:: + + Adds or replaces a hashmap entry. If the hashmap contains duplicate + entries equal to the specified entry, only one of them will be replaced. ++ +`map` is the hashmap structure. ++ +`entry` is the entry to add or replace. ++ +Returns the replaced entry, or NULL if not found (i.e. the entry was added). + +`void *hashmap_remove(struct hashmap *map, const void *key, const void *keydata)`:: + + Removes a hashmap entry matching the specified key. If the hashmap + contains duplicate entries equal to the specified key, only one of + them will be removed. ++ +`map` is the hashmap structure. ++ +`key` is a hashmap_entry structure (or user data structure that starts with +hashmap_entry) that has at least been initialized with the proper hash code +(via `hashmap_entry_init`). ++ +If an entry with matching hash code is found, `key` and `keydata` are +passed to `hashmap_cmp_fn` to decide whether the entry matches the key. ++ +Returns the removed entry, or NULL if not found. + +`void hashmap_iter_init(struct hashmap *map, struct hashmap_iter *iter)`:: +`void *hashmap_iter_next(struct hashmap_iter *iter)`:: +`void *hashmap_iter_first(struct hashmap *map, struct hashmap_iter *iter)`:: + + Used to iterate over all entries of a hashmap. ++ +`hashmap_iter_init` initializes a `hashmap_iter` structure. ++ +`hashmap_iter_next` returns the next hashmap_entry, or NULL if there are no +more entries. ++ +`hashmap_iter_first` is a combination of both (i.e. initializes the iterator +and returns the first entry, if any). + +Usage example +------------- + +Here's a simple usage example that maps long keys to double values. +[source,c] +------------ +struct hashmap map; + +struct long2double { + struct hashmap_entry ent; /* must be the first member! */ + long key; + double value; +}; + +static int long2double_cmp(const struct long2double *e1, const struct long2double *e2, const void *unused) +{ + return !(e1->key == e2->key); +} + +void long2double_init(void) +{ + hashmap_init(&map, (hashmap_cmp_fn) long2double_cmp, 0); +} + +void long2double_free(void) +{ + hashmap_free(&map, 1); +} + +static struct long2double *find_entry(long key) +{ + struct long2double k; + hashmap_entry_init(&k, memhash(&key, sizeof(long))); + k.key = key; + return hashmap_get(&map, &k, NULL); +} + +double get_value(long key) +{ + struct long2double *e = find_entry(key); + return e ? e->value : 0; +} + +void set_value(long key, double value) +{ + struct long2double *e = find_entry(key); + if (!e) { + e = malloc(sizeof(struct long2double)); + hashmap_entry_init(e, memhash(&key, sizeof(long))); + e->key = key; + hashmap_add(&map, e); + } + e->value = value; +} +------------ + +Using variable-sized keys +------------------------- + +The `hashmap_entry_get` and `hashmap_entry_remove` functions expect an ordinary +`hashmap_entry` structure as key to find the correct entry. If the key data is +variable-sized (e.g. a FLEX_ARRAY string) or quite large, it is undesirable +to create a full-fledged entry structure on the heap and copy all the key data +into the structure. + +In this case, the `keydata` parameter can be used to pass +variable-sized key data directly to the comparison function, and the `key` +parameter can be a stripped-down, fixed size entry structure allocated on the +stack. + +See test-hashmap.c for an example using arbitrary-length strings as keys. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 248dcabd50..d4f9804462 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -3795,7 +3795,7 @@ like so: $ git update-index filename ------------------------------------------------- -but to avoid common mistakes with filename globbing etc, the command +but to avoid common mistakes with filename globbing etc., the command will not normally add totally new entries or remove old entries, i.e. it will normally just update existing cache entries. |