Re: [PATCH v1 01/11] checkout: split part of it to new command 'restore'

[Duy Nguyen <pclouds@gmail.com>]

On Sat, Mar 9, 2019 at 1:01 AM Elijah Newren <newren@gmail.com> wrote:
>
> Thanks for working on this; overall looks really good.  I've got a few
> comments here and there on the wording and combinations of options...
>
> On Fri, Mar 8, 2019 at 2:17 AM Nguyễn Thái Ngọc Duy <pclouds@gmail.com> wrote:
> > +SYNOPSIS
>
> It might be worth adding some words somewhere to differentiate between
> `reset` and `restore`.  E.g.
>
> `git restore` modifies the working tree (and maybe index) to change
> file content to match some other (usually older) version, but does not
> update your branch.  `git reset` is about modifying which commit your
> branch points to, meaning possibly removing and/or adding many commits
> to your branch.
>
> It may also make sense to add whatever description you use to the reset manpage.

Good point.

> > +--------
> > +[verse]
> > +'git restore' [<options>] [--source=<revision>] <pathspec>...
> > +'git restore' (-p|--patch) [--source=<revision>] [<pathspec>...]
>
> So one cannot specify any special options with -p?  Does that mean one
> cannot use it with --index (i.e. this command cannot replace 'git
> reset -p')?  Or is this an oversight in the synopsis?

Oversight. -p can be used with either --index or --worktree or both.

> > +
> > +When a `<revision>` is given, the paths that match the `<pathspec>` are
> > +updated both in the index and in the working tree.
>
> I thought the default was --worktree.  Is this sentence from an older
> version of your patch series that you forgot to update?

Oops.

> > +-q::
> > +--quiet::
> > +       Quiet, suppress feedback messages.
> > +
> > +--progress::
> > +--no-progress::
> > +       Progress status is reported on the standard error stream
> > +       by default when it is attached to a terminal, unless `--quiet`
> > +       is specified. This flag enables progress reporting even if not
> > +       attached to a terminal, regardless of `--quiet`.
>
> I'm assuming this means there are feedback messages other than
> progress feedback?

There could be. This is carried over from git-checkout. I suspect this
is about warnings that we print from time to time.

> > +-f::
> > +--force::
> > +       If `--source` is not specified, unmerged entries are left alone
> > +       and will not fail the operation. Unmerged entries are always
> > +       replaced if `--source` is specified, regardless of `--force`.
>
> This may be slightly confusing, in particular it suggests that --index
> (or --worktree and --index) are the default.  Is --force only useful
> when --index is specified?  If it has utility with --worktree only,
> what does it do?

Well, this is 'git checkout -f' behavior which only concerns the
index. So yeah it only matters with --index.

> Also, what happens when there are unmerged entries
> in the index and someone tries to restore just working tree files --
> are the ones corresponding to unmerged entries skipped (if so,
> silently or with warnings printed for the user?), or does something
> else happen?

If -m is also specified, then we recreate the conflict. The from code,
if an unmerged path is skipped, there will be warnings.

> > +
> > +-m::
> > +--merge::
> > +       Recreate the conflicted merge in the specified paths.
> > +
> > +--conflict=<style>::
> > +       The same as `--merge` option above, but changes the way the
> > +       conflicting hunks are presented, overriding the merge.conflictStyle
> > +       configuration variable.  Possible values are "merge" (default)
> > +       and "diff3" (in addition to what is shown by "merge" style,
> > +       shows the original contents).
>
> Should you mention that these are incompatible with --source and
> --index?  And perhaps also make sure the code aborts if either of
> these options are combined with either of those?

I will make sure that the code aborts. Not so sure about mentionging
every incompatible combination though. Will it be too much? I think we
catch and report plenty invalid combinations but I don't think we have
mentioned them all (or maybe we have, I didn't check the document
again)

> > +       Just like linkgit:git-submodule[1], this will detach the
> > +       submodules HEAD.
> > +
> > +--overlay::
> > +--no-overlay::
> > +       In overlay mode, `git checkout` never removes files from the
>
> Why are you talking about `git checkout` here?  Shouldn't this be `git restore`?

Oops.
-- 
Duy