Adding "--ignore-submodules" switch to git-describe

Adding "--ignore-submodules" switch to git-describe

[Francis Moreau]

Hello,

Would it make sense to add the option --ignore-submodules (currently
available in git-status) to git-describe when the later is used with
--dirty option ?

Thanks
-- 
Francis

Re: Adding "--ignore-submodules" switch to git-describe

[Junio C Hamano]

Francis Moreau <francis.moro@gmail.com> writes:

> Would it make sense to add the option --ignore-submodules (currently
> available in git-status) to git-describe when the later is used with
> --dirty option ?

I think the spirit of "describe --dirty" is to allow people who
gives out binaries this assurance:

	The version string I got out of "describe --dirty" does not
	say dirty. If the recipient of the binary later reports
	issues, I should be able to reproduce the same binary by
	starting from a pristine checkout of the version (provided
	if I didn't screw up and depended on an untracked file when
	I initially created the binary, or used a custom build
	option, or lost the toolchain, ..., of course).

With that in mind, does --ignore-submodules make sense?

As we do not take untracked content at the superproject level into
account when deciding "--dirty"-ness, I think it is very sensible to
either do one of the following:

 (1) always ignore untracked files in submodule working trees; or

 (2) if we were to introduce some form of --ignore-submodules,
     ignore untracked files in the superproject working tree when we
     use that mechanism to ignore untracked files in submodule
     working trees.

Strictly speaking, (1) is a degenerate case of (2).

Using the same semantics of "--ignore-submodules" as "git status"
would not make much sense. "git status --ignore-submodules" does not
show modified submodules at all (e.g. the gitlink recorded in the
HEAD of the superproject being described does not match what is
checked out), so a clean output from the "describe --dirty" at the
superproject level does not give any assurance on the build
artifact.  It defeats the whole point of "describe --dirty".

I think what is missing from "--dirty" is not "--ignore-submodules",
but "--do-not-ignore-untracked" option [*1*].  "describe --dirty"
ignores untracked files in the superproject by default, and we
should ignore untracked files in submodule working trees, but the
current code does not.  Fixing that is (1) above.

And then when "--do-not-ignore-untracked" is in effect, we should
report a "dirty" revision when the working tree of the superproject
or any of the submodule working trees has untracked cruft.

You might want to argue, in the longer term, that the default should
be "--do-not-ignore-untracked" and people who want the current
toplevel behaviour should ask it with "--ignore-untracked".  I am
somewhat sympathetic to that position, but I do not think it is
practical.  People are not perfect and they do keep untracked and
unignored paths in the working tree; ignoring untracked paths does
have an excuse to be the default from practical point of view.

But when we ignore untracked paths in the superproject, we should
ignore untracked paths in submodule working trees consistently.


[Footnote]

*1* Ignoring any other kind of change in submodules (i.e. "none",
"dirty" or "all" for "git status --ignore-submodules=<when>") in the
context of "describe --dirty" in the superproject tree does not make
any sense, so

	BAD$ git describe --dirty --ignore-submodules=<when>

is not a right thing to do.

Re: Adding "--ignore-submodules" switch to git-describe

[Jens Lehmann]

Am 01.03.2013 18:46, schrieb Junio C Hamano:
> I think what is missing from "--dirty" is not "--ignore-submodules",
> but "--do-not-ignore-untracked" option [*1*].  "describe --dirty"
> ignores untracked files in the superproject by default, and we
> should ignore untracked files in submodule working trees, but the
> current code does not.  Fixing that is (1) above.
>
> And then when "--do-not-ignore-untracked" is in effect, we should
> report a "dirty" revision when the working tree of the superproject
> or any of the submodule working trees has untracked cruft.

I agree with your analysis. What about teaching describe the
"-u|--untracked-files" option which status already knows? The
two modes could be "no" and "yes" here (as the distinction
between "normal" and "all" doesn't make any sense for describe).
Current default would be "no", using "-u" alone would set mode to
"yes".

> You might want to argue, in the longer term, that the default should
> be "--do-not-ignore-untracked" and people who want the current
> toplevel behaviour should ask it with "--ignore-untracked".  I am
> somewhat sympathetic to that position, but I do not think it is
> practical.  People are not perfect and they do keep untracked and
> unignored paths in the working tree; ignoring untracked paths does
> have an excuse to be the default from practical point of view.

I think the default mostly depends on the habits of the people
using a repo. Personally I would lean towards making "-uyes" the
default, because in my experience untracked files can make a huge
difference when you later try to reproduce a certain version and
its behavior (and additionally that is just what status already
uses as default). But I won't care that much about the default if
we would just reuse the "status.showUntrackedFiles" config option
to set the default for describe too. This should allow to set the
policy per repo or globally to peoples taste. Does that make sense?

> But when we ignore untracked paths in the superproject, we should
> ignore untracked paths in submodule working trees consistently.

Definitely (we fixed that for status some time ago in 3bfc45047).

Re: Adding "--ignore-submodules" switch to git-describe

[Francis Moreau]

Hi,

Sorry for the long delay, I somehow missed your answer...

On Fri, Mar 1, 2013 at 6:46 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Francis Moreau <francis.moro@gmail.com> writes:
>
>> Would it make sense to add the option --ignore-submodules (currently
>> available in git-status) to git-describe when the later is used with
>> --dirty option ?
>
> I think the spirit of "describe --dirty" is to allow people who
> gives out binaries this assurance:
>
>         The version string I got out of "describe --dirty" does not
>         say dirty. If the recipient of the binary later reports
>         issues, I should be able to reproduce the same binary by
>         starting from a pristine checkout of the version (provided
>         if I didn't screw up and depended on an untracked file when
>         I initially created the binary, or used a custom build
>         option, or lost the toolchain, ..., of course).
>
> With that in mind, does --ignore-submodules make sense?

Well, I wouldn't have thought about this definition of "describe
--dirty". I would have thought that, by default, this command look
only at the files that git knows/tracks. There're too many external
(to the git repo) parameters that could influence the build of a
project: environment variables, components of the toolchain, version
of each components etc... that git doesn't know about.

[...]

>
> But when we ignore untracked paths in the superproject, we should
> ignore untracked paths in submodule working trees consistently.
>
>

yes I agree.

But in the short term, could you suggest a method to workaround this
inconsistency ?

Thanks.
-- 
Francis

Re: Adding "--ignore-submodules" switch to git-describe

[Junio C Hamano]

Francis Moreau <francis.moro@gmail.com> writes:

>> But when we ignore untracked paths in the superproject, we should
>> ignore untracked paths in submodule working trees consistently.
>
> yes I agree.
>
> But in the short term, could you suggest a method to workaround this
> inconsistency ?

Hrm, ... didn't I already?

    As we do not take untracked content at the superproject level into
    account when deciding "--dirty"-ness, I think it is very sensible to
    either do one of the following:

     (1) always ignore untracked files in submodule working trees; or

     (2) if we were to introduce some form of --ignore-submodules,
         ignore untracked files in the superproject working tree when we
         use that mechanism to ignore untracked files in submodule
         working trees.

    Strictly speaking, (1) is a degenerate case of (2).

    ...
    I think what is missing from "--dirty" is not "--ignore-submodules",
    but "--do-not-ignore-untracked" option [*1*].  "describe --dirty"
    ignores untracked files in the superproject by default, and we
    should ignore untracked files in submodule working trees, but the
    current code does not.  Fixing that is (1) above.

I think the right first step without any new option is to make
"describe --dirty" to ignore the dirtiness in submodules coming
solely from having untracked files in submodules' working trees.

You could later add --having-untracked-is-dirty option to mark the
output dirty when there is an untracked file in submodules' working
trees or the toplevel working tree, which would be the second step.