More git files
[emacs.git] / .emacs.d / elisp / mo-git-blame / README
1 mo-git-blame -- An interactive, interative 'git blame' mode for Emacs
2
3 Copyright
4 ---------
5
6 Copyright (C) 2009 Moritz Bunkus <moritz@bunkus.org>
7
8 mo-git-blame is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 3, or (at your option)
11 any later version.
12
13 mo-git-blame is distributed in the hope that it will be useful, but
14 WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 General Public License for more details.
17
18 You should have received a copy of the GNU General Public License
19 along with GNU Emacs; see the file COPYING. If not, write to the Free
20 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
21 02111-1307, USA.
22
23 Installation
24 ------------
25
26 Put this file somewhere in your load-path or add the directory it
27 is in to it, e.g.:
28
29 (add-to-list 'load-path "~/.emacs.d/mo-git-blame")
30
31 Then add two autoload definitions:
32
33 (autoload 'mo-git-blame-file "mo-git-blame" nil t)
34 (autoload 'mo-git-blame-current "mo-git-blame" nil t)
35
36 Optionally bind keys to these functions, e.g.
37
38 (global-set-key [?\C-c ?g ?c] 'mo-git-blame-current)
39 (global-set-key [?\C-c ?g ?f] 'mo-git-blame-file)
40
41 Usage
42 -----
43
44 There are two ways to invoke it: `mo-git-blame-file' which lets you
45 select a file for which 'git blame' should be called and
46 `mo-git-blame-current' which does the same for the current buffer's
47 associated file.
48
49 Once the mode starts it splits the window vertically. The left one
50 is filled with the blame output while the right one is filled with the
51 content at the current revision. Syntax highlighting is enabled for
52 the content window. The content buffer's name will contain the file
53 name and the current revision.
54
55 mo-git-blame works with three different buffers:
56
57 1. the `blame' buffer which contains the output of `git blame' and
58 which is the main buffer from which actions can be invoked
59
60 2. the `content' buffer which shows the file content at the current
61 revision. This buffer has syntax highlighting turned on. Only a few
62 actions can be invoked from this buffer (e.g. `q' for exiting
63 mo-git-blame).
64
65 3. the `output' buffer which contains the output of several git
66 commands, e.g. 'git show' or 'git cat-file'.
67
68 Normally the `blame' and the `content' buffer are shown
69 side-by-side. If the user requests additional information then the
70 `output' buffer is shown instead of the `content' buffer. The user can
71 return to the `content' buffer with <TAB>.
72
73 You can invoke several actions from the blame buffer with single key
74 strokes. These include but are not limited to:
75
76 a -- Call 'git blame' for the file for the first ancestor of the
77 revision listed in the current line. Sets the content buffer to
78 contain the file content at the new revision.
79 A -- Call 'git blame' for the file for the first ancestor of the
80 current revision. Sets the content buffer to contain the file
81 content at the new revision.
82 b -- Call 'git blame' for the file for the revision listed in the
83 current line. Sets the content buffer to contain the file
84 content at the new revision.
85 B -- Call 'git blame' for the file for a specific revision read from
86 the minibuffer.
87 c -- Call 'git cat-file blob ...' for the revision listed in the
88 current line and show the output in the `output' buffer. The
89 output will not have syntax highlighting.
90 i -- Display the current state information (current revision, git
91 repository path etc) in the right window.
92 l -- Call 'git log' for the revision listed in the current line and
93 show the output in the `output' buffer.
94 L -- Call 'git log' for the current revision and show the output in
95 the `output' buffer.
96 p -- Call 'git blame' for the file for the revision that was shown
97 prior to the current one. Works only if you've used `b'
98 before.
99 o -- Overwrite the file with the content of the revision listed in
100 the current line. Asks for confirmation before actually
101 overwriting the file.
102 O -- Overwrite the file with the content of the current
103 revision. Asks for confirmation before actually overwriting the
104 file.
105 q -- Exit mo-git-blame and kill all its buffers.
106 s -- Call 'git show' for the revision listed in the current line and
107 show the output in the `output' buffer.
108 S -- Call 'git show' for the current revision and show the output in
109 the `output' buffer.
110 TAB -- Re-display the `content' buffer in the right window if it has
111 replaced with the `output' buffer.
112 RET -- Same as `s'.
113
114 Customizing
115 -----------
116
117 There are several variables that can be customized. They belong to the
118 group `mo-git-blame' and can be customized with
119
120 (customize-group 'mo-git-blame)
121
122 These variables include:
123
124 * `mo-git-blame-git-executable' defaults to `git' and should point to
125 your `git' executable if it is not in your path.
126 * `mo-git-blame-blame-window-width' defaults to 45 and determines the
127 initial width of the `blame' window.
128 * `mo-git-blame-use-ido' determines whether or not the `ido' package
129 is used for various interactive lookups.
130
131 Bugs, feature requests, contact
132 -------------------------------
133
134 You can reach me via email at Moritz Bunkus <moritz@bunkus.org>. I'm
135 always grateful for bug reports and usually open to feature
136 suggestions as far as my time permits.
137
138 You can also file an issue on github's issue tracker:
139
140 https://github.com/mbunkus/mo-git-blame/issues
141
142 Patches, source code
143 --------------------
144
145 The latest version can always be retrieved from my Git repository:
146
147 git clone git://github.com/mbunkus/mo-git-blame.git
148
149 If you want to send patches: Yes! By all means! Please do so! Please
150 note that I'm using wide windows and do not like forced wrapping
151 around 80 columns. I also don't like tabs. Thanks.