git help prune accuracy?

git help prune accuracy?

[Martin Fick]

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

-- 
Employee of Qualcomm Innovation Center, Inc. which is a 
member of Code Aurora Forum

Re: git help prune accuracy?

[Martin Fick]

On Thursday, December 15, 2011 02:32:09 pm Martin Fick 
wrote:
> 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/

Ack, I meant:

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

-Martin

-- 
Employee of Qualcomm Innovation Center, Inc. which is a 
member of Code Aurora Forum

Re: git help prune accuracy?

[Junio C Hamano]

Martin Fick <mfick@codeaurora.org> writes:

>>   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/
>
> Ack, I meant:
>
> s/it prunes the unpacked/it prunes the unreachable/

"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.

Re: git help prune accuracy?

[Martin Fick]

On Thursday, December 15, 2011 03:18:19 pm Junio C Hamano 
wrote:
> Martin Fick <mfick@codeaurora.org> writes:
> >>   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/
> > 
> > Ack, I meant:
> > 
> > s/it prunes the unpacked/it prunes the unreachable/
> 
> "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.

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


-- 
Employee of Qualcomm Innovation Center, Inc. which is a 
member of Code Aurora Forum

Re: git help prune accuracy?

[Junio C Hamano]

Martin Fick <mfick@codeaurora.org> writes:

> ...  The summary line reads:
>
>   git-prune - Prune all unreachable objects from the object 
> database

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.

> 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)

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.