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

[Eric Sunshine <sunshine@sunshineco.com>]

On Wed, Sep 2, 2020 at 12:46 PM Junio C Hamano <gitster@pobox.com> wrote:
> 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.