contrib: add git-jump script
[git/git.git] / 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 Obviously this trivial case isn't that interesting; you could just open
29 `foo.c` yourself. But when you have many changes scattered across a
30 project, you can use the editor's support to "jump" from point to point.
31
32 Git-jump can generate three 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
41 Using git-jump
42 --------------
43
44 To use it, just drop git-jump in your PATH, and then invoke it like
45 this:
46
47 --------------------------------------------------
48 # jump to changes not yet staged for commit
49 git jump diff
50
51 # jump to changes that are staged for commit; you can give
52 # arbitrary diff options
53 git jump diff --cached
54
55 # jump to merge conflicts
56 git jump merge
57
58 # jump to all instances of foo_bar
59 git jump grep foo_bar
60
61 # same as above, but case-insensitive; you can give
62 # arbitrary grep options
63 git jump grep -i foo_bar
64 --------------------------------------------------
65
66
67 Related Programs
68 ----------------
69
70 You can accomplish some of the same things with individual tools. For
71 example, you can use `git mergetool` to start vimdiff on each unmerged
72 file. `git jump merge` is for the vim-wielding luddite who just wants to
73 jump straight to the conflict text with no fanfare.
74
75 As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option,
76 which does something similar to `git jump grep`. However, it is limited
77 to positioning the cursor to the correct line in only the first file,
78 leaving you to locate subsequent hits in that file or other files using
79 the editor or pager. By contrast, git-jump provides the editor with a
80 complete list of files and line numbers for each match.
81
82
83 Limitations
84 -----------
85
86 This scripts was written and tested with vim. Given that the quickfix
87 format is the same as what gcc produces, I expect emacs users have a
88 similar feature for iterating through the list, but I know nothing about
89 how to activate it.
90
91 The shell snippets to generate the quickfix lines will almost certainly
92 choke on filenames with exotic characters (like newlines).