On Thu, Nov 30, 2023 at 11:18:51AM +0100, Patrick Steinhardt wrote: > > diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt > > index d130e65b28..ac0c7b124b 100644 > > --- a/Documentation/git-multi-pack-index.txt > > +++ b/Documentation/git-multi-pack-index.txt > > @@ -54,6 +54,14 @@ write:: > > "disjoint". See the "`DISP` chunk and disjoint packs" > > section in linkgit:gitformat-pack[5] for more. > > > > + --retain-disjoint:: > > + When writing a multi-pack index with a reachability > > + bitmap, keep any packs marked as disjoint in the > > + existing MIDX (if any) as such in the new MIDX. Existing > > + disjoint packs which are removed (e.g., not listed via > > + `--stdin-packs`) are ignored. This option works in > > + addition to the '+' marker for `--stdin-packs`. > > I'm trying to understand when you're expected to pass this flag and when > you're expected not to pass it. This documentation could also help in > the documentation here so that the user can make a more informed > decision. I think there are multiple reasons that you may or may not want to pass that flag. Certainly if you're not using disjoint packs (and instead only care about single-pack verbatim reuse over the MIDX's preferred packfile), then you don't need to pass it. But if you are using disjoint packs, you may want to pass it if you are adding packs to the MIDX which are disjoint, _and_ you want to hold onto the existing set of disjoint packs. But if you want to change the set of disjoint packs entirely, you would want to omit this flag (unless you knew a-priori that you were going to drop all of the currently marked disjoint packs from the new MIDX you are writing, e.g. with --stdin-packs). If you think it would be useful, I could try and distill some of this down, but I think that there is likely too much detail here for it to be useful in user-facing documentation. Thanks, Taylor
