contrib/git-jump/README

   1 git-jump
   2 ========
   3
   4 Git-jump is a script for helping you jump to "interesting" parts of your
   5 project in your editor. It works by outputting a set of interesting
   6 spots in the "quickfix" format, which editors like vim can use as a
   7 queue of places to visit (this feature is usually used to jump to errors
   8 produced by a compiler). For example, given a diff like this:
   9
  10 ------------------------------------
  11 diff --git a/foo.c b/foo.c
  12 index a655540..5a59044 100644
  13 --- a/foo.c
  14 +++ b/foo.c
  15 @@ -1,3 +1,3 @@
  16  int main(void) {
  17 -  printf("hello word!\n");
  18 +  printf("hello world!\n");
  19  }
  20 -----------------------------------
  21
  22 git-jump will feed this to the editor:
  23
  24 -----------------------------------
  25 foo.c:2: printf("hello word!\n");
  26 -----------------------------------
  27
  28 Or, when running 'git jump grep', column numbers will also be emitted,
  29 e.g. `git jump grep "hello"` would return:
  30
  31 -----------------------------------
  32 foo.c:2:9: printf("hello word!\n");
  33 -----------------------------------
  34
  35 Obviously this trivial case isn't that interesting; you could just open
  36 `foo.c` yourself. But when you have many changes scattered across a
  37 project, you can use the editor's support to "jump" from point to point.
  38
  39 Git-jump can generate four types of interesting lists:
  40
  41   1. The beginning of any diff hunks.
  42
  43   2. The beginning of any merge conflict markers.
  44
  45   3. Any grep matches, including the column of the first match on a
  46      line.
  47
  48   4. Any whitespace errors detected by `git diff --check`.
  49
  50
  51 Using git-jump
  52 --------------
  53
  54 To use it, just drop git-jump in your PATH, and then invoke it like
  55 this:
  56
  57 --------------------------------------------------
  58 # jump to changes not yet staged for commit
  59 git jump diff
  60
  61 # jump to changes that are staged for commit; you can give
  62 # arbitrary diff options
  63 git jump diff --cached
  64
  65 # jump to merge conflicts
  66 git jump merge
  67
  68 # documentation conflicts are hard; skip past them for now
  69 git jump merge :^Documentation
  70
  71 # jump to all instances of foo_bar
  72 git jump grep foo_bar
  73
  74 # same as above, but case-insensitive; you can give
  75 # arbitrary grep options
  76 git jump grep -i foo_bar
  77
  78 # use the silver searcher for git jump grep
  79 git config jump.grepCmd "ag --column"
  80 --------------------------------------------------
  81
  82 You can use the optional argument '--stdout' to print the listing to
  83 standard output instead of feeding it to the editor. You can use the
  84 argument with M-x grep on Emacs:
  85
  86 --------------------------------------------------
  87 # In Emacs, M-x grep and invoke "git jump --stdout <mode>"
  88 M-x grep<RET>git jump --stdout diff<RET>
  89 --------------------------------------------------
  90
  91 Related Programs
  92 ----------------
  93
  94 You can accomplish some of the same things with individual tools. For
  95 example, you can use `git mergetool` to start vimdiff on each unmerged
  96 file. `git jump merge` is for the vim-wielding luddite who just wants to
  97 jump straight to the conflict text with no fanfare.
  98
  99 As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option,
 100 which does something similar to `git jump grep`. However, it is limited
 101 to positioning the cursor to the correct line in only the first file,
 102 leaving you to locate subsequent hits in that file or other files using
 103 the editor or pager. By contrast, git-jump provides the editor with a
 104 complete list of files, lines, and a column number for each match.
 105
 106
 107 Limitations
 108 -----------
 109
 110 This script was written and tested with vim. Given that the quickfix
 111 format is the same as what gcc produces, I expect other tools have a
 112 similar feature for iterating through the list, but I know nothing about
 113 how to activate it.
 114
 115 The shell snippets to generate the quickfix lines will almost certainly
 116 choke on filenames with exotic characters (like newlines).
 117
 118 Contributing
 119 ------------
 120
 121 Bug fixes, bug reports, and feature requests should be discussed on the
 122 Git mailing list <git@vger.kernel.org>, and cc'd to the git-jump
 123 maintainer, Jeff King <peff@peff.net>.