diff options
Diffstat (limited to 'Documentation')
46 files changed, 688 insertions, 338 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 91a12c7..36c58fc 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -324,7 +324,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in user-manual.xml: user-manual.txt user-manual.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \ + $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \ mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \ diff --git a/Documentation/RelNotes/1.8.5.2.txt b/Documentation/RelNotes/1.8.5.2.txt new file mode 100644 index 0000000..3ac4984 --- /dev/null +++ b/Documentation/RelNotes/1.8.5.2.txt @@ -0,0 +1,20 @@ +Git v1.8.5.2 Release Notes +========================== + +Fixes since v1.8.5.1 +-------------------- + + * "git diff -- ':(icase)makefile'" was unnecessarily rejected at the + command line parser. + + * "git cat-file --batch-check=ok" did not check the existence of + the named object. + + * "git am --abort" sometimes complained about not being able to write + a tree with an 0{40} object in it. + + * 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. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/1.8.5.3.txt b/Documentation/RelNotes/1.8.5.3.txt new file mode 100644 index 0000000..3de2dd0 --- /dev/null +++ b/Documentation/RelNotes/1.8.5.3.txt @@ -0,0 +1,27 @@ +Git v1.8.5.3 Release Notes +========================== + +Fixes since v1.8.5.2 +-------------------- + + * The "--[no-]informative-errors" options to "git daemon" were parsed + a bit too loosely, allowing any other string after these option + names. + + * A "gc" process running as a different user should be able to stop a + new "gc" process from starting. + + * An earlier "clean-up" introduced an unnecessary memory leak to the + credential subsystem. + + * "git mv A B/", when B does not exist as a directory, should error + out, but it didn't. + + * "git rev-parse <revs> -- <paths>" did not implement the usual + disambiguation rules the commands in the "git log" family used in + the same way. + + * "git cat-file --batch=", an admittedly useless command, did not + behave very well. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/1.9.txt b/Documentation/RelNotes/1.9.txt index 9debcc4..7bcf371 100644 --- a/Documentation/RelNotes/1.9.txt +++ b/Documentation/RelNotes/1.9.txt @@ -15,6 +15,17 @@ 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. +The meanings of "--tags" option to "git fetch" has changed; the +command fetches tags _in addition to_ what are fetched by the same +command line without the option. + +The way "git push $there $what" interprets $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. + +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) ------------------------------------------ @@ -68,15 +79,71 @@ Updates since v1.8.5 Foreign interfaces, subsystems and ports. - * The HTTP transport, when talking GSS-Negotinate, uses "100 + * The HTTP transport, when talking GSS-Negotiate, uses "100 Continue" response to avoid having to rewind and resend a large payload, which may not be always doable. * Various bugfixes to remote-bzr and remote-hg (in contrib/). + * The build procedure is aware of MirBSD now. + UI, Workflows & Features + * Fetching from a shallowly-cloned repository used to be forbidden, + 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 + with a truncated history). + + * Just like we give a reasonable default for "less" via the LESS + environment variable, we now specify a reasonable default for "lv" + via the "LV" environment variable when spawning the pager. + + * Two-level configuration variable names in "branch.*" and "remote.*" + 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' + 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. + + * "diff.orderfile=<file>" configuration variable can be used to + pretend as if the "-O<file>" option were given from the command + line of "git diff", etc. + + * The negative pathspec syntax allows "git log -- . ':!dir'" to tell + us "I am interested in everything but 'dir' directory". + + * "git difftool" shows how many different paths there are in total, + and how many of them have been shown so far, to indicate progress. + + * "git push origin master" used to push our 'master' branch to update + the 'master' branch at the 'origin' repository. This has been + enhanced to use the same ref mapping "git push origin" would use to + determine what ref at the 'origin' to be updated with our 'master'. + For example, with this configuration + + [remote "origin"] + push = refs/heads/*:refs/review/* + + that would cause "git push origin" to push out our local branches + to corresponding refs under refs/review/ hierarchy at 'origin', + "git push origin master" would update 'refs/review/master' over + there. Alternatively, if push.default is set to 'upstream' and our + 'master' is set to integrate with 'topic' from the 'origin' branch, + running "git push origin" while on our 'master' would update their + 'topic' branch, and running "git push origin master" while on any + of our branches does the same. + + * "gitweb" learned to treat ref hierarchies other than refs/heads as + if they are additional branch namespaces (e.g. refs/changes/ in + Gerrit). + * "git for-each-ref --format=..." learned a few formatting directives; e.g. "%(color:red)%(HEAD)%(color:reset) %(refname:short) %(subject)". @@ -91,9 +158,36 @@ UI, Workflows & Features * "git rev-parse --parseopt" learned a new "--stuck-long" option to help scripts parse options with an optional parameter. + * The "--tags" option to "git fetch" no longer tells the command to + fetch _only_ the tags. It instead fetches tags _in addition to_ + what are fetched by the same command line without the option. + Performance, Internal Implementation, etc. + * When parsing a 40-hex string into the object name, the string is + checked to see if it can be interpreted as a ref so that a warning + can be given for ambiguity. The code kicked in even when the + core.warnambiguousrefs is set to false to squelch this warning, in + which case the cycles spent to look at the ref namespace were an + expensive no-op, as the result was discarded without being used. + + * The naming convention of the packfiles has been updated; it used to + be based on the enumeration of names of the objects that are + contained in the pack, but now it also depends on how the packed + result is represented---packing the same set of objects using + different settings (or delta order) would produce a pack with + different name. + + * "git diff --no-index" mode used to unnecessarily attempt to read + the index when there is one. + + * The deprecated parse-options macro OPT_BOOLEAN has been removed; + use OPT_BOOL or OPT_COUNTUP in new code. + + * A few duplicate implementations of prefix/suffix string comparison + functions have been unified to starts_with() and ends_with(). + * The new PERLLIB_EXTRA makefile variable can be used to specify additional directories Perl modules (e.g. the ones necessary to run git-svn) are installed on the platform when building. @@ -101,8 +195,14 @@ Performance, Internal Implementation, etc. * "git merge-base" learned the "--fork-point" mode, that implements the same logic used in "git pull --rebase" to find a suitable fork point out of the reflog entries for the remote-tracking branch the - work has been based on. + work has been based on. "git rebase" has the same logic that can be + triggered with the "--fork-point" option. + * A third-party "receive-pack" (the responder to "git push") can + advertise the "no-thin" capability to tell "git push" not to use + the thin-pack optimization. Our receive-pack has always been + capable of accepting and fattening a thin-pack, and will continue + not to ask "git push" to use a non-thin pack. Also contains various documentation updates and code clean-ups. @@ -115,6 +215,99 @@ Unless otherwise noted, all the fixes since v1.8.5 in the maintenance track are contained in this release (see the maintenance releases' notes for details). + * "submodule.*.update=checkout", when propagated from .gitmodules to + .git/config, turned into a "submodule.*.update=none", which did not + make much sense. + (merge efa8fd7 fp/submodule-checkout-mode later to maint). + + * 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 was. + (merge e228c17 js/lift-parent-count-limit later to maint). + + * The basic test used to leave unnecessary trash directories in the + t/ directory. + (merge 738a8be jk/test-framework-updates later to maint). + + * "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 + 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 + corresponding mechanism to sha1_object_info() that was used to + obtain the metainfo (e.g. type & size) about the object. This led + callers to weird inconsistencies. + (merge 663a856 cc/replace-object-info later to maint). + + * "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 + corrupts system error messages in non-C locales. + + * 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 + 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). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7055576..e6d46ed 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -139,8 +139,15 @@ People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for a developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of -your code. For this reason, all patches should be submitted -"inline". If your log message (including your name on the +your code. For this reason, each patch should be submitted +"inline" in a separate message. + +Multiple related patches should be grouped into their own e-mail +thread to help readers find all parts of the series. To that end, +send them as replies to either an additional "cover letter" message +(see below), the first patch, or the respective preceding patch. + +If your log message (including your name on the Signed-off-by line) is not writable in ASCII, make sure that you send off a message in the correct encoding. diff --git a/Documentation/config.txt b/Documentation/config.txt index ab26963..5f4d793 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -567,6 +567,10 @@ be passed to the shell by Git, which will translate the final command to `LESS=FRSX less -+S`. The environment tells the command to set the `S` option to chop long lines but the command line resets it to the default to fold long lines. ++ +Likewise, when the `LV` environment variable is unset, Git sets it +to `-c`. You can override this setting by exporting `LV` with +another value or setting `core.pager` to `lv +c`. core.whitespace:: A comma separated list of common whitespace problems to @@ -2026,6 +2030,10 @@ receive.updateserverinfo:: If set to true, git-receive-pack will run git-update-server-info after receiving data from git-push and updating refs. +receive.shallowupdate:: + If set to true, .git/shallow can be updated when new refs + require new shallow roots. Otherwise those refs are rejected. + remote.pushdefault:: The remote to push to by default. Overrides `branch.<name>.remote` for all branches, and is overridden by @@ -2087,8 +2095,8 @@ remote.<name>.vcs:: remote.<name>.prune:: When set to true, fetching from this remote by default will also - remove any remote-tracking branches which no longer exist on the - remote (as if the `--prune` option was give on the command line). + remove any remote-tracking references that no longer exist on the + remote (as if the `--prune` option was given on the command line). Overrides `fetch.prune` settings, if any. remotes.<group>:: diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 223b931..f07b451 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -98,6 +98,11 @@ diff.mnemonicprefix:: diff.noprefix:: If set, 'git diff' does not show any source or destination prefix. +diff.orderfile:: + File indicating how to order files within a diff, using + one shell glob pattern per line. + Can be overridden by the '-O' option to linkgit:git-diff[1]. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the 'git diff' option '-l'. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index bbed2cd..9b37b2a 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -432,6 +432,9 @@ endif::git-format-patch[] -O<orderfile>:: Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the `diff.orderfile` configuration variable + (see linkgit:git-config[1]). To cancel `diff.orderfile`, + use `-O/dev/null`. ifndef::git-format-patch[] -R:: diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index ba1fe49..92c68c3 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -14,8 +14,18 @@ branch history. Tags for the deepened commits are not fetched. --unshallow:: - Convert a shallow repository to a complete one, removing all - the limitations imposed by shallow repositories. + If the source repository is complete, convert a shallow + repository to a complete one, removing all the limitations + imposed by shallow repositories. ++ +If the source repository is shallow, fetch as much as possible so that +the current repository has the same history as the source repository. + +--update-shallow:: + By default when fetching from a shallow repository, + `git fetch` refuses refs that require updating + .git/shallow. This option updates .git/shallow and accept such + refs. ifndef::git-pull[] --dry-run:: @@ -41,17 +51,20 @@ ifndef::git-pull[] -p:: --prune:: - After fetching, remove any remote-tracking branches which - no longer exist on the remote. + After fetching, remove any remote-tracking references that no + longer exist on the remote. Tags are not subject to pruning + if they are fetched only because of the default tag + auto-following or due to a --tags option. However, if tags + are fetched due to an explicit refspec (either on the command + line or in the remote configuration, for example if the remote + was cloned with the --mirror option), then they are also + subject to pruning. endif::git-pull[] -ifdef::git-pull[] ---no-tags:: -endif::git-pull[] ifndef::git-pull[] -n:: ---no-tags:: endif::git-pull[] +--no-tags:: By default, tags that point at objects that are downloaded from the remote repository are fetched and stored locally. This option disables this automatic tag following. The default @@ -61,11 +74,12 @@ endif::git-pull[] ifndef::git-pull[] -t:: --tags:: - This is a short-hand for giving `refs/tags/*:refs/tags/*` - refspec from the command line, to ask all tags to be fetched - and stored locally. Because this acts as an explicit - refspec, the default refspecs (configured with the - remote.$name.fetch variable) are overridden and not used. + Fetch all tags from the remote (i.e., fetch remote tags + `refs/tags/*` into local tags with the same name), in addition + to whatever else would otherwise be fetched. Using this + option alone does not subject tags to pruning, even if --prune + is used (though tags may be pruned anyway if they are also the + destination of an explicit refspec; see '--prune'). --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 322f5ed..f6a16f4 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -109,6 +109,11 @@ newline. The available atoms are: The size, in bytes, that the object takes up on disk. See the note about on-disk sizes in the `CAVEATS` section below. +`deltabase`:: + If the object is stored as a delta on-disk, this expands to the + 40-hex sha1 of the delta base object. Otherwise, expands to the + null sha1 (40 zeroes). See `CAVEATS` below. + `rest`:: If this atom is used in the output string, input lines are split at the first whitespace boundary. All characters before that @@ -152,10 +157,11 @@ should be taken in drawing conclusions about which refs or objects are responsible for disk usage. The size of a packed non-delta object may be much larger than the size of objects which delta against it, but the choice of which object is the base and which is the delta is arbitrary -and is subject to change during a repack. Note also that multiple copies -of an object may be present in the object database; in this case, it is -undefined which copy's size will be reported. +and is subject to change during a repack. +Note also that multiple copies of an object may be present in the object +database; in this case, it is undefined which copy's size or delta base +will be reported. GIT --- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 91294f8..33ad2ad 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -232,8 +232,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. commit, your HEAD becomes "detached" and you are no longer on any branch (see below for details). + -As a special case, the `"@{-N}"` syntax for the N-th last branch -checks out the branch (instead of detaching). You may also specify +As a special case, the `"@{-N}"` syntax for the N-th last branch/commit +checks out branches (instead of detaching). You may also specify `-` which is synonymous with `"@{-1}"`. + As a further special case, you may use `"A...B"` as a shortcut for the diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 2d0daae..0ea921a 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -3,7 +3,7 @@ git-cherry(1) NAME ---- -git-cherry - Find commits not merged upstream +git-cherry - Find commits yet to be applied to upstream SYNOPSIS -------- @@ -12,46 +12,26 @@ SYNOPSIS DESCRIPTION ----------- -The changeset (or "diff") of each commit between the fork-point and <head> -is compared against each commit between the fork-point and <upstream>. -The diffs are compared after removing any whitespace and line numbers. +Determine whether there are commits in `<head>..<upstream>` that are +equivalent to those in the range `<limit>..<head>`. -Every commit that doesn't exist in the <upstream> branch -has its id (sha1) reported, prefixed by a symbol. The ones that have -equivalent change already -in the <upstream> branch are prefixed with a minus (-) sign, and those -that only exist in the <head> branch are prefixed with a plus (+) symbol: - - __*__*__*__*__> <upstream> - / - fork-point - \__+__+__-__+__+__-__+__> <head> - - -If a <limit> has been given then the commits along the <head> branch up -to and including <limit> are not reported: - - __*__*__*__*__> <upstream> - / - fork-point - \__*__*__<limit>__-__+__> <head> - - -Because 'git cherry' compares the changeset rather than the commit id -(sha1), you can use 'git cherry' to find out if a commit you made locally -has been applied <upstream> under a different commit id. For example, -this will happen if you're feeding patches <upstream> via email rather -than pushing or pulling commits directly. +The equivalence test is based on the diff, after removing whitespace +and line numbers. git-cherry therefore detects when commits have been +"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or +linkgit:git-rebase[1]. +Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with +`-` for commits that have an equivalent in <upstream>, and `+` for +commits that do not. OPTIONS ------- -v:: - Verbose. + Show the commit subjects next to the SHA1s. <upstream>:: - Upstream branch to compare against. - Defaults to the first tracked remote branch, if available. + Upstream branch to search for equivalent commits. + Defaults to the upstream branch of HEAD. <head>:: Working branch; defaults to HEAD. @@ -59,6 +39,103 @@ OPTIONS <limit>:: Do not report commits up to (and including) limit. +EXAMPLES +-------- + +Patch workflows +~~~~~~~~~~~~~~~ + +git-cherry is frequently used in patch-based workflows (see +linkgit:gitworkflows[7]) to determine if a series of patches has been +applied by the upstream maintainer. In such a workflow you might +create and send a topic branch like this: + +------------ +$ git checkout -b topic origin/master +# work and create some commits +$ git format-patch origin/master +$ git send-email ... 00* +------------ + +Later, you can see whether your changes have been applied by saying +(still on `topic`): + +------------ +$ git fetch # update your notion of origin/master +$ git cherry -v +------------ + +Concrete example +~~~~~~~~~~~~~~~~ + +In a situation where topic consisted of three commits, and the +maintainer applied two of them, the situation might look like: + +------------ +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +|/ +o 1234567 branch point +------------ + +In such cases, git-cherry shows a concise summary of what has yet to +be applied: + +------------ +$ git cherry origin/master topic +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +------------ + +Here, we see that the commits A and C (marked with `-`) can be +dropped from your `topic` branch when you rebase it on top of +`origin/master`, while the commit B (marked with `+`) still needs to +be kept so that it will be sent to be applied to `origin/master`. + + +Using a limit +~~~~~~~~~~~~~ + +The optional <limit> is useful in cases where your topic is based on +other work that is not in upstream. Expanding on the previous +example, this might look like: + +------------ +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +| * 0000fff (base) unpublished stuff F +[... snip ...] +| * 0000aaa unpublished stuff A +|/ +o 1234567 merge-base between upstream and topic +------------ + +By specifying `base` as the limit, you can avoid listing commits +between `base` and `topic`: + +------------ +$ git cherry origin/master topic base +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +------------ + + SEE ALSO -------- linkgit:git-patch-id[1] diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 450f158..4987857 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -181,12 +181,7 @@ objects from the source repository into a pack in the cloned repository. --depth <depth>:: Create a 'shallow' clone with a history truncated to the - specified number of revisions. A shallow repository has a - number of limitations (you cannot clone or fetch from - it, nor push from nor into it), but is adequate if you - are only interested in the recent history of a large project - with a long history, and would want to send in fixes - as patches. + specified number of revisions. --[no-]single-branch:: Clone only the history leading to the tip of a single branch, diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index e08a028..5809aa4 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -24,19 +24,22 @@ The ref names and their object names of fetched refs are stored in `.git/FETCH_HEAD`. This information is left for a later merge operation done by 'git merge'. -When <refspec> stores the fetched result in remote-tracking branches, -the tags that point at these branches are automatically -followed. This is done by first fetching from the remote using -the given <refspec>s, and if the repository has objects that are -pointed by remote tags that it does not yet have, then fetch -those missing tags. If the other end has tags that point at -branches you are not interested in, you will not get them. +By default, tags are auto-followed. This means that when fetching +from a remote, any tags on the remote that point to objects that exist +in the local repository are fetched. The effect is to fetch tags that +point at branches that you are interested in. This default behavior +can be changed by using the --tags or --no-tags options, by +configuring remote.<name>.tagopt, or by using a refspec that fetches +tags explicitly. 'git fetch' can fetch from either a single named repository, or from several repositories at once if <group> is given and there is a remotes.<group> entry in the configuration file. (See linkgit:git-config[1]). +When no remote is specified, by default the `origin` remote will be used, +unless there's an upstream branch configured for the current branch. + OPTIONS ------- include::fetch-options.txt[] diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e4c8e82..2eba627 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -393,7 +393,7 @@ git filter-branch --index-filter \ Checklist for Shrinking a Repository ------------------------------------ -git-filter-branch is often used to get rid of a subset of files, +git-filter-branch can be used to get rid of a subset of files, usually with some combination of `--index-filter` and `--subdirectory-filter`. People expect the resulting repository to be smaller than the original, but you need a few more steps to @@ -429,6 +429,37 @@ warned. (or if your git-gc is not new enough to support arguments to `--prune`, use `git repack -ad; git prune` instead). +Notes +----- + +git-filter-branch allows you to make complex shell-scripted rewrites +of your Git history, but you probably don't need this flexibility if +you're simply _removing unwanted data_ like large files or passwords. +For those operations you may want to consider +link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner], +a JVM-based alternative to git-filter-branch, typically at least +10-50x faster for those use-cases, and with quite different +characteristics: + +* Any particular version of a file is cleaned exactly _once_. The BFG, + unlike git-filter-branch, does not give you the opportunity to + handle a file differently based on where or when it was committed + within your history. This constraint gives the core performance + benefit of The BFG, and is well-suited to the task of cleansing bad + data - you don't care _where_ the bad data is, you just want it + _gone_. + +* By default The BFG takes full advantage of multi-core machines, + cleansing commit file-trees in parallel. git-filter-branch cleans + commits sequentially (ie in a single-threaded manner), though it + _is_ possible to write filters that include their own parallellism, + in the scripts executed against each commit. + +* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options] + are much more restrictive than git-filter branch, and dedicated just + to the tasks of removing unwanted data- e.g: + `--strip-blobs-bigger-than 1M`. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 94f5c46..d639abe 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -227,6 +227,10 @@ Documentation ------------- Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-show-ref[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt deleted file mode 100644 index d549328..0000000 --- a/Documentation/git-lost-found.txt +++ /dev/null @@ -1,74 +0,0 @@ -git-lost-found(1) -================= - -NAME ----- -git-lost-found - Recover lost refs that luckily have not yet been pruned - -SYNOPSIS --------- -[verse] -'git lost-found' - -DESCRIPTION ------------ - -*NOTE*: this command is deprecated. Use linkgit:git-fsck[1] with -the option '--lost-found' instead. - -Finds dangling commits and tags from the object database, and -creates refs to them in the .git/lost-found/ directory. Commits and -tags that dereference to commits are stored in .git/lost-found/commit, -and other objects are stored in .git/lost-found/other. - - -OUTPUT ------- -Prints to standard output the object names and one-line descriptions -of any commits or tags found. - -EXAMPLE -------- - -Suppose you run 'git tag -f' and mistype the tag to overwrite. -The ref to your tag is overwritten, but until you run 'git -prune', the tag itself is still there. - ------------- -$ git lost-found -[1ef2b196d909eed523d4f3c9bf54b78cdd6843c6] GIT 0.99.9c -... ------------- - -Also you can use gitk to browse how any tags found relate to each -other. - ------------- -$ gitk $(cd .git/lost-found/commit && echo ??*) ------------- - -After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular `refs` hierarchy by using -the `update-ref` command. - ------------- -$ git cat-file -t 1ef2b196 -tag -$ git cat-file tag 1ef2b196 -object fa41bbce8e38c67a218415de6cfa510c7e50032a -type commit -tag v0.99.9c -tagger Junio C Hamano <junkio@cox.net> 1131059594 -0800 - -GIT 0.99.9c - -This contains the following changes from the "master" branch, since -... -$ git update-ref refs/tags/not-lost-anymore 1ef2b196 -$ git rev-parse not-lost-anymore -1ef2b196d909eed523d4f3c9bf54b78cdd6843c6 ------------- - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index b1f7988..e453132 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -52,6 +52,18 @@ core.worktree setting to make the submodule work in the new location. It also will attempt to update the submodule.<name>.path setting in the linkgit:gitmodules[5] file and stage that file (unless -n is used). +BUGS +---- +Each time a superproject update moves a populated submodule (e.g. when +switching between commits before and after the move) a stale submodule +checkout will remain in the old location and an empty directory will +appear in the new location. To populate the submodule again in the new +location the user will have to run "git submodule update" +afterwards. Removing the old directory is only safe when it uses a +gitfile, as otherwise the history of the submodule will be deleted +too. Both steps will be obsolete when recursive submodule update has +been implemented. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 8cba16d..6ab5f94 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -168,7 +168,8 @@ All commands except clone accept these options. --git-dir <dir>:: Set the 'GIT_DIR' environment variable. See linkgit:git[1]. ---verbose, -v:: +-v:: +--verbose:: Provide more progress information. Sync options @@ -279,7 +280,8 @@ These options can be used to modify 'git p4 submit' behavior. Export tags from Git as p4 labels. Tags found in Git are applied to the perforce working directory. ---dry-run, -n:: +-n:: +--dry-run:: Show just what commits would be submitted to p4; do not change state in Git or p4. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index d94edcd..cdab9ed 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -51,8 +51,7 @@ base-name:: <base-name> to determine the name of the created file. When this option is used, the two files are written in <base-name>-<SHA-1>.{pack,idx} files. <SHA-1> is a hash - of the sorted object names to make the resulting filename - based on the pack content, and written to the standard + based on the pack content and is written to the standard output of the command. --stdout:: diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt deleted file mode 100644 index 87ea3fb..0000000 --- a/Documentation/git-peek-remote.txt +++ /dev/null @@ -1,43 +0,0 @@ -git-peek-remote(1) -================== - -NAME ----- -git-peek-remote - List the references in a remote repository - - -SYNOPSIS --------- -[verse] -'git peek-remote' [--upload-pack=<git-upload-pack>] [<host>:]<directory> - -DESCRIPTION ------------ -This command is deprecated; use 'git ls-remote' instead. - -OPTIONS -------- ---upload-pack=<git-upload-pack>:: - Use this to specify the path to 'git-upload-pack' on the - remote side, if it is not found on your $PATH. Some - installations of sshd ignores the user's environment - setup scripts for login shells (e.g. .bash_profile) and - your privately installed git may not be found on the system - default $PATH. Another workaround suggested is to set - up your $PATH in ".bashrc", but this flag is for people - who do not want to pay the overhead for non-interactive - shells, but prefer having a lean .bashrc file (they set most of - the things up in .bash_profile). - -<host>:: - A remote host that houses the repository. When this - part is specified, 'git-upload-pack' is invoked via - ssh. - -<directory>:: - The repository to sync from. - - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index bf82410..058ac0d 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -24,6 +24,8 @@ objects unreachable from any of these head objects from the object database. In addition, it prunes the unpacked objects that are also found in packs by running 'git prune-packed'. +It also removes entries from .git/shallow that are not reachable by +any ref. Note that unreachable, packed objects will remain. If this is not desired, see linkgit:git-repack[1]. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 6083aab..200eb22 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -99,10 +99,10 @@ must be given before the options meant for 'git fetch'. Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ -include::merge-options.txt[] - :git-pull: 1 +include::merge-options.txt[] + -r:: --rebase[=false|true|preserve]:: When true, rebase the current branch on top of the upstream diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 9eec740..2b7f4f9 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -56,8 +56,13 @@ it can be any arbitrary "SHA-1 expression", such as `master~4` or + The <dst> tells which ref on the remote side is updated with this push. Arbitrary expressions cannot be used here, an actual ref must -be named. If `:`<dst> is omitted, the same ref as <src> will be -updated. +be named. +If `git push [<repository>]` without any `<refspec>` argument is set to +update some ref at the destination with `<src>` with +`remote.<repository>.push` configuration variable, `:<dst>` part can +be omitted---such a push will update a ref that `<src>` normally updates +without any `<refspec>` on the command line. Otherwise, missing +`:<dst>` means to update the same ref as the `<src>`. + The object referenced by <src> is used to update the <dst> reference on the remote side. By default this is only allowed if <dst> is not diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 94e07fd..2889be6 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -324,6 +324,16 @@ fresh commits so it can be remerged successfully without needing to "revert the reversion" (see the link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). +--fork-point:: +--no-fork-point:: + Use 'git merge-base --fork-point' to find a better common ancestor + between `upstream` and `branch` when calculating which commits have + have been introduced by `branch` (see linkgit:git-merge-base[1]). ++ +If no non-option arguments are given on the command line, then the default is +`--fork-point @{u}` otherwise the `upstream` argument is interpreted literally +unless the `--fork-point` option is specified. + --ignore-whitespace:: --whitespace=<option>:: These flag are passed to the 'git apply' program diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index f373ab4..0a02f70 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git replace' [-f] <object> <replacement> 'git replace' -d <object>... -'git replace' -l [<pattern>] +'git replace' [--format=<format>] [-l [<pattern>]] DESCRIPTION ----------- @@ -70,6 +70,23 @@ OPTIONS Typing "git replace" without arguments, also lists all replace refs. +--format=<format>:: + When listing, use the specified <format>, which can be one of + 'short', 'medium' and 'long'. When omitted, the format + defaults to 'short'. + +FORMATS +------- + +The following format are available: + +* 'short': + <replaced sha1> +* 'medium': + <replaced sha1> -> <replacement sha1> +* 'long': + <replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>) + CREATING REPLACEMENT OBJECTS ---------------------------- diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt deleted file mode 100644 index 9ec115b..0000000 --- a/Documentation/git-repo-config.txt +++ /dev/null @@ -1,23 +0,0 @@ -git-repo-config(1) -================== - -NAME ----- -git-repo-config - Get and set repository or global options - - -SYNOPSIS --------- -[verse] -'git repo-config' ... - - -DESCRIPTION ------------ - -This is a synonym for linkgit:git-config[1]. Please refer to the -documentation of that command. - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 9d731b4..f1efc11 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -170,6 +170,15 @@ of files and subdirectories under the `Documentation/` directory. (i.e. you are listing the files explicitly), it does not remove `subdir/git-foo.sh`. +BUGS +---- +Each time a superproject update removes a populated submodule +(e.g. when switching between commits before and after the removal) a +stale submodule checkout will remain in the old location. Removing the +old directory is only safe when it uses a gitfile, as otherwise the +history of the submodule will be deleted too. This step will be +obsolete when recursive submodule update has been implemented. + SEE ALSO -------- linkgit:git-add[1] diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index b0a309b..ffd1b03 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -175,6 +175,7 @@ FILES SEE ALSO -------- +linkgit:git-for-each-ref[1], linkgit:git-ls-remote[1], linkgit:git-update-ref[1], linkgit:gitrepository-layout[5] diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt deleted file mode 100644 index f7362dc..0000000 --- a/Documentation/git-tar-tree.txt +++ /dev/null @@ -1,82 +0,0 @@ -git-tar-tree(1) -=============== - -NAME ----- -git-tar-tree - Create a tar archive of the files in the named tree object - - -SYNOPSIS --------- -[verse] -'git tar-tree' [--remote=<repo>] <tree-ish> [ <base> ] - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. Use 'git archive' with `--format=tar` -option instead (and move the <base> argument to `--prefix=base/`). - -Creates a tar archive containing the tree structure for the named tree. -When <base> is specified it is added as a leading path to the files in the -generated tar archive. - -'git tar-tree' behaves differently when given a tree ID versus when given -a commit ID or tag ID. In the first case the current time is used as -modification time of each file in the archive. In the latter case the -commit time as recorded in the referenced commit object is used instead. -Additionally the commit ID is stored in a global extended pax header. -It can be extracted using 'git get-tar-commit-id'. - -OPTIONS -------- - -<tree-ish>:: - The tree or commit to produce tar archive for. If it is - the object name of a commit object. - -<base>:: - Leading path to the files in the resulting tar archive. - ---remote=<repo>:: - Instead of making a tar archive from local repository, - retrieve a tar archive from a remote repository. - -CONFIGURATION -------------- - -tar.umask:: - This variable can be used to restrict the permission bits of - tar archive entries. The default is 0002, which turns off the - world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) for - details. - -EXAMPLES --------- -`git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`:: - - Create a tar archive that contains the contents of the - latest commit on the current branch, and extracts it in - `/var/tmp/junk` directory. - -`git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`:: - - Create a tarball for v1.4.0 release. - -`git tar-tree v1.4.0^{tree} git-1.4.0 | gzip >git-1.4.0.tar.gz`:: - - Create a tarball for v1.4.0 release, but without a - global extended pax header. - -`git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`:: - - Get a tarball v1.4.0 from example.com. - -`git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`:: - - Put everything in the current head's Documentation/ directory - into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'. - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 4448ce2..274d816 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,11 @@ unreleased) version of Git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.8.5.1/git.html[documentation for release 1.8.5.1] +* link:v1.8.5.3/git.html[documentation for release 1.8.5.3] * release notes for + 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], link:RelNotes/1.8.5.txt[1.8.5]. @@ -806,6 +808,15 @@ temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. + For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 parameter, <path>. ++ +For each path 'GIT_EXTERNAL_DIFF' is called, two environment variables, +'GIT_DIFF_PATH_COUNTER' and 'GIT_DIFF_PATH_TOTAL' are set. + +'GIT_DIFF_PATH_COUNTER':: + A 1-based counter incremented by one for every path. + +'GIT_DIFF_PATH_TOTAL':: + The total number of paths. other ~~~~~ diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index b322a26..643c1ba 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -930,9 +930,12 @@ state. DEFINING MACRO ATTRIBUTES ------------------------- -Custom macro attributes can be defined only in the `.gitattributes` -file at the toplevel (i.e. not in any subdirectory). The built-in -macro attribute "binary" is equivalent to: +Custom macro attributes can be defined only in top-level gitattributes +files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the +top level of the working tree, or the global or system-wide +gitattributes files), not in `.gitattributes` files in working tree +subdirectories. The built-in macro attribute "binary" is equivalent +to: ------------ [attr]binary -diff -merge -text diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index f971960..b08d34d 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -7,7 +7,7 @@ gitignore - Specifies intentionally untracked files to ignore SYNOPSIS -------- -$GIT_DIR/info/exclude, .gitignore +$HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore DESCRIPTION ----------- @@ -79,8 +79,10 @@ PATTERN FORMAT - An optional prefix "`!`" which negates the pattern; any matching file excluded by a previous pattern will become - included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded. Git doesn't list excluded + directories for performance reasons, so any patterns on contained + files have no effect, no matter where they are defined. Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". @@ -182,6 +184,19 @@ Another example: The second .gitignore prevents Git from ignoring `arch/foo/kernel/vmlinux.lds.S`. +Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): + +-------------------------------------------------------------- + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +-------------------------------------------------------------- + SEE ALSO -------- linkgit:git-rm[1], diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index d44e14c..1e9e38a 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -98,6 +98,22 @@ linkgit:git-rev-list[1] for a complete list. (See "History simplification" in linkgit:git-log[1] for a more detailed explanation.) +-L<start>,<end>:<file>:: +-L:<regex>:<file>:: + + Trace the evolution of the line range given by "<start>,<end>" + (or the funcname regex <regex>) within the <file>. You may + not give any pathspec limiters. This is currently limited to + a walk starting from a single revision, i.e., you may only + give zero or one positive revision arguments. + You can specify this option more than once. ++ +*Note:* gitk (unlike linkgit:git-log[1]) currently only understands +this option if you specify it "glued together" with its argument. Do +*not* put a space after `-L`. ++ +include::line-range-format.txt[] + <revision range>:: Limit the revisions to show. This can be either a single revision diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index f7be93f..347a9f7 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -35,6 +35,8 @@ submodule.<name>.url:: linkgit:git-clone[1] or (if it begins with ./ or ../) a location relative to the superproject's origin repository. +In addition, there are a number of optional keys: + submodule.<name>.update:: Defines what to do when the submodule is updated by the superproject. If 'checkout' (the default), the new commit specified in the diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index f1f4ca9..c2908db 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -437,6 +437,13 @@ set by Git if the remote helper has the 'option' capability. 'option check-connectivity' \{'true'|'false'\}:: Request the helper to check connectivity of a clone. +'option cloning \{'true'|'false'\}:: + Notify the helper this is a clone request (i.e. the current + repository is guaranteed empty). + +'option update-shallow \{'true'|'false'\}:: + Allow to extend .git/shallow if the new refs require it. + SEE ALSO -------- linkgit:git-remote[1] diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index e2113d9..db4154f 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -849,6 +849,43 @@ time zones in the form of "+/-HHMM", such as "+0200". + Project specific override is not supported. +extra-branch-refs:: + List of additional directories under "refs" which are going to + be used as branch refs. For example if you have a gerrit setup + where all branches under refs/heads/ are official, + push-after-review ones and branches under refs/sandbox/, + refs/wip and refs/other are user ones where permissions are + much wider, then you might want to set this variable as + follows: ++ +-------------------------------------------------------------------------------- +$feature{'extra-branch-refs'}{'default'} = + ['sandbox', 'wip', 'other']; +-------------------------------------------------------------------------------- ++ +This feature can be configured on per-repository basis after setting +$feature{'extra-branch-refs'}{'override'} to true, via repository's +`gitweb.extraBranchRefs` configuration variable, which contains a +space separated list of refs. An example: ++ +-------------------------------------------------------------------------------- +[gitweb] + extraBranchRefs = sandbox wip other +-------------------------------------------------------------------------------- ++ +The gitweb.extraBranchRefs is actually a multi-valued configuration +variable, so following example is also correct and the result is the +same as of the snippet above: ++ +-------------------------------------------------------------------------------- +[gitweb] + extraBranchRefs = sandbox + extraBranchRefs = wip other +-------------------------------------------------------------------------------- ++ +It is an error to specify a ref that does not pass "git check-ref-format" +scrutiny. Duplicated values are filtered. + EXAMPLES -------- diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index afba8d4..e134315 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -14,9 +14,12 @@ inspect and further tweak the merge result before committing. further edit the auto-generated merge message, so that the user can explain and justify the merge. The `--no-edit` option can be used to accept the auto-generated message (this is generally - discouraged). The `--edit` (or `-e`) option is still useful if you are - giving a draft message with the `-m` option from the command line - and want to edit it in the editor. + discouraged). +ifndef::git-pull[] +The `--edit` (or `-e`) option is still useful if you are +giving a draft message with the `-m` option from the command line +and want to edit it in the editor. +endif::git-pull[] + Older scripts may depend on the historical behaviour of not allowing the user to edit the merge log message. They will see an editor opened when diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 49a9a7d..fb6e593 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -113,3 +113,11 @@ subtree:: match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common ancestor tree. + +With the strategies that use 3-way merge (including the default, 'recursive'), +if a change is made on both branches, but later reverted on one of the +branches, that change will be present in the merged result; some people find +this behavior confusing. It occurs because only the heads and the merge base +are considered when performing a merge, not the individual commits. The merge +algorithm therefore considers the reverted change as no change at all, and +substitutes the changed version instead. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 2c06ed3..5a286d0 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -88,7 +88,7 @@ some output processing may assume ref names in UTF-8. branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. '@\{-<n>\}', e.g. '@\{-1\}':: - The construct '@\{-<n>\}' means the <n>th branch checked out + The construct '@\{-<n>\}' means the <n>th branch/commit checked out before the current one. '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index f3c1357..e3d6e7a 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -14,8 +14,8 @@ Git: . Add the external declaration for the function to `builtin.h`. -. Add the command to `commands[]` table in `handle_internal_command()`, - defined in `git.c`. The entry should look like: +. Add the command to the `commands[]` table defined in `git.c`. + The entry should look like: { "foo", cmd_foo, <options> }, + diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt index 4be8776..5d245aa 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -58,16 +58,16 @@ default remote, given the current branch and configuration. struct refspec -------------- -A struct refspec holds the parsed interpretation of a refspec. If it -will force updates (starts with a '+'), force is true. If it is a -pattern (sides end with '*') pattern is true. src and dest are the two -sides (if a pattern, only the part outside of the wildcards); if there -is only one side, it is src, and dst is NULL; if sides exist but are -empty (i.e., the refspec either starts or ends with ':'), the -corresponding side is "". - -This parsing can be done to an array of strings to give an array of -struct refpsecs with parse_ref_spec(). +A struct refspec holds the parsed interpretation of a refspec. If it +will force updates (starts with a '+'), force is true. If it is a +pattern (sides end with '*') pattern is true. src and dest are the +two sides (including '*' characters if present); if there is only one +side, it is src, and dst is NULL; if sides exist but are empty (i.e., +the refspec either starts or ends with ':'), the corresponding side is +"". + +An array of strings can be parsed into an array of struct refspecs +using parse_fetch_refspec() or parse_push_refspec(). remote_find_tracking(), given a remote and a struct refspec with either src or dst filled out, will fill out the other such that the diff --git a/Documentation/technical/pack-heuristics.txt b/Documentation/technical/pack-heuristics.txt index b7bd951..95a07db 100644 --- a/Documentation/technical/pack-heuristics.txt +++ b/Documentation/technical/pack-heuristics.txt @@ -1,5 +1,5 @@ - Concerning Git's Packing Heuristics - =================================== +Concerning Git's Packing Heuristics +=================================== Oh, here's a really stupid question: diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index b898e97..c73b62f 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -161,6 +161,7 @@ MUST peel the ref if it's an annotated tag. ---- advertised-refs = (no-refs / list-of-refs) + *shallow flush-pkt no-refs = PKT-LINE(zero-id SP "capabilities^{}" @@ -174,6 +175,8 @@ MUST peel the ref if it's an annotated tag. other-tip = obj-id SP refname LF other-peeled = obj-id SP refname "^{}" LF + shallow = PKT-LINE("shallow" SP obj-id) + capability-list = capability *(SP capability) capability = 1*(LC_ALPHA / DIGIT / "-" / "_") LC_ALPHA = %x61-7A @@ -461,7 +464,9 @@ contain all the objects that the server will need to complete the new references. ---- - update-request = command-list [pack-file] + update-request = *shallow command-list [pack-file] + + shallow = PKT-LINE("shallow" SP obj-id) command-list = PKT-LINE(command NUL capability-list LF) *PKT-LINE(command LF) diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index fd8ffa5..e3e7924 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -72,14 +72,29 @@ interleaved with S-R-Q. thin-pack --------- -This capability means that the server can send a 'thin' pack, a pack -which does not contain base objects; if those base objects are available -on client side. Client requests 'thin-pack' capability when it -understands how to "thicken" it by adding required delta bases making -it self-contained. - -Client MUST NOT request 'thin-pack' capability if it cannot turn a thin -pack into a self-contained pack. +A thin pack is one with deltas which reference base objects not +contained within the pack (but are known to exist at the receiving +end). This can reduce the network traffic significantly, but it +requires the receiving end to know how to "thicken" these packs by +adding the missing bases to the pack. + +The upload-pack server advertises 'thin-pack' when it can generate +and send a thin pack. A client requests the 'thin-pack' capability +when it understands how to "thicken" it, notifying the server that +it can receive such a pack. A client MUST NOT request the +'thin-pack' capability if it cannot turn a thin pack into a +self-contained pack. + +Receive-pack, on the other hand, is assumed by default to be able to +handle thin packs, but can ask the client not to use the feature by +advertising the 'no-thin' capability. A client MUST NOT send a thin +pack if the server advertises the 'no-thin' capability. + +The reasons for this asymmetry are historical. The receive-pack +program did not exist until after the invention of thin packs, so +historically the reference implementation of receive-pack always +understood thin packs. Adding 'no-thin' later allowed receive-pack +to disable the feature in a backwards-compatible manner. side-band, side-band-64k diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index cbb01a1..248dcab 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1,5 +1,5 @@ Git User Manual -_______________ +=============== Git is a fast distributed revision control system. |