summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/MyFirstObjectWalk.txt4
-rw-r--r--Documentation/RelNotes/2.34.0.txt278
-rw-r--r--Documentation/config.txt9
-rw-r--r--Documentation/config/advice.txt3
-rw-r--r--Documentation/config/gui.txt2
-rw-r--r--Documentation/config/help.txt16
-rw-r--r--Documentation/config/transfer.txt14
-rw-r--r--Documentation/git-am.txt2
-rw-r--r--Documentation/git-branch.txt3
-rw-r--r--Documentation/git-bugreport.txt4
-rw-r--r--Documentation/git-bundle.txt145
-rw-r--r--Documentation/git-column.txt2
-rw-r--r--Documentation/git-for-each-ref.txt9
-rw-r--r--Documentation/git-index-pack.txt6
-rw-r--r--Documentation/git-maintenance.txt57
-rw-r--r--Documentation/git-merge.txt2
-rw-r--r--Documentation/git-multi-pack-index.txt20
-rw-r--r--Documentation/git-pull.txt21
-rw-r--r--Documentation/git-rebase.txt41
-rw-r--r--Documentation/git-receive-pack.txt5
-rw-r--r--Documentation/git-sparse-checkout.txt10
-rw-r--r--Documentation/git-upload-pack.txt12
-rw-r--r--Documentation/gitfaq.txt2
-rw-r--r--Documentation/merge-options.txt44
-rw-r--r--Documentation/merge-strategies.txt99
-rw-r--r--Documentation/pretty-options.txt6
-rw-r--r--Documentation/rev-list-options.txt8
-rw-r--r--Documentation/technical/api-trace2.txt14
-rw-r--r--Documentation/technical/bitmap-format.txt71
-rw-r--r--Documentation/technical/directory-rename-detection.txt14
-rw-r--r--Documentation/technical/http-protocol.txt3
-rw-r--r--Documentation/technical/multi-pack-index.txt10
-rw-r--r--Documentation/technical/protocol-v2.txt3
-rw-r--r--Documentation/user-manual.txt2
34 files changed, 783 insertions, 158 deletions
diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
index 2d10eea7a9..45eb84d8b4 100644
--- a/Documentation/MyFirstObjectWalk.txt
+++ b/Documentation/MyFirstObjectWalk.txt
@@ -691,7 +691,7 @@ help understand. In our case, that means we omit trees and blobs not directly
referenced by `HEAD` or `HEAD`'s history, because we begin the walk with only
`HEAD` in the `pending` list.)
-First, we'll need to `#include "list-objects-filter-options.h`" and set up the
+First, we'll need to `#include "list-objects-filter-options.h"` and set up the
`struct list_objects_filter_options` at the top of the function.
----
@@ -779,7 +779,7 @@ Count all the objects within and modify the print statement:
while ((oid = oidset_iter_next(&oit)))
omitted_count++;
- printf("commits %d\nblobs %d\ntags %d\ntrees%d\nomitted %d\n",
+ printf("commits %d\nblobs %d\ntags %d\ntrees %d\nomitted %d\n",
commit_count, blob_count, tag_count, tree_count, omitted_count);
----
diff --git a/Documentation/RelNotes/2.34.0.txt b/Documentation/RelNotes/2.34.0.txt
new file mode 100644
index 0000000000..7ce5ab7cc2
--- /dev/null
+++ b/Documentation/RelNotes/2.34.0.txt
@@ -0,0 +1,278 @@
+Git 2.34 Release Notes
+======================
+
+Updates since Git 2.33
+----------------------
+
+UI, Workflows & Features
+
+ * Pathname expansion (like "~username/") learned a way to specify a
+ location relative to Git installation (e.g. its $sharedir which is
+ $(prefix)/share), with "%(prefix)".
+
+ * Use `ort` instead of `recursive` as the default merge strategy.
+
+ * The userdiff pattern for "java" language has been updated.
+
+ * "git rebase" by default skips changes that are equivalent to
+ commits that are already in the history the branch is rebased onto;
+ give messages when this happens to let the users be aware of
+ skipped commits, and also teach them how to tell "rebase" to keep
+ duplicated changes.
+
+ * The advice message that "git cherry-pick" gives when it asks
+ conflicted replay of a commit to be resolved by the end user has
+ been updated.
+
+ * After "git clone --recurse-submodules", all submodules are cloned
+ but they are not by default recursed into by other commands. With
+ submodule.stickyRecursiveClone configuration set, submodule.recurse
+ configuration is set to true in a repository created by "clone"
+ with "--recurse-submodules" option.
+
+ * The logic for auto-correction of misspelt subcommands learned to go
+ interactive when the help.autocorrect configuration variable is set
+ to 'prompt'.
+
+ * "git maintenance" scheduler learned to use systemd timers as a
+ possible backend.
+
+ * "git diff --submodule=diff" showed failure from run_command() when
+ trying to run diff inside a submodule, when the user manually
+ removes the submodule directory.
+
+ * "git bundle unbundle" learned to show progress display.
+
+ * In cone mode, the sparse-index code path learned to remove ignored
+ files (like build artifacts) outside the sparse cone, allowing the
+ entire directory outside the sparse cone to be removed, which is
+ especially useful when the sparse patterns change.
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * "git bisect" spawned "git show-branch" only to pretty-print the
+ title of the commit after checking out the next version to be
+ tested; this has been rewritten in C.
+
+ * "git add" can work better with the sparse index.
+
+ * Support for ancient versions of cURL library (pre 7.19.4) has been
+ dropped.
+
+ * A handful of tests that assumed implementation details of files
+ backend for refs have been cleaned up.
+
+ * trace2 logs learned to show parent process name to see in what
+ context Git was invoked.
+
+ * Loading of ref tips to prepare for common ancestry negotiation in
+ "git fetch-pack" has been optimized by taking advantage of the
+ commit graph when available.
+
+ * Remind developers that the userdiff patterns should be kept simple
+ and permissive, assuming that the contents they apply are always
+ syntactically correct.
+
+ * The current implementation of GIT_TEST_FAIL_PREREQS is broken in
+ that checking for the lack of a prerequisite would not work. Avoid
+ the use of "if ! test_have_prereq X" in a test script.
+
+ * The revision traversal API has been optimized by taking advantage
+ of the commit-graph, when available, to determine if a commit is
+ reachable from any of the existing refs.
+
+ * "git fetch --quiet" optimization to avoid useless computation of
+ info that will never be displayed.
+
+ * Callers from older advice_config[] based API has been updated to
+ use the newer advice_if_enabled() and advice_enabled() API.
+
+ * Teach "test_pause" and "debug" helpers to allow using the HOME and
+ TERM environment variables the user usually uses.
+
+ * "make INSTALL_STRIP=-s install" allows the installation step to use
+ "install -s" to strip the binaries as they get installed.
+
+ * Code that handles large number of refs in the "git fetch" code
+ path has been optimized.
+
+ * The reachability bitmap file used to be generated only for a single
+ pack, but now we've learned to generate bitmaps for history that
+ span across multiple packfiles.
+
+ * The code to make "git grep" recurse into submodules has been
+ updated to migrate away from the "add submodule's object store as
+ an alternate object store" mechanism (which is suboptimal).
+
+ * The tracing of process ancestry information has been enhanced.
+
+ * Reduce number of write(2) system calls while sending the
+ ref advertisement.
+
+ * Update the build procedure to use the "-pedantic" build when
+ DEVELOPER makefile macro is in effect.
+
+ * Large part of "git submodule add" gets rewritten in C.
+
+ * The run-command API has been updated so that the callers can easily
+ ask the file descriptors open for packfiles to be closed immediately
+ before spawning commands that may trigger auto-gc.
+
+
+Fixes since v2.33
+-----------------
+
+ * Input validation of "git pack-objects --stdin-packs" has been
+ corrected.
+ (merge 561fa03529 ab/pack-stdin-packs-fix later to maint).
+
+ * Bugfix for common ancestor negotiation recently introduced in "git
+ push" code path.
+ (merge 82823118b9 jt/push-negotiation-fixes later to maint).
+
+ * "git pull" had various corner cases that were not well thought out
+ around its --rebase backend, e.g. "git pull --ff-only" did not stop
+ but went ahead and rebased when the history on other side is not a
+ descendant of our history. The series tries to fix them up.
+ (merge 6f843a3355 en/pull-conflicting-options later to maint).
+
+ * "git apply" miscounted the bytes and failed to read to the end of
+ binary hunks.
+ (merge 46d723ce57 jk/apply-binary-hunk-parsing-fix later to maint).
+
+ * "git range-diff" code clean-up.
+ (merge c4d5907324 jk/range-diff-fixes later to maint).
+
+ * "git commit --fixup" now works with "--edit" again, after it was
+ broken in v2.32.
+ (merge 8ef6aad664 jk/commit-edit-fixup-fix later to maint).
+
+ * Use upload-artifacts v1 (instead of v2) for 32-bit linux, as the
+ new version has a blocker bug for that architecture.
+ (merge 3cf9bb36bf cb/ci-use-upload-artifacts-v1 later to maint).
+
+ * Checking out all the paths from HEAD during the last conflicted
+ step in "git rebase" and continuing would cause the step to be
+ skipped (which is expected), but leaves MERGE_MSG file behind in
+ $GIT_DIR and confuses the next "git commit", which has been
+ corrected.
+ (merge e5ee33e855 pw/rebase-skip-final-fix later to maint).
+
+ * Various bugs in "git rebase -r" have been fixed.
+ (merge f2563c9ef3 pw/rebase-r-fixes later to maint).
+
+ * mmap() imitation used to call xmalloc() that dies upon malloc()
+ failure, which has been corrected to just return an error to the
+ caller to be handled.
+ (merge 95b4ff3931 rs/git-mmap-uses-malloc later to maint).
+
+ * "git diff --relative" segfaulted and/or produced incorrect result
+ when there are unmerged paths.
+ (merge 8174627b3d dd/diff-files-unmerged-fix later to maint).
+
+ * The delayed checkout code path in "git checkout" etc. were chatty
+ even when --quiet and/or --no-progress options were given.
+ (merge 7a132c628e mt/quiet-with-delayed-checkout later to maint).
+
+ * "git branch -D <branch>" used to refuse to remove a broken branch
+ ref that points at a missing commit, which has been corrected.
+ (merge 597a977489 rs/branch-allow-deleting-dangling later to maint).
+
+ * Build update for Apple clang.
+ (merge f32c5d3716 cb/makefile-apple-clang later to maint).
+
+ * The parser for the "--nl" option of "git column" has been
+ corrected.
+ (merge c93ca46cf5 sg/column-nl later to maint).
+
+ * "git upload-pack" which runs on the other side of "git fetch"
+ forgot to take the ref namespaces into account when handling
+ want-ref requests.
+ (merge 53a66ec37c ka/want-ref-in-namespace later to maint).
+
+ * The sparse-index support can corrupt the index structure by storing
+ a stale and/or uninitialized data, which has been corrected.
+ (merge d9e9b44d7a jh/sparse-index-resize-fix later to maint).
+
+ * Buggy tests could damage repositories outside the throw-away test
+ area we created. We now by default export GIT_CEILING_DIRECTORIES
+ to limit the damage from such a stray test.
+ (merge 614c3d8f2e sg/set-ceiling-during-tests later to maint).
+
+ * Even when running "git send-email" without its own threaded
+ discussion support, a threading related header in one message is
+ carried over to the subsequent message to result in an unwanted
+ threading, which has been corrected.
+ (merge e082113484 mh/send-email-reset-in-reply-to later to maint).
+
+ * The output from "git fast-export", when its anonymization feature
+ is in use, showed an annotated tag incorrectly.
+ (merge 2f040a9671 tk/fast-export-anonymized-tag-fix later to maint).
+
+ * Doc update plus improved error reporting.
+ (merge 1e93770888 jk/log-warn-on-bogus-encoding later to maint).
+
+ * Recent "diff -m" changes broke "gitk", which has been corrected.
+ (merge 5acffd3473 so/diff-index-regression-fix later to maint).
+
+ * Regression fix.
+ (merge b996f84989 ab/send-email-config-fix later to maint).
+
+ * The "git apply -3" code path learned not to bother the lower level
+ merge machinery when the three-way merge can be trivially resolved
+ without the content level merge. This fixes a regression caused by
+ recent "-3way first and fall back to direct application" change.
+ (merge 57f183b698 jc/trivial-threeway-binary-merge later to maint).
+
+ * The code that optionally creates the *.rev reverse index file has
+ been optimized to avoid needless computation when it is not writing
+ the file out.
+ (merge 8fe8bae9d2 ab/reverse-midx-optim later to maint).
+
+ * "git range-diff -I... <range> <range>" segfaulted, which has been
+ corrected.
+ (merge 709b3f32d3 rs/range-diff-avoid-segfault-with-I later to maint).
+
+ * The order in which various files that make up a single (conceptual)
+ packfile has been reevaluated and straightened up. This matters in
+ correctness, as an incomplete set of files must not be shown to a
+ running Git.
+ (merge 4bc1fd6e39 tb/pack-finalize-ordering later to maint).
+
+ * The "mode" word is useless in a call to open(2) that does not
+ create a new file. Such a call in the files backend of the ref
+ subsystem has been cleaned up.
+ (merge 35cf94eaf6 rs/no-mode-to-open-when-appending later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+ (merge 1d9c8daef8 ab/bundle-doc later to maint).
+ (merge 81483fe613 en/merge-strategy-docs later to maint).
+ (merge 626beebdf8 js/log-protocol-version later to maint).
+ (merge 00e302da76 cb/builtin-merge-format-string-fix later to maint).
+ (merge ad51ae4dc0 cb/ci-freebsd-update later to maint).
+ (merge be6444d1ca fc/completion-updates later to maint).
+ (merge ff7b83f562 ti/tcsh-completion-regression-fix later to maint).
+ (merge 325b06deda sg/make-fix-ar-invocation later to maint).
+ (merge bd72824c60 me/t5582-cleanup later to maint).
+ (merge f6a5af0f62 ga/send-email-sendmail-cmd later to maint).
+ (merge f58c7468cd ab/ls-remote-packet-trace later to maint).
+ (merge 0160f7e725 ab/rebase-fatal-fatal-fix later to maint).
+ (merge a16eb6b1ff js/maintenance-launchctl-fix later to maint).
+ (merge c21b2511c2 jk/t5323-no-pack-test-fix later to maint).
+ (merge 5146c2f148 mh/credential-leakfix later to maint).
+ (merge 1549577338 dd/t6300-wo-gpg-fix later to maint).
+ (merge 66e905b7dd rs/xopen-reports-open-failures later to maint).
+ (merge 469888e6a5 es/walken-tutorial-fix later to maint).
+ (merge 88682b016d ba/object-info later to maint).
+ (merge b45c172e51 ab/gc-log-rephrase later to maint).
+ (merge ccdd5d1eb1 ab/mailmap-leakfix later to maint).
+ (merge 6540b71614 cb/remote-ndebug-fix later to maint).
+ (merge e4f8d27585 rs/show-branch-simplify later to maint).
+ (merge e124ecf7f7 rs/archive-use-object-id later to maint).
+ (merge cebead1ebf cb/ci-build-pedantic later to maint).
+ (merge ca0cc98e03 bs/doc-bugreport-outdir later to maint).
+ (merge 72b113e562 ab/no-more-check-bindir later to maint).
+ (merge 92a5d1c9b4 jc/prefix-filename-allocates later to maint).
+ (merge d9a65b6c0a rs/setup-use-xopen-and-xdup later to maint).
+ (merge e8f55568de jk/t5562-racefix later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index bf82766a6a..0c0e6b859f 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -298,6 +298,15 @@ pathname::
tilde expansion happens to such a string: `~/`
is expanded to the value of `$HOME`, and `~user/` to the
specified user's home directory.
++
+If a path starts with `%(prefix)/`, the remainder is interpreted as a
+path relative to Git's "runtime prefix", i.e. relative to the location
+where Git itself was installed. For example, `%(prefix)/bin/` refers to
+the directory in which the Git executable itself lives. If Git was
+compiled without runtime prefix support, the compiled-in prefix will be
+subsituted instead. In the unlikely event that a literal path needs to
+be specified that should _not_ be expanded, it needs to be prefixed by
+`./`, like so: `./%(prefix)/bin`.
Variables
diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index 8b2849ff7b..063eec2511 100644
--- a/Documentation/config/advice.txt
+++ b/Documentation/config/advice.txt
@@ -44,6 +44,9 @@ advice.*::
Shown when linkgit:git-push[1] rejects a forced update of
a branch when its remote-tracking ref has updates that we
do not have locally.
+ skippedCherryPicks::
+ Shown when linkgit:git-rebase[1] skips a commit that has already
+ been cherry-picked onto the upstream branch.
statusAheadBehind::
Shown when linkgit:git-status[1] computes the ahead/behind
counts for a local ref compared to its remote tracking ref,
diff --git a/Documentation/config/gui.txt b/Documentation/config/gui.txt
index d30831a130..0c087fd8c9 100644
--- a/Documentation/config/gui.txt
+++ b/Documentation/config/gui.txt
@@ -11,7 +11,7 @@ gui.displayUntracked::
in the file list. The default is "true".
gui.encoding::
- Specifies the default encoding to use for displaying of
+ Specifies the default character encoding to use for displaying of
file contents in linkgit:git-gui[1] and linkgit:gitk[1].
It can be overridden by setting the 'encoding' attribute
for relevant files (see linkgit:gitattributes[5]).
diff --git a/Documentation/config/help.txt b/Documentation/config/help.txt
index 783a90a0f9..610701f9a3 100644
--- a/Documentation/config/help.txt
+++ b/Documentation/config/help.txt
@@ -9,13 +9,15 @@ help.format::
help.autoCorrect::
If git detects typos and can identify exactly one valid command similar
- to the error, git will automatically run the intended command after
- waiting a duration of time defined by this configuration value in
- deciseconds (0.1 sec). If this value is 0, the suggested corrections
- will be shown, but not executed. If it is a negative integer, or
- "immediate", the suggested command
- is run immediately. If "never", suggestions are not shown at all. The
- default value is zero.
+ to the error, git will try to suggest the correct command or even
+ run the suggestion automatically. Possible config values are:
+ - 0 (default): show the suggested command.
+ - positive number: run the suggested command after specified
+deciseconds (0.1 sec).
+ - "immediate": run the suggested command immediately.
+ - "prompt": show the suggestion and prompt for confirmation to run
+the command.
+ - "never": don't run or show any suggested command.
help.htmlPath::
Specify the path where the HTML documentation resides. File system paths
diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt
index 505126a780..b49429eb4d 100644
--- a/Documentation/config/transfer.txt
+++ b/Documentation/config/transfer.txt
@@ -52,13 +52,17 @@ If you have multiple hideRefs values, later entries override earlier ones
(and entries in more-specific config files override less-specific ones).
+
If a namespace is in use, the namespace prefix is stripped from each
-reference before it is matched against `transfer.hiderefs` patterns.
+reference before it is matched against `transfer.hiderefs` patterns. In
+order to match refs before stripping, add a `^` in front of the ref name. If
+you combine `!` and `^`, `!` must be specified first.
++
For example, if `refs/heads/master` is specified in `transfer.hideRefs` and
the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master`
-is omitted from the advertisements but `refs/heads/master` and
-`refs/namespaces/bar/refs/heads/master` are still advertised as so-called
-"have" lines. In order to match refs before stripping, add a `^` in front of
-the ref name. If you combine `!` and `^`, `!` must be specified first.
+is omitted from the advertisements. If `uploadpack.allowRefInWant` is set,
+`upload-pack` will treat `want-ref refs/heads/master` in a protocol v2
+`fetch` command as if `refs/namespaces/foo/refs/heads/master` did not exist.
+`receive-pack`, on the other hand, will still advertise the object id the
+ref is pointing to without mentioning its name (a so-called ".have" line).
+
Even if you hide refs, a client may still be able to steal the target
objects via the techniques described in the "SECURITY" section of the
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 8714dfcb76..0a4a984dfd 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -178,6 +178,8 @@ default. You can use `--no-utf8` to override this.
--abort::
Restore the original branch and abort the patching operation.
+ Revert contents of files involved in the am operation to their
+ pre-am state.
--quit::
Abort the patching operation but keep HEAD and the index
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 94dc9a54f2..5449767121 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -118,7 +118,8 @@ OPTIONS
Reset <branchname> to <startpoint>, even if <branchname> exists
already. Without `-f`, 'git branch' refuses to change an existing branch.
In combination with `-d` (or `--delete`), allow deleting the
- branch irrespective of its merged status. In combination with
+ branch irrespective of its merged status, or whether it even
+ points to a valid commit. In combination with
`-m` (or `--move`), allow renaming the branch even if the new
branch name already exists, the same applies for `-c` (or `--copy`).
diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt
index 66e88c2e31..d8817bf3ce 100644
--- a/Documentation/git-bugreport.txt
+++ b/Documentation/git-bugreport.txt
@@ -40,8 +40,8 @@ OPTIONS
-------
-o <path>::
--output-directory <path>::
- Place the resulting bug report file in `<path>` instead of the root of
- the Git repository.
+ Place the resulting bug report file in `<path>` instead of the current
+ directory.
-s <format>::
--suffix <format>::
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b..71b5ecabd1 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -13,26 +13,53 @@ SYNOPSIS
[--version=<version>] <file> <git-rev-list-args>
'git bundle' verify [-q | --quiet] <file>
'git bundle' list-heads <file> [<refname>...]
-'git bundle' unbundle <file> [<refname>...]
+'git bundle' unbundle [--progress] <file> [<refname>...]
DESCRIPTION
-----------
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
OPTIONS
-------
@@ -117,28 +144,88 @@ unbundle <file>::
SPECIFYING REFERENCES
---------------------
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads. References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis. More than one reference may be packaged, and more
-than one basis can be specified. The objects packaged are those not
-contained in the union of the given bases. Each basis can be
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
+bundle.
+
+More than one reference may be packaged, and more than one set of prerequisite objects can
+be specified. The objects packaged are those not contained in the
+union of the prerequisites.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
+
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
-It is very important that the basis used be held by the destination.
It is okay to err on the side of caution, causing the bundle file
to contain objects already in the destination, as these are ignored
when unpacking at the destination.
-`git clone` can use any bundle created without negative refspecs
-(e.g., `new`, but not `old..new`).
If you want to match `git clone --mirror`, which would include your
refs such as `refs/remotes/*`, use `--all`.
If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
EXAMPLES
--------
@@ -149,7 +236,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.).
We want to update R2 with development made on the branch master in R1.
To bootstrap the process, you can first create a bundle that does not have
-any basis. You can use a tag to remember up to what commit you last
+any prerequisites. You can use a tag to remember up to what commit you last
processed, in order to make it easy to later update the other repository
with an incremental bundle:
@@ -200,7 +287,7 @@ machineB$ git pull
If you know up to what commit the intended recipient repository sho