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. 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
