blob: 3211841305fcb3cc9cce22bcd6c445cf327e274f [file] [log] [blame]
Jeff King21e46312011-10-21 13:28:04 -04001git-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
Taylor Blau240cf2a2018-06-22 10:49:54 -050028Or, 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
Jeff King21e46312011-10-21 13:28:04 -040035Obviously 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
Jeff King1af9c602016-07-22 12:35:19 -040039Git-jump can generate four types of interesting lists:
Jeff King21e46312011-10-21 13:28:04 -040040
41 1. The beginning of any diff hunks.
42
43 2. The beginning of any merge conflict markers.
44
Taylor Blau240cf2a2018-06-22 10:49:54 -050045 3. Any grep matches, including the column of the first match on a
46 line.
Jeff King21e46312011-10-21 13:28:04 -040047
Jeff King1af9c602016-07-22 12:35:19 -040048 4. Any whitespace errors detected by `git diff --check`.
49
Jeff King21e46312011-10-21 13:28:04 -040050
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
Jeff King67ba13e2021-11-09 11:35:47 -050068# documentation conflicts are hard; skip past them for now
69git jump merge :^Documentation
70
Jeff King21e46312011-10-21 13:28:04 -040071# jump to all instances of foo_bar
72git jump grep foo_bar
73
74# same as above, but case-insensitive; you can give
75# arbitrary grep options
76git jump grep -i foo_bar
Beat Bolli007d06a2017-11-20 00:05:36 +010077
78# use the silver searcher for git jump grep
79git config jump.grepCmd "ag --column"
Jeff King21e46312011-10-21 13:28:04 -040080--------------------------------------------------
81
Yoichi Nakayamacfb7b3b2022-11-27 01:18:51 +000082You can use the optional argument '--stdout' to print the listing to
83standard output instead of feeding it to the editor. You can use the
84argument with M-x grep on Emacs:
85
86--------------------------------------------------
87# In Emacs, M-x grep and invoke "git jump --stdout <mode>"
88M-x grep<RET>git jump --stdout diff<RET>
89--------------------------------------------------
Jeff King21e46312011-10-21 13:28:04 -040090
91Related Programs
92----------------
93
94You can accomplish some of the same things with individual tools. For
95example, you can use `git mergetool` to start vimdiff on each unmerged
96file. `git jump merge` is for the vim-wielding luddite who just wants to
97jump straight to the conflict text with no fanfare.
98
99As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option,
100which does something similar to `git jump grep`. However, it is limited
101to positioning the cursor to the correct line in only the first file,
102leaving you to locate subsequent hits in that file or other files using
103the editor or pager. By contrast, git-jump provides the editor with a
Taylor Blau240cf2a2018-06-22 10:49:54 -0500104complete list of files, lines, and a column number for each match.
Jeff King21e46312011-10-21 13:28:04 -0400105
106
107Limitations
108-----------
109
Jeff Kinga91e6922016-07-22 12:30:58 -0400110This script was written and tested with vim. Given that the quickfix
Yoichi Nakayamacfb7b3b2022-11-27 01:18:51 +0000111format is the same as what gcc produces, I expect other tools have a
Jeff King21e46312011-10-21 13:28:04 -0400112similar feature for iterating through the list, but I know nothing about
113how to activate it.
114
115The shell snippets to generate the quickfix lines will almost certainly
116choke on filenames with exotic characters (like newlines).
Jeff Kingf5da0772017-11-20 14:18:46 -0500117
118Contributing
119------------
120
121Bug fixes, bug reports, and feature requests should be discussed on the
122Git mailing list <git@vger.kernel.org>, and cc'd to the git-jump
123maintainer, Jeff King <peff@peff.net>.