rebase: teach rebase --keep-base
[git/git.git] / contrib / git-jump / README
CommitLineData
21e4631c
JK
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
240cf2a2
TB
28Or, when running 'git jump grep', column numbers will also be emitted,
29e.g. `git jump grep "hello"` would return:
30
31-----------------------------------
32foo.c:2:9: printf("hello word!\n");
33-----------------------------------
34
21e4631c
JK
35Obviously this trivial case isn't that interesting; you could just open
36`foo.c` yourself. But when you have many changes scattered across a
37project, you can use the editor's support to "jump" from point to point.
38
1af9c609 39Git-jump can generate four types of interesting lists:
21e4631c
JK
40
41 1. The beginning of any diff hunks.
42
43 2. The beginning of any merge conflict markers.
44
240cf2a2
TB
45 3. Any grep matches, including the column of the first match on a
46 line.
21e4631c 47
1af9c609
JK
48 4. Any whitespace errors detected by `git diff --check`.
49
21e4631c
JK
50
51Using git-jump
52--------------
53
54To use it, just drop git-jump in your PATH, and then invoke it like
55this:
56
57--------------------------------------------------
58# jump to changes not yet staged for commit
59git jump diff
60
61# jump to changes that are staged for commit; you can give
62# arbitrary diff options
63git jump diff --cached
64
65# jump to merge conflicts
66git jump merge
67
68# jump to all instances of foo_bar
69git jump grep foo_bar
70
71# same as above, but case-insensitive; you can give
72# arbitrary grep options
73git jump grep -i foo_bar
007d06aa
BB
74
75# use the silver searcher for git jump grep
76git config jump.grepCmd "ag --column"
21e4631c
JK
77--------------------------------------------------
78
79
80Related Programs
81----------------
82
83You can accomplish some of the same things with individual tools. For
84example, you can use `git mergetool` to start vimdiff on each unmerged
85file. `git jump merge` is for the vim-wielding luddite who just wants to
86jump straight to the conflict text with no fanfare.
87
88As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option,
89which does something similar to `git jump grep`. However, it is limited
90to positioning the cursor to the correct line in only the first file,
91leaving you to locate subsequent hits in that file or other files using
92the editor or pager. By contrast, git-jump provides the editor with a
240cf2a2 93complete list of files, lines, and a column number for each match.
21e4631c
JK
94
95
96Limitations
97-----------
98
a91e6925 99This script was written and tested with vim. Given that the quickfix
21e4631c
JK
100format is the same as what gcc produces, I expect emacs users have a
101similar feature for iterating through the list, but I know nothing about
102how to activate it.
103
104The shell snippets to generate the quickfix lines will almost certainly
105choke on filenames with exotic characters (like newlines).
f5da077b
JK
106
107Contributing
108------------
109
110Bug fixes, bug reports, and feature requests should be discussed on the
111Git mailing list <git@vger.kernel.org>, and cc'd to the git-jump
112maintainer, Jeff King <peff@peff.net>.