git help prune accuracy?

I admit that I am guessing here, but I was wondering if this paragraph from git help prune was a incorrect, it says:

  This runs git fsck --unreachable using all the refs 
  available in refs/, optionally with additional set of 
  objects specified on the command line, and prunes all 
  unpacked objects unreachable from any of these head  
  objects from the object database. In addition, it prunes
  the unpacked objects that are also found in packs by
  running git prune-packed.

The last sentence seems like it should maybe have the following fix:

s/it prunes the unpacked/it prunes the unreferenced/

-Martin

On Thursday, December 15, 2011 02:32:09 pm Martin Fick wrote:

Ack, I meant:

s/it prunes the unpacked/it prunes the unreachable/

-Martin

Martin Fick <mfick@codeaurora.org> writes:

"In addition" part is about objects that exist in loose format that are also found in packs and has nothing to do with reachability.

Running "git pack-objects" to collect loose objects into a new pack will not remove these loose objects that are copied into that new pack. Because we try to access objects from an already open packfile before trying a loose object file, removing these now-redundant loose ones after they are packed makes sense. And that is what "git prune-packed" does.

On Thursday, December 15, 2011 03:18:19 pm Junio C Hamano wrote:

Thanks Junio, that makes a lot of sense. I don't know why I was not getting that from the description even though that was exactly what I was looking for. Maybe it was because of the intro/summary line? Now that I think I understand what it is doing, it seems like this command is more about "pruning loose objects" (whether unreachable or already packed) than it is about "pruning unreachable objects" (which could be loose or packed)? The summary line reads:

  git-prune - Prune all unreachable objects from the object 
database

Maybe I am not familiar enough with git terminology, but does "object database" imply loose objects only? Because the word "all" in that summary makes it sound like it will prune all unreachable objects (loose and packed).

I don't quite have an alternative suggestion for a better summary, the best I could do (but don't like) is:

  git-prune - Prune loose objects (unreachable or packed)

-Martin

Martin Fick <mfick@codeaurora.org> writes:

Yea, prune itself has always been primarily about getting rid of unreachable objects. I suspect (I didn't check) that we did not even have a call to prune-packed in its original implementation and it was later added as "we are doing the pruning anyway, why not do this as well while at it".

Yeah, I just checked. Before 51890a6 (Call prune-packed from "git prune" as well., 2005-08-19), we didn't. And 2396ec8 (Add "git-prune-packed" that removes objects that exist in a pack., 2005-07-03) explains it rather nicely:

    Add "git-prune-packed" that removes objects that exist in a pack.
    
    This, together with "git repack" can be used to clean up unpacked
    git archives.

For a one-liner description, "Remove unnecessary or redundant loose objects" without parentheses may be better. Explaining "git prune" as "this prunes" does not add as much information as restating it using a different and more common verb.

The body text can clarify what we mean by "unnecessary" and "redundant". A loose object that is old may be unreachable from any of the refs, i.e. unused, and hence unnecessary. Or the same object as a loose one may be found in a pack, which would make the loose one redundant.