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

Merge branch 'jk/bundle-use-dash-for-stdfiles'

2023-03-19T22:03:12Z

"git bundle" learned that "-" is a common way to say that the input comes from the standard input and/or the output goes to the standard output. It used to work only for output and only from the root level of the working tree. * jk/bundle-use-dash-for-stdfiles: parse-options: use prefix_filename_except_for_dash() helper parse-options: consistently allocate memory in fix_filename() bundle: don't blindly apply prefix_filename() to "-" bundle: document handling of "-" as stdin bundle: let "-" mean stdin for reading operations

bundle: document handling of "-" as stdin

2023-03-06T21:12:56Z

We have always allowed "bundle create -" to write to stdout, but it was never documented. And a recent patch let reading operations like "bundle list-heads -" read from stdin. Let's document all of these cases. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

bundle: turn on --all-progress-implied by default

2023-03-06T17:51:06Z

In 79862b6b77c (bundle-create: progress output control, 2019-11-10), "bundle create" learned about the --all-progress and --all-progress-implied options, which were copied from pack-objects. I think these were a mistake. In pack-objects, "all-progress-implied" is about switching the behavior between a regular on-disk "git repack" and the use of pack-objects for push/fetch (where a fetch does not want progress from the server during the write stage; the client will print progress as it receives the data). But there's no such distinction for bundles. Prior to 79862b6b77c, we always printed the write stage. Afterwards, a vanilla: git bundle create foo.bundle omits the write progress, appearing to hang (especially if your repository is large or your disk is slow). That seems like a regression. It's possible that the flexibility to disable the write-phase progress _could_ be useful for bundle. E.g., if you did something like: ssh some-host git bundle create foo.bundle | git bundle unbundle But if you are running both in real-time, why are you using bundles in the first place? You're better off doing a real fetch. But even if we did want to support that, it should be the exception, and vanilla "bundle create" should display the full progress. So we'd want to name the option "--no-write-progress" or something. The "--all-progress" option itself is even worse. It exists in pack-objects only for historical reasons. It's a mistake because it implies "--progress", and we added "--all-progress-implied" to fix that. There is no reason to propagate that mistake to new commands. Likewise, the documentation for these options was pulled from pack-objects. But it doesn't make any sense in this context. It talks about "--stdout", but that is not even an option that git-bundle supports. This patch flips the default for "--all-progress-implied" back to "true", fixing the regression in 79862b6b77c. This turns that option into a noop, and means that "--all-progress" is really the same as "--progress". We _could_ drop them completely, but since they've been shipped with Git since v2.25.0, it's polite to continue accepting them. I didn't implement any sort of "--no-write-progress" here. I'm not at all convinced it's necessary, and the discussion from the original thread: https://lore.kernel.org/git/20191110204126.30553-2-robbat2@gentoo.org/ shows that that the main focus was on getting --progress and --quiet support, and not any kind of clever "real-time bundle over the network" feature. But technically this patch is making it impossible to do something that you _could_ do post-79862b6b77c. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

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