]>
Commit | Line | Data |
---|---|---|
21e4631c JK |
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 | ||
240cf2a2 TB |
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 | ||
21e4631c JK |
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 | ||
1af9c609 | 39 | Git-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 | |
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 | # jump to all instances of foo_bar | |
69 | git jump grep foo_bar | |
70 | ||
71 | # same as above, but case-insensitive; you can give | |
72 | # arbitrary grep options | |
73 | git jump grep -i foo_bar | |
007d06aa BB |
74 | |
75 | # use the silver searcher for git jump grep | |
76 | git config jump.grepCmd "ag --column" | |
21e4631c JK |
77 | -------------------------------------------------- |
78 | ||
79 | ||
80 | Related Programs | |
81 | ---------------- | |
82 | ||
83 | You can accomplish some of the same things with individual tools. For | |
84 | example, you can use `git mergetool` to start vimdiff on each unmerged | |
85 | file. `git jump merge` is for the vim-wielding luddite who just wants to | |
86 | jump straight to the conflict text with no fanfare. | |
87 | ||
88 | As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option, | |
89 | which does something similar to `git jump grep`. However, it is limited | |
90 | to positioning the cursor to the correct line in only the first file, | |
91 | leaving you to locate subsequent hits in that file or other files using | |
92 | the editor or pager. By contrast, git-jump provides the editor with a | |
240cf2a2 | 93 | complete list of files, lines, and a column number for each match. |
21e4631c JK |
94 | |
95 | ||
96 | Limitations | |
97 | ----------- | |
98 | ||
a91e6925 | 99 | This script was written and tested with vim. Given that the quickfix |
21e4631c JK |
100 | format is the same as what gcc produces, I expect emacs users have a |
101 | similar feature for iterating through the list, but I know nothing about | |
102 | how to activate it. | |
103 | ||
104 | The shell snippets to generate the quickfix lines will almost certainly | |
105 | choke on filenames with exotic characters (like newlines). | |
f5da077b JK |
106 | |
107 | Contributing | |
108 | ------------ | |
109 | ||
110 | Bug fixes, bug reports, and feature requests should be discussed on the | |
111 | Git mailing list <git@vger.kernel.org>, and cc'd to the git-jump | |
112 | maintainer, Jeff King <peff@peff.net>. |