git/Documentation/git-bundle.txt, branch v2.37.2

bundle: move capabilities to end of 'verify'

2022-03-23T20:13:59Z

The 'filter' capability was added in 105c6f14a (bundle: parse filter capability, 2022-03-09), but was added in a strange place in the 'git bundle verify' output. The tests for this show output like the following: The bundle contains these 2 refs: The bundle uses this filter: blob:none The bundle records a complete history. This looks very odd if we have a thin bundle that contains boundary commits instead of a complete history: The bundle contains these 2 refs: The bundle uses this filter: blob:none The bundle requires these 2 refs: This separation between tip refs and boundary refs is unfortunate. Move the filter capability output to the end of the output. Update the documentation to match. Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

bundle: parse filter capability

2022-03-09T18:25:27Z

The v3 bundle format has capabilities, allowing newer versions of Git to create bundles with newer features. Older versions that do not understand these new capabilities will fail with a helpful warning. Create a new capability allowing Git to understand that the contained pack-file is filtered according to some object filter. Typically, this filter will be "blob:none" for a blobless partial clone. This change teaches Git to parse this capability, place its value in the bundle header, and demonstrate this understanding by adding a message to 'git bundle verify'. Since we will use gently_parse_list_objects_filter() outside of list-objects-filter-options.c, make it an external method and move its API documentation to before its declaration. Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

git-bundle.txt: add missing words and punctuation

2021-10-28T00:06:12Z

Add an "and" to separate the two halves of the first sentence of the paragraph more. Add a comma to similarly separate the two halves of the second sentence a bit better. Add a period at the end of the paragraph. Further down in the file, add the missing "be" in "must be accompanied". Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

bundle: show progress on "unbundle"

2021-09-07T17:59:23Z

The "unbundle" command added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22) did not show progress output, even though the underlying API learned how to show progress in be042aff24c (Teach progress eye-candy to fetch_refs_from_bundle(), 2011-09-18). Now we'll show "Unbundling objects" using the new --progress-title option to "git index-pack", to go with its existing "Receiving objects" and "Indexing objects" (which it shows when invoked with "--stdin", and with a pack file, respectively). Unlike "git bundle create" we don't handle "--quiet" here, nor "--all-progress" and "--all-progress-implied". Those are all specific to "create" (and "verify", in the case of "--quiet"). The structure of the existing documentation is a bit unclear, e.g. the documentation for the "--quiet" option added in 79862b6b77c (bundle-create: progress output control, 2019-11-10) only describes how it works for "create", and not for "verify". That and other issues in it should be fixed, but I'd like to avoid untangling that mess right now. Let's just support the standard "--no-progress" implicitly here, and leave cleaning up the general behavior of "git bundle" for a later change. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

bundle doc: replace "basis" with "prerequsite(s)"

2021-08-02T21:46:22Z

In the preceding commits we introduced new documentation that talks about "[commit|object] prerequsite(s)", but also faithfully moved around existing documentation that talks about the "basis". Let's change both that moved-around documentation and other existing documentation in the file to consistently use "[commit|object]" prerequisite(s)" instead of talking about "basis". The mention of "basis" isn't wrong, but readers will be helped by us using only one term throughout the document for this concept. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

bundle doc: elaborate on rev<->ref restriction

2021-08-02T21:46:21Z

Elaborate on the restriction that you cannot provide a revision that doesn't resolve to a reference in the "SPECIFYING REFERENCES" section with examples. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

bundle doc: elaborate on object prerequisites

2021-08-02T21:46:21Z

Split out the discussion bout "object prerequisites" into its own section, and add some more examples of the common cases. See 2e0afafebd (Add git-bundle: move objects and references by archive, 2007-02-22) for the introduction of the documentation being changed here. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

bundle doc: rewrite the "DESCRIPTION" section

2021-08-02T21:46:21Z

Rewrite the "DESCRIPTION" section for "git bundle" to start by talking about what bundles are in general terms, rather than diving directly into one example of what they might be used for. This changes documentation that's been substantially the same ever since the command was added in 2e0afafebd8 (Add git-bundle: move objects and references by archive, 2007-02-22). I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT" section, it briefly discusses the format, but then links to the technical/bundle-format.txt documentation. The "the user must specify a basis" part of this is discussed below in "SPECIFYING REFERENCES", and will be further elaborated on in a subsequent commit. So I'm removing that part and letting the mention of "revision exclusions" suffice. There was a discussion about whether to say anything at all about "thin packs" here[1]. I think it's good to mention it for the curious reader willing to read the technical docs, but let's explicitly say that there's no "thick pack", and that the difference shouldn't matter. 1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

bundle: add new version for use with SHA-256

2020-07-30T16:16:48Z

Currently we detect the hash algorithm in use by the length of the object ID. This is inelegant and prevents us from using a different hash algorithm that is also 256 bits in length. Since we cannot extend the v2 format in a backward-compatible way, let's add a v3 format, which is identical, except for the addition of capabilities, which are prefixed by an at sign. We add "object-format" as the only capability and reject unknown capabilities, since we do not have a network connection and therefore cannot negotiate with the other side. For compatibility, default to the v2 format for SHA-1 and require v3 for SHA-256. In t5510, always use format v3 so we can be sure we produce consistent results across hash algorithms. Since head -n N lists the top N lines instead of the Nth line, let's run our output through sed to normalize it and compare it against a fixed value, which will make sure we get exactly what we're expecting. Signed-off-by: brian m. carlson Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

Merge branch 'po/bundle-doc-clonable'

2019-12-10T21:11:41Z

Doc update. * po/bundle-doc-clonable: Doc: Bundle file usage