Re: What's cooking in git.git (Sep 2020, #01; Tue, 1)

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Sep 2, 2020, 16:58 UTC
Message-ID: <CAPig+cTGspJAGxRu+vqdko1ntkBonVaoStYde3+P5UxPxrCs7g@mail.gmail.com>
In-Reply-To: <xmqq7dtcceka.fsf@gitster.c.googlers.com>

On Wed, Sep 2, 2020 at 12:46 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 18 quoted lines

> Eric Sunshine <sunshine@sunshineco.com> writes:
> > I wonder if this could be reworded so it's clearer that "git worktree
> > repair" is a new command, and to mention fixes to "git init
> > --separate-git-dir". Perhaps like this?
> >
> >     "git worktree" gained a "repair" subcommand to help users recover
> >     from problems arising from factors outside of Git's control.
> >     Also, "git init --separate-git-dir" no longer corrupts
> >     administrative data related to linked worktrees.
>
> OK that reads much better.
>
> -from problems arising from factors outside of Git's control.
> +after moving the worktrees manually without telling Git.
>
> The latter is slightly shorter; does the "repair" help situations
> other than that, or is the above cover all the "factors outside" out
> control?

The current implementation also helps out when the main worktree (or bare repository) is moved.

However, in the "git worktree repair" documentation, I intentionally avoided nailing down precisely the problems it repairs, instead leaving it open-ended since it may learn more repairs in the future. (The documentation is careful to say that it repairs "administrative files", and then talks about the currently-implemented repairs as _examples_ of what it might repair, without locking it into only those repairs.)

I think the same generality of description can apply to the blurb here, as well. We don't necessarily need to give precise detail in this blurb -- the reader can learn the details by consulting the documentation.