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

Documentation: fix various repeat word typos

2022-09-12T18:04:55Z

Inspired by 24966cd982 ("doc: fix repeated words", 08-09-2019), I ran "egrep -R "\<([a-zA-Z]+)\> \<\1\>" ./Documentation/*" to find current cases of repeated words such as "the the" that were quite clearly typos. There were many false positives reported, such as "really really" or valid uses of "that that" which I left alone. Signed-off-by: Jacob Stopak Signed-off-by: Junio C Hamano

docs: move pack format docs to man section 5

2022-08-04T21:12:24Z

Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the various documentation pertaining to the *.pack format and related files, and updating things that refer to it to link to the new location. By moving these we can properly link from the newly created gitformat-commit-graph to a gitformat-chunk-format page. Integrating "Documentation/technical/bitmap-format.txt" and "Documentation/technical/cruft-packs.txt" might logically be part of this change, but as those cover parts of the wider "pack format" (including associated files) that's documented outside of "Documentation/technical/pack-format.txt" let's leave those for now, subsequent commit(s) will address those. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

git docs: add a category for file formats, protocols and interfaces

2022-08-04T21:12:23Z

Create a new "File formats, protocols and other developer interfaces" section in the main "git help git" manual page and start moving the documentation that now lives in "Documentation/technical/*.git" over to it. This complements the newly added and adjacent "Repository, command and file interfaces" section. This makes the technical documentation more accessible and discoverable. Before this we wouldn't install it by default, and had no ability to build man page versions of them. The links to them from our existing documentation link to the generated HTML version of these docs. So let's start moving those over, starting with just the "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe Git bundle format, 2020-02-07). We'll now have a new gitformat-bundle(5) man page. Subsequent commits will move more git internal format documentation over. Unfortunately the syntax of the current Documentation/technical/*.txt is not the same (when it comes to section headings etc.) as our Documentation/*.txt documentation, so change the relevant bits of syntax as we're moving this over. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

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