Re: [PATCH v2 4/4] branch: make "-l" a synonym for "--list"

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Aug 30, 2018, 21:07 UTC
Message-ID: <87h8jbd0lv.fsf@evledraar.gmail.com>
In-Reply-To: <20180830205033.GA27399@sigill.intra.peff.net>

On Thu, Aug 30 2018, Jeff King wrote:

Show 21 quoted lines

> On Thu, Aug 30, 2018 at 01:29:53PM -0700, Junio C Hamano wrote:
>
>> >> > I do not know if the documentation that is shipped in 2.20 should
>> >> > talk about how the old world looked like, though.  `-l` was a short
>> >> > for `--create-reflog` is worth saying, but I do not see much value
>> >> > in talking about the warning given in 2.19.
>> >>
>> >> I'm anticipating that there will be users in the wild with similar -l
>> >> invocations, noting this helps them, because they'll be wondering what
>> >> some script that does "git branch -l <name>" is trying to do while
>> >> reading our docs.
>> >
>> > I don't have a strong opinion either way. If we do mention it, it should
>> > probably be short ("Until Git v2.20, the `-l` option was a synonym for
>> > `--create-reflog").
>>
>> I agree that the short one would of course be good.  I am on the
>> fence about mentioning the warning only given in 2.19.
>
> Yeah, I was confused about that part of the thread. Is there something
> proposed to (additionally) go into v2.19? Ævar, can you elaborate?

The patch I proposed was badly worded and on reflection I don't think it's useful to include this, but FWIW what I meant was:

 * 1. <2.19: -l is --create-reflog
 * 2. =2.19: -l is --create-reflog, but will spew a warning to stderr about futre deprecation
 * 3. >2.19: -l is --list

I.e. should we in >2.19 docs say that -l used to mean something different <= 2.19? Yeah, but it's probably worthless information to say that it used to warn in that one release, since the actionable thing to do with this information is to change it to --create-reflog, and unlike going from >2.19 to <2.19 running =2.19 isn't silently going to treat the -l option in a way you might not expect.