Re: backwards compatibility, was Re: [PATCH v1 1/3] Introduce config variable "diff.primer"

From: Jeff King <peff@peff.net>
Date: Jan 26, 2009, 20:35 UTC
Message-ID: <20090126203508.GC27604@coredump.intra.peff.net>
In-Reply-To: <7vd4e96dh7.fsf@gitster.siamese.dyndns.org>

On Mon, Jan 26, 2009 at 12:04:20PM -0800, Junio C Hamano wrote:

Show 12 quoted lines

> > Well, this issue seems to come up every so often, so the idea would be:
> >
> > - We're adding a mechanism for scripts to communicate that they need
> > plumbing context
> > - Start using it in your scripts when calling git if you rely on a
> > stable interface
> > - In the next major release, git may introduce changes to commands
> > which are not clearly plumbing if you haven't adopted the mechanism
> 
> Where do all of these nonsense come from?  We are not adding any mechanism
> for scripts to say they need plumbing context.  By calling plumbing they
> are already asking for stable plumbing behaviour.

I think this is my fault a little for mentioning "blurred plumbing and porcelain" and not explaining further. This really has nothing to do with actual plumbing commands. Scripts should use diff-tree and not diff, and that has always and probably will always be the case.

But what about something like "git grep"? Is it plumbing or porcelain? The functionality isn't exposed in any other way, so I can imagine that some scripts are using it. But it's sad to think that we could never have config that might change its behavior, because it is used directly by users all the time. I think the same applies for "git archive". There may be others.

So something like Jay's proposal could future-proof those commands better by allowing scripts to say "BTW, I am a script. Turn off your new features." And there are two classes of alternatives:

  - as you described, instead of making scripts turn _off_ features,
    make them turn them _on_, effectively declaring these commands as
    plumbing. This is obviously much nicer because it Just Works with
    current scripts. But it means that these mixed porcelain/plumbing
    commands suffer in their porcelain capacity; we can never add a
    config option that might change the behavior without the user
    specifying "it's ok to use this feature" at each invocation.

  - we can provide support _now_ for splitting the functionality into
    porcelain and plumbing, scripts can adapt over time to using the
    plumbing version, and then eventually we can declare it safe to make
    changes to the porcelain. And that is more or less what Jay's
    proposal is doing.

    However, I don't think a command-line option is the best way to say
    "I am a script". It's too easy to type "git grep" in a script and
    "git grep -J" (either because you are clueless about "-J", or
    because you simply forget). Other signal methods include:

      - just making two different commands to expose the same
        functionality, one plumbing and one porcelain. This is what has
        evolved in other areas, such as diff (though note that there
        _isn't_ exactly a "git diff" plumbing command -- there is the
        plumbing that "git diff is based on). I'm not sure what the
        plumbing name for "git grep" would be.

      - set an environment variable like GIT_STRICT. It's easy to set
        once at the top of your script, and it trickles down
        automatically as we call other git commands and scripts.
        We could even set it in git-sh-setup, though that of course
        covers only shell scripts, and not other callers.

Show 6 quoted lines

> The scripts can, if they want to, use newer options updated versions of
> the plumbing commands offer, by passing them when they want to.
> 
> And the trigger to do so is up to the scripts.  They can get new options
> from the end user, or they can peek into user's configuration variables
> similar to the diff.primer mentioned earlier in the discussion.

Right, I think that is absolutely the right thing for commands which are clearly plumbing.

Show 6 quoted lines

> One way could be a new option --screw-me-with=name that can be given to a
> plumbing command and tells it pretend as if the command line options
> specified by the configuration variable of the given name were given
> (e.g. a script runs "git diff-files --screw-me-with=diff.primer").
> 
> The important point is that it has to be opt _IN_.

Our precedent so far has been to just add a new command line option that enables the feature (e.g., --ext-diff and --textconv). Functionally it is no different than --screw-me-with=diff.*.textconv. :)

-Peff