contrib / git-jump / READMEon commit Merge branch 'rs/compat-strdup' into maint (815a73f)
   1git-jump
   2========
   3
   4Git-jump is a script for helping you jump to "interesting" parts of your
   5project in your editor. It works by outputting a set of interesting
   6spots in the "quickfix" format, which editors like vim can use as a
   7queue of places to visit (this feature is usually used to jump to errors
   8produced by a compiler). For example, given a diff like this:
   9
  10------------------------------------
  11diff --git a/foo.c b/foo.c
  12index 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
  22git-jump will feed this to the editor:
  23
  24-----------------------------------
  25foo.c:2: printf("hello word!\n");
  26-----------------------------------
  27
  28Obviously this trivial case isn't that interesting; you could just open
  29`foo.c` yourself. But when you have many changes scattered across a
  30project, you can use the editor's support to "jump" from point to point.
  31
  32Git-jump can generate four types of interesting lists:
  33
  34  1. The beginning of any diff hunks.
  35
  36  2. The beginning of any merge conflict markers.
  37
  38  3. Any grep matches.
  39
  40  4. Any whitespace errors detected by `git diff --check`.
  41
  42
  43Using git-jump
  44--------------
  45
  46To use it, just drop git-jump in your PATH, and then invoke it like
  47this:
  48
  49--------------------------------------------------
  50# jump to changes not yet staged for commit
  51git jump diff
  52
  53# jump to changes that are staged for commit; you can give
  54# arbitrary diff options
  55git jump diff --cached
  56
  57# jump to merge conflicts
  58git jump merge
  59
  60# jump to all instances of foo_bar
  61git jump grep foo_bar
  62
  63# same as above, but case-insensitive; you can give
  64# arbitrary grep options
  65git jump grep -i foo_bar
  66--------------------------------------------------
  67
  68
  69Related Programs
  70----------------
  71
  72You can accomplish some of the same things with individual tools. For
  73example, you can use `git mergetool` to start vimdiff on each unmerged
  74file. `git jump merge` is for the vim-wielding luddite who just wants to
  75jump straight to the conflict text with no fanfare.
  76
  77As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option,
  78which does something similar to `git jump grep`. However, it is limited
  79to positioning the cursor to the correct line in only the first file,
  80leaving you to locate subsequent hits in that file or other files using
  81the editor or pager. By contrast, git-jump provides the editor with a
  82complete list of files and line numbers for each match.
  83
  84
  85Limitations
  86-----------
  87
  88This script was written and tested with vim. Given that the quickfix
  89format is the same as what gcc produces, I expect emacs users have a
  90similar feature for iterating through the list, but I know nothing about
  91how to activate it.
  92
  93The shell snippets to generate the quickfix lines will almost certainly
  94choke on filenames with exotic characters (like newlines).