Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 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 | |
Taylor Blau | 240cf2a | 2018-06-22 10:49:54 -0500 | [diff] [blame] | 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 | |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 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 | |
Jeff King | 1af9c60 | 2016-07-22 12:35:19 -0400 | [diff] [blame] | 39 | Git-jump can generate four types of interesting lists: |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 40 | |
| 41 | 1. The beginning of any diff hunks. |
| 42 | |
| 43 | 2. The beginning of any merge conflict markers. |
| 44 | |
Taylor Blau | 240cf2a | 2018-06-22 10:49:54 -0500 | [diff] [blame] | 45 | 3. Any grep matches, including the column of the first match on a |
| 46 | line. |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 47 | |
Jeff King | 1af9c60 | 2016-07-22 12:35:19 -0400 | [diff] [blame] | 48 | 4. Any whitespace errors detected by `git diff --check`. |
| 49 | |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 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 | |
Jeff King | 67ba13e | 2021-11-09 11:35:47 -0500 | [diff] [blame] | 68 | # documentation conflicts are hard; skip past them for now |
| 69 | git jump merge :^Documentation |
| 70 | |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 71 | # jump to all instances of foo_bar |
| 72 | git jump grep foo_bar |
| 73 | |
| 74 | # same as above, but case-insensitive; you can give |
| 75 | # arbitrary grep options |
| 76 | git jump grep -i foo_bar |
Beat Bolli | 007d06a | 2017-11-20 00:05:36 +0100 | [diff] [blame] | 77 | |
| 78 | # use the silver searcher for git jump grep |
| 79 | git config jump.grepCmd "ag --column" |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 80 | -------------------------------------------------- |
| 81 | |
| 82 | |
| 83 | Related Programs |
| 84 | ---------------- |
| 85 | |
| 86 | You can accomplish some of the same things with individual tools. For |
| 87 | example, you can use `git mergetool` to start vimdiff on each unmerged |
| 88 | file. `git jump merge` is for the vim-wielding luddite who just wants to |
| 89 | jump straight to the conflict text with no fanfare. |
| 90 | |
| 91 | As of git v1.7.2, `git grep` knows the `--open-files-in-pager` option, |
| 92 | which does something similar to `git jump grep`. However, it is limited |
| 93 | to positioning the cursor to the correct line in only the first file, |
| 94 | leaving you to locate subsequent hits in that file or other files using |
| 95 | the editor or pager. By contrast, git-jump provides the editor with a |
Taylor Blau | 240cf2a | 2018-06-22 10:49:54 -0500 | [diff] [blame] | 96 | complete list of files, lines, and a column number for each match. |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 97 | |
| 98 | |
| 99 | Limitations |
| 100 | ----------- |
| 101 | |
Jeff King | a91e692 | 2016-07-22 12:30:58 -0400 | [diff] [blame] | 102 | This script was written and tested with vim. Given that the quickfix |
Jeff King | 21e4631 | 2011-10-21 13:28:04 -0400 | [diff] [blame] | 103 | format is the same as what gcc produces, I expect emacs users have a |
| 104 | similar feature for iterating through the list, but I know nothing about |
| 105 | how to activate it. |
| 106 | |
| 107 | The shell snippets to generate the quickfix lines will almost certainly |
| 108 | choke on filenames with exotic characters (like newlines). |
Jeff King | f5da077 | 2017-11-20 14:18:46 -0500 | [diff] [blame] | 109 | |
| 110 | Contributing |
| 111 | ------------ |
| 112 | |
| 113 | Bug fixes, bug reports, and feature requests should be discussed on the |
| 114 | Git mailing list <git@vger.kernel.org>, and cc'd to the git-jump |
| 115 | maintainer, Jeff King <peff@peff.net>. |