[PATCH v6] difftool.c: learn a new way start at specified file

From: ZheNing Hu <adlternative@gmail.com>

`git difftool` only allow us to select file to view in turn. If there is a commit with many files and we exit in the middle, we will have to traverse list again to get the file diff which we want to see. Therefore,teach the command an option `--skip-to=<path>` to allow the user to say that diffs for earlier paths are not interesting (because they were already seen in an earlier session) and start this session with the named path.

Signed-off-by: ZheNing Hu <adlternative@gmail.com>
---
    difftool.c: learn a new way start at specified file
    
     * The patch of the previous version implemented the jump through
       environment variables. The current version is based on the "diff
       --skip-to=" feature implemented by gitster, which implements a
       possible solution for the jump of difftool.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-870%2Fadlternative%2Fdifftool_save_point-v6
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-870/adlternative/difftool_save_point-v6
Pull-Request: https://github.com/gitgitgadget/git/pull/870

Range-diff vs v5:

 1:  fb4bfd0f8b16 < -:  ------------ diff: --{rotate,skip}-to=<path>
 2:  98e2707ee2fa ! 1:  4377a917ca9e difftool.c: learn a new way start at specified file
     @@ Commit message
          difftool.c: learn a new way start at specified file
      
          `git difftool` only allow us to select file to view in turn.
     -    If there is a commit with many files and we exit in the search,
     -    We will have to traverse list again to get the file diff which
     -    we want to see. Therefore, here is a new method: user can use
     -    `git difftool --rotate-to=<filename>` or `git difftool --skip-to=<filename>`
     -    to start viewing from the specified file, This will improve the
     -    user experience.
     -
     -    `git difftool --rotate-to=<file>` or `git difftool --skip-to=<filename>`
     -    will pass the path to `diffcore-rotate`, and diff-core will
     -    adjust the order of files, make the specified file sorted to
     -    the first.`git difftool --rotate-to=<file>` will move files before
     -    the  specified path to the last output, and
     -    `git difftool --skip-to=<filename>`  will ignore these files output.
     -    It is an error when there is no patch for specified file is shown.
     +    If there is a commit with many files and we exit in the middle,
     +    we will have to traverse list again to get the file diff which
     +    we want to see. Therefore,teach the command an option
     +    `--skip-to=<path>` to allow the user to say that diffs for earlier
     +    paths are not interesting (because they were already seen in an
     +    earlier session) and start this session with the named path.
      
          Signed-off-by: ZheNing Hu <adlternative@gmail.com>
      
     - ## Documentation/diff-options.txt ##
     -@@ Documentation/diff-options.txt: components matches the pattern.  For example, the pattern "`foo*bar`"
     - matches "`fooasdfbar`" and "`foo/bar/baz/asdf`" but not "`foobarx`".
     - 
     - --skip-to=<file>::
     ----rotate-to=<file::
     -+--rotate-to=<file>::
     - 	Discard the files before the named <file> from the output
     - 	(i.e. 'skip to'), or move them to the end of the output
     - 	(i.e. 'rotate to').  These were invented primarily for use
     -
       ## Documentation/git-difftool.txt ##
      @@ Documentation/git-difftool.txt: OPTIONS
       	This is the default behaviour; the option is provided to
       	override any configuration settings.
       
      +--rotate-to=<file>::
     -+	Internally call `git diff --rotate-to=<file>`,
     -+	show the change in the specified path first.
     -+	Files before the specified path will be moved to the last output.
     ++	Start showing the diff for the given path,
     ++	the paths before it will move to end and output.
      +
      +--skip-to=<file>::
     -+	Internally call `git diff --skip-to=<file>`,
     -+	skip the output to the specified path.
     -+	Files before the specified path will not output.
     ++	Start showing the diff for the given path, skipping all
     ++	the paths before it.
      +
       -t <tool>::
       --tool=<tool>::
     @@ t/t7800-difftool.sh: test_expect_success 'difftool --gui, --tool and --extcmd ar
      +	4
      +	1
      +	EOF
     -+	test_cmp output expect &&
     -+	test_must_fail git difftool --no-prompt --extcmd=cat --rotate-to="3" HEAD^
     ++	test_cmp output expect
      +'
      +
      +test_expect_success 'difftool --skip-to' '
     @@ t/t7800-difftool.sh: test_expect_success 'difftool --gui, --tool and --extcmd ar
      +	2
      +	4
      +	EOF
     -+	test_cmp output expect &&
     -+	test_must_fail git difftool --no-prompt --extcmd=cat --skip-to="3" HEAD^
     ++	test_cmp output expect
      +'
      +
     ++test_expect_success 'difftool --rotate/skip-to error condition' '
     ++	test_must_fail git difftool --no-prompt --extcmd=cat --rotate-to="3" HEAD^ &&
     ++	test_must_fail git difftool --no-prompt --extcmd=cat --skip-to="3" HEAD^
     ++'
       test_done

 Documentation/git-difftool.txt |  8 ++++++++
 t/t7800-difftool.sh            | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)