Re: [PATCH v1 01/11] checkout: split part of it to new command 'restore'
- Date: Sat, 9 Mar 2019 19:16:00 +0700
- From: Duy Nguyen <pclouds@xxxxxxxxx>
- Subject: Re: [PATCH v1 01/11] checkout: split part of it to new command 'restore'
On Sat, Mar 9, 2019 at 1:01 AM Elijah Newren <newren@xxxxxxxxx> 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@xxxxxxxxx> 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.
> > +--------
> > +[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?
> > +-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
> > + Just like linkgit:git-submodule, 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`?