Re: git-tag documentation enhancement

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 30, 2012, 01:13 UTC
Message-ID: <7vvch6t5in.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAHtLG6SQ3DeexriXRtV4ys7x12iKQtq7OCrZdC+A8SSH6Tokow@mail.gmail.com>

乙酸鋰 <ch3cooli@gmail.com> writes:

Show 6 quoted lines

> I would like to enhance git-tag documentation
>
> --Unless -f is given, the tag to be created must not yet exist in the
> .git/refs/tags/ directory.
> ++Unless -f is given, the tag to be created must not yet exist in the
> .git/refs/tags/ directory or inside .git/packed-refs file.

I think the updated text is technically correct, but I do not think it is a good direction to go. The root cause of the problem was that the original text assumed ".git/refs/tags/ directory" will forever be the only way to have a local tag, and the description was left behind when packed refs mechanism was introduced to improve the file system usage. It shouldn't have relied its description on such an implementation detail in the first place.

The updated text still shares the same problem. I think the right fix is to say something like this:

        Unless -f is given, the tag to be created must not yet exist
        as a local tag.