On Thu, Nov 30, 2023 at 02:29:52PM -0500, Taylor Blau wrote: > 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. Yeah, this indeed feels too detailed to be added here. I was hoping for a simple "Never do this if"-style rule that points out why it is unwise under some circumstances, but seems like it's not as simple as that. Well, so be it. Thanks! Patrick
Attachment:
signature.asc
Description: PGP signature
