sponsor Vim development Vim logo Vim Book Ad

vcs-jump : Jump to interesting places with a Git or Mercurial repo

 script karma  Rating 0/0, Downloaded by 483  Comments, bugs, improvements  Vim wiki

created by
Greg Hurrell
 
script type
utility
 
description
*vcs-jump.txt*                 vcs-jump plug-in for Vim                 *vcs-jump*

CONTENTS                                                     *vcs-jump-contents*

1. Intro             |vcs-jump-intro|
2. Requirements      |vcs-jump-requirements|
3. Installation      |vcs-jump-installation|
4. Usage             |vcs-jump-usage|
5. Commands          |vcs-jump-commands|
6. Mappings          |vcs-jump-mappings|
7. Options           |vcs-jump-options|
8. Website           |vcs-jump-website|
9. License           |vcs-jump-license|
10. Development      |vcs-jump-development|
11. Authors          |vcs-jump-authors|
12. History          |vcs-jump-history|

INTRO                                                           *vcs-jump-intro*

This plug-in allows you to jump to useful places within a Git or Mercurial
repository: diff hunks, merge conflicts, and "grep" results.

The actual work is done by the included `vcs-jump` script, which is a Ruby
port of the "git-jump" (shell) script from official Git repo, adapted to
work transparently with either Git or Mercurial:

https://git.kernel.org/pub/scm/git/git.git/tree/contrib/git-jump

REQUIREMENTS                                             *vcs-jump-requirements*

- A Ruby interpreter must be available on the host system: the `vcs-jump`
  script uses a "shebang" line of "/usr/bin/env ruby".

INSTALLATION                                             *vcs-jump-installation*

To install vcs-jump, use your plug-in management system of choice.

vcs-jump consists of a Vim plug-in that provides a |:VcsJump| command which
invokes a bundled `vcs-jump` executable. The executable itself is useful
outside of Vim, so you may wish to add the plug-in's `bin` directory to your
`$PATH`; for example, if you installed the plug-in inside
`~/.vim/pack/bundle/vcs-jump`, you could add the following to your shell's
startup file:
>
    export PATH=$PATH:~/.vim/pack/bundle/vcs-jump/bin
<
See |vcs-jump-usage| for a description of usage from the command-line.

USAGE                                                           *vcs-jump-usage*

vcs-jump can be used from inside or outside of Vim. Inside Vim, run |:VcsJump|
to populate the |quickfix| list with "interesting" locations (diff hunks,
merge conflicts, or grep results).

Outside of Vim, provided you have set up your `$PATH` as described in
|vcs-jump-installation|, you can run the bundled `vcs-jump` executable in any of
the following ways to open Vim and immediately populate the |quickfix| list:
>
    vcs-jump diff # find hunks with diffs relative to current HEAD
    vcs-jump diff HEAD~10 # find hunks with diffs relative to specified commit
    vcs-jump grep stuff # find grep results for "stuff"
    vcs-jump merge # find merge conflicts
<
COMMANDS                                                     *vcs-jump-commands*

                                                                      *:VcsJump*
:VcsJump  ~

This command invokes the bundled `vcs-jump` script to get the list of
"interesting" locations (diff hunks, merge conflicts, or grep results) in
the repo, and put them in the |quickfix| list.

Filename completion is available in the context of this command.

Subcommands are:

- "diff": Results are diff hunks. Arguments are passed on to the Mercurial
  or Git `diff` invocation. This means that in the absence of any arguments, a
  diff against the current "HEAD" will be performed, but you can change that
  by passing options (eg. `--cached`) or specifying a target revision to
  compare against.
- "merge": Results are merge conflicts. Arguments are ignored.
- "grep": Results are grep hits. Arguments are given to the underlying Git
  or Mercurial `grep` command.

When called with a trailing |:command-bang| (eg. `:VcsJump!`) the current value
of the |g:VcsJumpMode| setting is inverted for the duration of that invocation.

MAPPINGS                                                     *vcs-jump-mappings*


                                                               *<Plug>(VcsJump)*
This mapping invokes the bundled `vcs-jump` script, defaulting to "diff" mode.

By default, `<Leader>d` will invoke this mapping unless:

- A mapping with the same |{lhs}| already exists; or:
- An alternative mapping to |<Plug>(VcsJump)| has already been defined in your
  |.vimrc|.

You can create a different mapping like this:
>
    " Use <Leader>g instead of <Leader>d
    nmap <Leader>g <Plug>(VcsJump)
<
OPTIONS                                                       *vcs-jump-options*


                                                                 *g:VcsJumpMode*
|g:VcsJumpMode|                                          string (default: "cwd")

Controls whether vcs-jump should operate relative to Vim's current working
directory (when |g:VcsJumpMode| is "cwd", the default) or to the current
buffer (when |g:VcsJumpMode| is "buffer").

To override the default, add this to your |.vimrc|:
>
    let g:VcsJumpMode="buffer"
<
Note that you can temporarily invert the sense of this setting by running
|:VcsJump| with a trailing |:command-bang| (eg. `:VcsJump!`).


                                                               *g:VcsJumpLoaded*
|g:VcsJumpLoaded|                                            any (default: none)

To prevent vcs-jump from being loaded, set |g:VcsJumpLoaded| to any value in
your " |.vimrc|. For example:
>
    let g:VcsJumpLoaded=1
<
WEBSITE                                                       *vcs-jump-website*

The official vcs-jump source code repo is at:

http://git.wincent.com/vcs-jump.git

A mirror exists at:

https://github.com/wincent/vcs-jump

Official releases are listed at:

http://www.vim.org/scripts/script.php?script_id=5790

LICENSE                                                       *vcs-jump-license*

Copyright 2014-present Greg Hurrell. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

DEVELOPMENT                                               *vcs-jump-development*

Contributing patches ~

Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
at: https://github.com/wincent/vcs-jump/pulls

Cutting a new release ~

At the moment the release process is manual:

- Perform final sanity checks and manual testing
- Update the |vcs-jump-history| section of the documentation
- Verify clean work tree:
>
    git status
<
- Tag the release:
>
    git tag -s -m "$VERSION release" $VERSION
<
- Publish the code:
>
    git push origin master --follow-tags
    git push github master --follow-tags
<
- Produce the release archive:
>
    git archive -o vcs-jump-$VERSION.zip HEAD -- .
<
- Upload to http://www.vim.org/scripts/script.php?script_id=5790

AUTHORS                                                       *vcs-jump-authors*

vcs-jump is written and maintained by Greg Hurrell <greg@hurrell.net>.

Other contributors that have submitted patches include (in alphabetical
order):

- Pascal Lalancette

HISTORY                                                       *vcs-jump-history*

1.0 (12 October 2019) ~

- Provide a meaningful title for the |quickfix| listing.
- Run `git diff` with `--no-color` to prevent a `git config color.ui` setting of
  "always" from breaking diff mode
  (https://github.com/wincent/vcs-jump/issues/1)
- Add |g:VcsJumpMode| and teach |:VcsJump| to accept a |:command-bang| suffix that
  can be used to make vcs-jump operate relative to the current buffer
  instead of the current working directory (patch from Pascal Lalancette,
  https://github.com/wincent/vcs-jump/pull/5).

0.1 (2 June 2019) ~

- Initial release: originally extracted from my dotfiles in
  https://wincent.com/n/vcs-jump-origin and then iterated on before
  extracting into a standalone Vim plug-in.
 
install details
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vcs-jump-1.0.zip 1.0 2019-10-12 7.0 Greg Hurrell - Provide a meaningful title for the |quickfix| listing.
- Run `git diff` with `--no-color` to prevent a `git config color.ui` setting of "always" from breaking diff mode (https://github.com/wincent/vcs-jump/issues/1)
- Add |g:VcsJumpMode| and teach |:VcsJump| to accept a |:command-bang| suffix that can be used to make vcs-jump operate relative to the current buffer instead of the current working directory (patch from Pascal Lalancette, https://github.com/wincent/vcs-jump/pull/5).
vcs-jump-0.1.zip 0.1 2019-06-03 7.0 Greg Hurrell Initial upload
ip used for rating: 44.200.77.59

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
Vim at Github