Skip to content
Newer
Older
100644 598 lines (458 sloc) 23.8 KB
343382c Added empty manual.
Marius Vollmer authored
1 \input texinfo.tex @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename magit.info
4 @settitle Magit User Manual
5 @c %**end of header
6
7 @dircategory Emacs
8 @direntry
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
9 * Magit: (magit). Using Git from Emacs with Magit.
343382c Added empty manual.
Marius Vollmer authored
10 @end direntry
11
12 @copying
3c6088e @mvollmer Manual updates.
mvollmer authored
13 Copyright @copyright{} 2008, 2009 Marius Vollmer
343382c Added empty manual.
Marius Vollmer authored
14
15 @quotation
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.2 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
ff21f5a Some content for the manual.
Marius Vollmer authored
20 Texts.
343382c Added empty manual.
Marius Vollmer authored
21 @end quotation
22 @end copying
23
24 @node Top
ff21f5a Some content for the manual.
Marius Vollmer authored
25 @top Magit User Manual
343382c Added empty manual.
Marius Vollmer authored
26
62b5fd8 Doc updates.
Marius Vollmer authored
27 Magit is an interface to the version control system Git, implemented
28 as an extension to Emacs.
343382c Added empty manual.
Marius Vollmer authored
29
30 @menu
31 * Introduction::
ea626db Fix two bugs from introducing the item abstraction.
Marius Vollmer authored
32 * Acknowledgments::
59bd8ec @mvollmer Use the digits to hide and show sections.
mvollmer authored
33 * Sections::
62643f9 Chapter renamings.
Marius Vollmer authored
34 * Status::
b64c4eb Texinfo menu fixes.
Marius Vollmer authored
35 * Untracked files::
c8cdc5e Manual updates.
Marius Vollmer authored
36 * Staging and Committing::
62643f9 Chapter renamings.
Marius Vollmer authored
37 * History::
c8cdc5e Manual updates.
Marius Vollmer authored
38 * Reflogs::
a21e998 Manual fixes.
Marius Vollmer authored
39 * Diffing::
157bee4 @mvollmer Even more control for pushing.
mvollmer authored
40 * Tagging::
e8cc5fd Updated manual menus.
Marius Vollmer authored
41 * Resetting::
7ac76de @mvollmer Stashing.
mvollmer authored
42 * Stashing::
a21e998 Manual fixes.
Marius Vollmer authored
43 * Branching::
3c6088e @mvollmer Manual updates.
mvollmer authored
44 * Wazzup::
a21e998 Manual fixes.
Marius Vollmer authored
45 * Merging::
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
46 * Rebasing::
2733ae2 Document rewriting.
Marius Vollmer authored
47 * Rewriting::
ff21f5a Some content for the manual.
Marius Vollmer authored
48 * Pushing and Pulling::
fe7ffeb Add keybindings for git-svn commands.
Alex Ott authored
49 * Interfacing with Subversion::
343382c Added empty manual.
Marius Vollmer authored
50 @end menu
51
52 @node Introduction
53 @chapter Introduction
ff21f5a Some content for the manual.
Marius Vollmer authored
54
a0df957 Manual updates.
Marius Vollmer authored
55 With Magit, you can inspect and modify your Git repositories with
56 Emacs. You can review and commit the changes you have made to the
57 tracked files, for example, and you can browse the history of past
58 changes. There is support for cherry picking, reverting, merging,
c8cdc5e Manual updates.
Marius Vollmer authored
59 rebasing, and other common Git operations.
ff21f5a Some content for the manual.
Marius Vollmer authored
60
1017a27 Updated manual.
Marius Vollmer authored
61 Magit is not a complete interface to Git; it just aims to make the
62 most common Git operations convenient. Thus, Magit will likely not
63 save you from learning Git itself.
ff21f5a Some content for the manual.
Marius Vollmer authored
64
636c676 Manual improvements.
Marius Vollmer authored
65 This manual provides a tour of all Magit features. It does not give a
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
66 introduction to version control in general, or to Git in particular.
ff21f5a Some content for the manual.
Marius Vollmer authored
67
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
68 The main entry point to Magit is @kbd{M-x magit-status}, which will
69 put you in Magit's status buffer. You will be using it frequently, so
ff21f5a Some content for the manual.
Marius Vollmer authored
70 it is probably a good idea to bind @code{magit-status} to a key of
71 your choice.
72
6538ce4 Manual improvements and updates.
Marius Vollmer authored
73 In addition to the status buffer, Magit will also create buffers that
74 show lists of commits, buffers with diffs, and other kinds of buffers.
75 All these buffers are in @code{magit-mode} and have the same key
76 bindings. Not all commands make sense in all contexts, but a given
c8cdc5e Manual updates.
Marius Vollmer authored
77 key will always do the same thing in all Magit buffers.
6538ce4 Manual improvements and updates.
Marius Vollmer authored
78
a0df957 Manual updates.
Marius Vollmer authored
79 Naturally, Magit runs the @code{git} command to do most of the work.
80 The @code{*magit-process*} buffer contains the transcript of the most
81 recent command. You can switch to it with @kbd{$}.
82
e110ed0 Acknowledgements.
Marius Vollmer authored
83 @node Acknowledgments
84 @chapter Acknowledgments
85
743987a @mvollmer Update acknowledgements.
mvollmer authored
86 From day one of the first Magit announcement, John Wiegley has
87 contributed numerous fixes, UI improvements, and new features.
88 Thanks!
89
90 Linh Dang and Christian Neukirchen also contributed from day one.
91 Thanks!
e110ed0 Acknowledgements.
Marius Vollmer authored
92
a93f24b Acknowledge Phil.
Marius Vollmer authored
93 Phil Hagelberg joined a few days later. Thanks!
94
b45a99c @mvollmer Acknowledge Alex Ott for git svn support.
mvollmer authored
95 Alex Ott contributed support for git svn. Thanks!
96
d5aa6d7 @mvollmer Thanks!
mvollmer authored
97 Marcin Bachry contributed bug fixes and support for decorated logs.
98 Thanks!
99
743987a @mvollmer Update acknowledgements.
mvollmer authored
100 Alexey Voinov fixed bugs. Thanks!
101
59bd8ec @mvollmer Use the digits to hide and show sections.
mvollmer authored
102 @node Sections
103 @chapter Sections
104
105 All Magit buffers are structured into nested 'sections'. These
106 sections can be hidden and shown individually. When a section is
107 hidden, only its first line is shown and all its children are
108 completely invisible.
109
110 The most fine-grained way to control the visibility of sections is the
111 @kbd{TAB} key. It will to toggle the current section (the section
112 that contains point) between being hidden and being shown.
113
114 Typing @kbd{S-TAB} toggles the visibility of the children of the
115 current section. When all of them are shown, they will all be hidden.
116 Otherwise, when some or all are hidden, they will all be shown.
117
118 The digit keys @kbd{1}, @kbd{2}, @kbd{3}, and @kbd{4} control the
119 visibility of sections based on levels. Hitting @kbd{2}, for example,
120 will show sections on levels one and two, and will hide sections on
121 level 3. However, only sections that are a parent or child of the
122 current section are affected.
123
124 For example, when the current section is on level 3 and you hit
125 @kbd{1}, the grand-parent of the current section (which is on level
45c6d95 @mvollmer Document M-s, M-S, M-h, and M-H.
mvollmer authored
126 one) will be shown, and the parent of the current section (level 2)
127 will be hidden. The visibility of no other section will be changed.
59bd8ec @mvollmer Use the digits to hide and show sections.
mvollmer authored
128
129 This sounds a bit complicated, but you'll figure it out.
130
131 Using @kbd{M-1}, @kbd{M-2}, @kbd{M-3}, and @kbd{M-4} is similar to the
132 unmodified digits, but now all sections on the respective level are
45c6d95 @mvollmer Document M-s, M-S, M-h, and M-H.
mvollmer authored
133 affected, regardless of whether or not they are related to the current
59bd8ec @mvollmer Use the digits to hide and show sections.
mvollmer authored
134 section.
135
136 For example, @kbd{M-1} will only show the first lines of the top-level
137 sections and will hide everything else. Typing @kbd{M-4} on the other
45c6d95 @mvollmer Document M-s, M-S, M-h, and M-H.
mvollmer authored
138 hand will show everything.
139
140 Because of the way the status buffer is set up, some changes to
141 section visibility are more common than others. Files are on level 2
142 and diff hunks are on level 4. Thus, you can type @kbd{2} to collapse
143 the diff of the current file, and @kbd{M-2} to collapse all files.
144 This returns the status buffer to its default setup and is a quick way
145 to unclutter it after drilling down into the modified files.
146
5c3ac91 @mvollmer Documentation updates.
mvollmer authored
147 Because @kbd{2} and @kbd{M-2} are so common in the status buffer, they
148 are bound to additional, more mnemonic keys: @kbd{M-h} (hide) and
149 @kbd{M-H} (hide all). Likewise @kbd{4} and @kbd{M-4} are also
150 available as @kbd{M-s} (show) and @kbd{M-S} (show all).
45c6d95 @mvollmer Document M-s, M-S, M-h, and M-H.
mvollmer authored
151
5c3ac91 @mvollmer Documentation updates.
mvollmer authored
152 In other buffers than the status buffer, @kbd{M-h}, @kbd{M-H},
153 @kbd{M-s}, and @kbd{M-S} might work on different levels than on 2 and
154 4, but they keep their general meaning: @kbd{M-H} hides all detail,
155 and @kbd{M-S} shows everything.
59bd8ec @mvollmer Use the digits to hide and show sections.
mvollmer authored
156
62643f9 Chapter renamings.
Marius Vollmer authored
157 @node Status
158 @chapter Status
ff21f5a Some content for the manual.
Marius Vollmer authored
159
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
160 Running @kbd{M-x magit-status} displays the main interface of Magit,
59aac28 Updated manual and TODO.
Marius Vollmer authored
161 the status buffer. You can have multiple status buffers active at the
162 same time, each associated with its own Git repository.
636c676 Manual improvements.
Marius Vollmer authored
163
2904e79 @mvollmer Make magit-status prompt less.
mvollmer authored
164 When invoking @kbd{M-x magit-status} from within a Git repository, it
165 will switch to the status buffer of that repository. Otherwise, it
e6167b8 @mvollmer Document that magit-status can create new Git repos.
mvollmer authored
166 will prompt for a directory. With a prefix argument, it will always
2904e79 @mvollmer Make magit-status prompt less.
mvollmer authored
167 prompt.
168
e6167b8 @mvollmer Document that magit-status can create new Git repos.
mvollmer authored
169 If you specify a directory that is not a Git repository, @kbd{M-x
170 magit-status} will ask whether to create one.
171
636c676 Manual improvements.
Marius Vollmer authored
172 You need to explicitly refresh the status buffer when you have made
173 changes to the repository from outside of Emacs. You can type @kbd{g}
174 in the status buffer itself, or just use @kbd{M-x magit-status}
175 instead of @kbd{C-x b} when switching to it. You also need to refresh
176 the status buffer in this way after saving a file in Emacs.
177
178 The header at the top of the status buffer shows a short summary of
179 the repository state: where it is located, which branch is checked
c8cdc5e Manual updates.
Marius Vollmer authored
180 out, etc. Below the header are a number of sections that show details
59bd8ec @mvollmer Use the digits to hide and show sections.
mvollmer authored
181 about the working tree and the staging area. You can hide and show
182 them as described in the previous section.
8a96fa0 Different hide/show behavior.
Marius Vollmer authored
183
138ac10 The "Untracked files" section is back, with better ignoring.
Marius Vollmer authored
184 The first section shows @emph{Untracked files}, if there are any. See
185 @ref{Untracked files} for more details.
1017a27 Updated manual.
Marius Vollmer authored
186
187 Two section show your local changes. They are explained fully in the
188 next chapter, @ref{Staging and Committing}.
189
190 If the current branch is associated with a remote tracking branch, the
191 status buffer shows the differences between the current branch and the
192 tracking branch. See @ref{Pushing and Pulling} for more information.
c8cdc5e Manual updates.
Marius Vollmer authored
193
e5d349a Mention 's' for adding untracked files.
Marius Vollmer authored
194 During a history rewriting session, the status buffer shows the
195 @emph{Pending changes} and @emph{Pending commits} sections. See
196 @ref{Rewriting} for more details.
197
138ac10 The "Untracked files" section is back, with better ignoring.
Marius Vollmer authored
198 @node Untracked files
199 @chapter Untracked files
200
53f4c6e Fixlet in manual.
Marius Vollmer authored
201 Untracked files are shown in the @emph{Untracked files} section.
138ac10 The "Untracked files" section is back, with better ignoring.
Marius Vollmer authored
202
e5d349a Mention 's' for adding untracked files.
Marius Vollmer authored
203 You can add a untracked file to the staging area with @kbd{s}.
204
138ac10 The "Untracked files" section is back, with better ignoring.
Marius Vollmer authored
205 You can instruct Git to ignore them by typing @kbd{i}. This will add
206 the filename to the @code{.gitignore} file. Typing @kbd{C-u i} will
207 ask you for the name of the file to ignore. This is useful to ignore
208 whole directories, for example. The @kbd{I} command is similar to
209 @kbd{i} but will add the file to @code{.git/info/exclude} instead.
210
1b4094e @mvollmer Removed binding for 'K', run git clean when hitting 'k' on the sectio…
mvollmer authored
211 To delete a untracked file forever, use @kbd{k}. If point is one the
212 @emph{Untracked files} section title when you it @kbd{k}, all
213 untracked files are deleted.
138ac10 The "Untracked files" section is back, with better ignoring.
Marius Vollmer authored
214
c8cdc5e Manual updates.
Marius Vollmer authored
215 @node Staging and Committing
216 @chapter Staging and Committing
217
e5d349a Mention 's' for adding untracked files.
Marius Vollmer authored
218 Comitting with Git is a two step process: first you add the changes
219 you want to commit to a 'staging area', and then you commit them to
220 the repository. This allows you to only commit a subset of your local
221 changes.
c8cdc5e Manual updates.
Marius Vollmer authored
222
223 Magit allows you to ignore the staging area if you wish. As long as
224 your staging area is unused, Magit will show your uncomitted changes
225 in a section named @emph{Changes}.
226
227 When the staging area is in use, Magit uses two sections:
228 @emph{Unstaged changes} and @emph{Staged changes}. The @emph{Staged
229 changes} section shows the changes that will be included in the next
230 commit, while the @emph{Unstaged changes} section shows the changes
231 that will be left out.
ff21f5a Some content for the manual.
Marius Vollmer authored
232
c8cdc5e Manual updates.
Marius Vollmer authored
233 To move a unstaged hunk into the staging area, move point into the
234 hunk and type @kbd{s}. Likewise, to unstage a hunk, move point into
235 it and type @kbd{u}. If point is in a diff header when you type
236 @kbd{s} or @kbd{u}, all hunks belonging to that diff are moved at the
14004f4 Stage/unstage, etc individual lines.
Marius Vollmer authored
237 same time.
238
239 If the region is active when you type @kbd{s} or @kbd{u}, only the
240 changes in the region are staged or unstaged. (This works line by
241 line: if the beginning of a line is in the region it is included in
242 the changes, otherwise it is not.)
243
244 To move all hunks of all diffs into the staging area in one go, type
245 @kbd{S}. To unstage everything, type @kbd{U}.
246
247 You can discard uncommitted changes by moving point into a hunk and
248 typing @kbd{k}. The changes to discard are selected as with @kbd{s}
249 and @kbd{u}.
ff21f5a Some content for the manual.
Marius Vollmer authored
250
c8cdc5e Manual updates.
Marius Vollmer authored
251 Before committing, you should write a short description of the
252 changes.
ff21f5a Some content for the manual.
Marius Vollmer authored
253
254 Type @kbd{c} to pop up a buffer where you can write your change
255 description. Once you are happy with the description, type @kbd{C-c
5c3ac91 @mvollmer Documentation updates.
mvollmer authored
256 C-c} in that buffer to perform the commit.
257
258 Typing @kbd{c} when the staging area is unused is a special situation.
259 Normally, the next commit would be empty, but you can configure Magit
260 to do something more useful by customizing the
261 @code{magit-commit-all-when-nothing-staged} variable. One choice is
262 to instruct the subsequent @kbd{C-c C-c} to commit all changes.
263 Another choice is stage everything at the time of hitting @kbd{c}.
c8cdc5e Manual updates.
Marius Vollmer authored
264
265 You can type @kbd{C-c C-a} in the buffer with the change description
27d53bd @mvollmer Document new behavior of 'c'.
mvollmer authored
266 to toggle a flag that determines whether the next commit will
267 @emph{amending} the current commit in HEAD.
ff21f5a Some content for the manual.
Marius Vollmer authored
268
67a0c1a @mvollmer Document C-c C-k in the *magit-log-edit* buffer.
mvollmer authored
269 If you change your mind and don't want to go ahead with your commit
270 while you are in the @code{*magit-log-edit*} buffer, you can just
271 switch to another buffer, continue editing there, staging and
272 unstaging things until you are happy, and then return to the
273 @code{*magit-log-edit*} buffer, maybe via @kbd{C-x b}, or by hitting
274 @kbd{c} again in a Magit buffer.
275
276 If you want to erase the @code{*magit-log-edit*} buffer and bury it,
277 you can hit @kbd{C-c C-k} in it.
278
6538ce4 Manual improvements and updates.
Marius Vollmer authored
279 Typing @kbd{C} will also pop up the change description buffer, but in
280 addition, it will try to insert a ChangeLog-style entry for the change
281 that point is in.
ff21f5a Some content for the manual.
Marius Vollmer authored
282
62643f9 Chapter renamings.
Marius Vollmer authored
283 @node History
284 @chapter History
ff21f5a Some content for the manual.
Marius Vollmer authored
285
6538ce4 Manual improvements and updates.
Marius Vollmer authored
286 To show the repository history of your current head, type @kbd{l}. A
287 new buffer will be shown that displays the history in a terse form.
ff21f5a Some content for the manual.
Marius Vollmer authored
288 The first paragraph of each commit message is displayed, next to a
289 representation of the relationships between commits.
290
3c6088e @mvollmer Manual updates.
mvollmer authored
291 Giving a prefix argument to @kbd{l} will ask for the starting and end
292 point of the history. This can be used to show the commits that are
293 in one branch, but not in another, for example.
294
295 Typing @kbd{L} (or @kbd{C-u L}) will show the log in a more verbose
296 form.
6538ce4 Manual improvements and updates.
Marius Vollmer authored
297
ff21f5a Some content for the manual.
Marius Vollmer authored
298 You can move point to a commit and then cause various things to happen
6538ce4 Manual improvements and updates.
Marius Vollmer authored
299 with it. (The following commands work in any list of commit, such as
300 the one shown in the @emph{Unpushed commits} section.)
ff21f5a Some content for the manual.
Marius Vollmer authored
301
c8cdc5e Manual updates.
Marius Vollmer authored
302 Typing @kbd{RET} will pop up more information about the current commit
303 and move point into the new buffer. Typing @kbd{SPC} and @kbd{DEL}
304 will also show the information, but will scroll the new buffer up or
3c6088e @mvollmer Manual updates.
mvollmer authored
305 down (respectively) when typed again.
ff21f5a Some content for the manual.
Marius Vollmer authored
306
c8cdc5e Manual updates.
Marius Vollmer authored
307 Typing @kbd{a} will apply the current commit to your current branch.
308 This is useful when you are browsing the history of some other branch
309 and you want to `cherry-pick' some changes from it. A typical
310 situation is applying selected bug fixes from the development version
311 of a program to a release branch. The cherry-picked changes will not
312 be committed automatically; you need to do that explicitly.
313
314 Typing @kbd{A} will cherry-pick the current commit and will also
315 commit the changes automatically when there have not been any
316 conflicts.
ff21f5a Some content for the manual.
Marius Vollmer authored
317
6538ce4 Manual improvements and updates.
Marius Vollmer authored
318 Typing @kbd{v} will revert the current commit. Thus, it will apply
319 the changes made by that commit in reverse. This is obviously useful
c8cdc5e Manual updates.
Marius Vollmer authored
320 to cleanly undo changes that turned out to be wrong. As with @kbd{a},
321 you need to commit the changes explicitly.
ff21f5a Some content for the manual.
Marius Vollmer authored
322
2c45b73 @mbachry Added `magit-copy-item-as-kill' command.
mbachry authored
323 Typing @kbd{C-w} will copy the sha1 of the current commit into the
324 kill ring.
325
6538ce4 Manual improvements and updates.
Marius Vollmer authored
326 Typing @kbd{=} will show the differences from the current commit to
327 the @dfn{marked} commit.
ff21f5a Some content for the manual.
Marius Vollmer authored
328
c691bc7 @voins Allow unmarking the marked commit.
voins authored
329 You can mark the current commit by typing @kbd{.}. When the current
330 commit is already marked, typing @kbd{.} will unmark it. To unmark
3c6088e @mvollmer Manual updates.
mvollmer authored
331 the marked commit no matter where point is, use @kbd{C-u .}.
c691bc7 @voins Allow unmarking the marked commit.
voins authored
332
333 Some commands, such as @kbd{=}, will use the current commit and the
334 marked commit as implicit arguments. Other commands will offer the
335 marked commit as a default when prompting for their arguments.
ff21f5a Some content for the manual.
Marius Vollmer authored
336
c8cdc5e Manual updates.
Marius Vollmer authored
337 @node Reflogs
338 @chapter Reflogs
339
340 You can use @kbd{h} and @kbd{H} to browse your @emph{reflog}, the
341 local history of changes made to your repository heads. Typing
342 @kbd{H} will ask for a head, while @kbd{h} will show the reflog of
343 @code{HEAD}.
344
345 The resulting buffer is just like the buffer produced by @kbd{l} and
346 @kbd{L} that shows the commit history.
347
6538ce4 Manual improvements and updates.
Marius Vollmer authored
348 @node Diffing
349 @chapter Diffing
350
351 To show the changes from you working tree to another revision, type
352 @kbd{d}. To show the changes between two arbitrary revisions, type
353 @kbd{D}.
48386c9 Unified keymaps, make resetting use the commit at point instead of
Marius Vollmer authored
354
14004f4 Stage/unstage, etc individual lines.
Marius Vollmer authored
355 You can use @kbd{a} within the diff output to apply the changes to
356 your working tree. As usual when point is in a diff header for a
357 file, all changes for that file are applied, and when it is in a hunk,
358 only that hunk is. When the region is active, the applied changes are
359 restricted to that region.
360
361 Typing @kbd{v} will apply the selected changes in reverse.
362
201822e @mvollmer Basic support for tagging.
mvollmer authored
363 @node Tagging
364 @chapter Tagging
365
366 Typing @kbd{t} will make a lighweight tag. Typing @kbd{T} will make a
367 annotated tag. It will put you in the normal @code{*magit-log-edit}
368 buffer for writing commit messages, but typing @kbd{C-c C-c} in it
369 will make the tag instead. This is controlled by the @code{Tag} field
370 that will be added to the @code{*magit-log-edit*} buffer. You can
371 edit it, if you like.
372
22ee4f7 Rebasing.
Marius Vollmer authored
373 @node Resetting
374 @chapter Resetting
11689b7 Manual additions.
Marius Vollmer authored
375
376 Once you have added a commit to your local repository, you can not
52c2e3e Speling fixes.
Marius Vollmer authored
377 change that commit anymore in any way. But you can reset your current
378 head to an earlier commit and start over.
11689b7 Manual additions.
Marius Vollmer authored
379
6538ce4 Manual improvements and updates.
Marius Vollmer authored
380 If you have published your history already, rewriting it in this way
381 can be confusing and should be avoided. However, rewriting your local
382 history is fine and it is often cleaner to fix mistakes this way than
c8cdc5e Manual updates.
Marius Vollmer authored
383 by reverting commits (with @kbd{v}, for example).
11689b7 Manual additions.
Marius Vollmer authored
384
6538ce4 Manual improvements and updates.
Marius Vollmer authored
385 Typing @kbd{x} will ask for a revision and reset your current head to
386 it. No changes will be made to your working tree and staging area.
387 Thus, the @emph{Staged changes} section in the status buffer will show
388 the changes that you have removed from your commit history. You can
389 commit the changes again as if you had just made them, thus rewriting
390 history.
11689b7 Manual additions.
Marius Vollmer authored
391
6538ce4 Manual improvements and updates.
Marius Vollmer authored
392 Typing @kbd{x} while point is in a line that describes a commit will
393 offer this commit as the default revision to reset to. Thus, you can
394 move point to one of the commits in the @emph{Unpushed commits}
395 section and hit @kbd{x RET} to reset your current head to it.
11689b7 Manual additions.
Marius Vollmer authored
396
6538ce4 Manual improvements and updates.
Marius Vollmer authored
397 Type @kbd{X} to reset your working tree and staging area to the most
398 recently committed state. This will discard your local modifications,
399 so be careful.
e4aceaf Manual additions.
Marius Vollmer authored
400
e6a1fd4 @mvollmer Tell people that they are going to do a hard reset.
mvollmer authored
401 You can give a prefix to @kbd{x} if you want to reset both the current
402 head and your working tree to a given commit. This is the same as
403 first using an unprefixed @kbd{x} to reset only the head, and then
404 using @kbd{X}.
405
7ac76de @mvollmer Stashing.
mvollmer authored
406 @node Stashing
407 @chapter Stashing
408
409 You can create a new stash with @kbd{z}. Your stashes will be listed
410 in the status buffer, and you can apply them with @kbd{a} and pop them
411 with @kbd{A}. To drop a stash, use @kbd{k}.
412
5c3ac91 @mvollmer Documentation updates.
mvollmer authored
413 Typing @kbd{Z} will create a stash just like @kbd{z}, but will leave
414 the changes in your working tree and index.
415
3c6088e @mvollmer Manual updates.
mvollmer authored
416 You can visit and show stashes in the usual way: Typing @kbd{SPC} and
417 @kbd{DEL} will pop up a buffer with the description of the stash and
418 scroll it, typing @kbd{RET} will move point into that buffer.
419
a21e998 Manual fixes.
Marius Vollmer authored
420 @node Branching
421 @chapter Branching
ff21f5a Some content for the manual.
Marius Vollmer authored
422
423 The current branch is indicated in the header of the status buffer.
6538ce4 Manual improvements and updates.
Marius Vollmer authored
424 You can switch to a different branch by typing @kbd{b}. This will
425 immediately checkout the branch into your working copy, so you
426 shouldn't have any local modifications when switching branches.
427
a21e998 Manual fixes.
Marius Vollmer authored
428 Similar to @kbd{x}, typing @kbd{b} while point is at a commit
6538ce4 Manual improvements and updates.
Marius Vollmer authored
429 description will offer that commit as the default to switch to.
430 This will result in a detached head.
431
432 To create a new branch and switch to it immediately, type @kbd{B}.
ff21f5a Some content for the manual.
Marius Vollmer authored
433
3c6088e @mvollmer Manual updates.
mvollmer authored
434 @node Wazzup
435 @chapter Wazzup
436
437 Typing @kbd{w} will show a summary of how your other branches relate
438 to the current branch.
439
440 For each branch, you will get a section that lists the commits in that
441 branch that are not in the current branch. The sections are initially
442 collapsed; you need to explicitly open them with @kbd{TAB} (or
443 similar) to show the lists of commits.
444
87a533d @mvollmer More docs.
mvollmer authored
445 When point is on a @emph{N unmerged commits in ...} title, the
446 corresponding branch will be offered as the default for a merge.
447
3857ce2 @mvollmer Allow ignoring of branches in the Wazzup view.
mvollmer authored
448 Hitting @kbd{i} on a branch title will ignore this branch in the
449 wazzup view. You can use @kbd{C-u w} to show all branches, including
5c7b6b2 @mvollmer Make 'i' toggle the ignore flag for wazzup.
mvollmer authored
450 the ignored ones. Hitting @kbd{i} on an already ignored branch in
451 that view will unignore it.
3857ce2 @mvollmer Allow ignoring of branches in the Wazzup view.
mvollmer authored
452
6538ce4 Manual improvements and updates.
Marius Vollmer authored
453 @node Merging
454 @chapter Merging
ff21f5a Some content for the manual.
Marius Vollmer authored
455
456 Magit offers two ways to merge branches: manually and automatic. A
457 manual merge will apply all changes to your working tree and staging
458 area, but will not commit them, while a automatic merge will go ahead
459 and commit them immediately.
460
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
461 Type @kbd{m} to initiate a manual merge, and type @kbd{M} for a
462 automatic merge.
463
ff21f5a Some content for the manual.
Marius Vollmer authored
464 A manual merge is useful when carefully merging a new feature that you
6538ce4 Manual improvements and updates.
Marius Vollmer authored
465 want to review and test before even committing it. A automatic merge
466 is appropriate when you are on a feature branch and want to catch up
467 with the master, say.
ff21f5a Some content for the manual.
Marius Vollmer authored
468
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
469 After initiating a manual merge, the header of the status buffer will
470 remind you that the next commit will be a merge commit (with more than
471 one parent). If you want to abort a manual merge, just do a hard
c8cdc5e Manual updates.
Marius Vollmer authored
472 reset to HEAD with @kbd{X}.
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
473
474 Merges can fail if the two branches you merge want to introduce
1eac6b7 @vanicat Use ediff interactive merge to help conflict resolution.
vanicat authored
475 conflicting changes. In that case, the automatic merge stops before the
476 commit, essentially falling back to a manual merge. You need to resolve
477 the conflicts for example with @kbd{e} and stage the resolved files, for
478 example with @kbd{S}.
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
479
480 You can not stage individual hunks one by one as you resolve them, you
481 can only stage whole files once all conflicts in them have been
e37626e Manual improvements.
Marius Vollmer authored
482 resolved.
067e715 More manual stuff, use "Magit" and "Git" spelling.
Marius Vollmer authored
483
484 @node Rebasing
485 @chapter Rebasing
11689b7 Manual additions.
Marius Vollmer authored
486
22ee4f7 Rebasing.
Marius Vollmer authored
487 Typing @kbd{R} in the status buffer will initiate a rebase or, if one
488 is already in progress, ask you how to continue.
489
490 When a rebase is stopped in the middle because of a conflict, the
e37626e Manual improvements.
Marius Vollmer authored
491 header of the status buffer will indicate how far along you are in the
492 series of commits that are being replayed.
22ee4f7 Rebasing.
Marius Vollmer authored
493
494 Of course, you can initiate a rebase in any number of ways, by
495 configuring @code{git pull} to rebase instead of merge, for example.
e37626e Manual improvements.
Marius Vollmer authored
496 Such a rebase can be finished with @kbd{R} as well.
14b1153 Manual additions.
Marius Vollmer authored
497
2733ae2 Document rewriting.
Marius Vollmer authored
498 @node Rewriting
499 @chapter Rewriting
500
501 As hinted at earlier, you can rewrite your commit history. For
502 example, you can reset he current head to an earlier commit with
503 @kbd{x}. This leaves the working tree unchanged, and the status
9ce8cb3 Fixed teh typos.
Marius Vollmer authored
504 buffer will show all the changes that have been made since that new
2733ae2 Document rewriting.
Marius Vollmer authored
505 value of the current head. You can commit these changes again,
506 possibly splitting them into multiple commits as you go along.
507
9ce8cb3 Fixed teh typos.
Marius Vollmer authored
508 Amending your last commit is a common special case of rewriting
509 history like this.
2733ae2 Document rewriting.
Marius Vollmer authored
510
511 Another common way to rewrite history is to reset the head to an
9ce8cb3 Fixed teh typos.
Marius Vollmer authored
512 earlier commit, and then to cherry pick the previous commits in a
513 different order. You could pick them from the reflog, for example.
2733ae2 Document rewriting.
Marius Vollmer authored
514
9ce8cb3 Fixed teh typos.
Marius Vollmer authored
515 Magit has several commands that can simplify the book keeping
516 associated with rewriting. These commands all start with the @kbd{r}
517 prefix key.
2733ae2 Document rewriting.
Marius Vollmer authored
518
519 Typing @kbd{r s} will start a rewrite operation. You will be prompted
520 for a @emph{base} commit, and all commits between the current head and
521 this commit are put in a list of @emph{Pending commits} (including the
522 base commit). The current head will then be reset to the parent of
523 the base commit.
524
525 You would then typically use @kbd{a} and @kbd{A} to cherry pick
526 commits from the list of pending commits in the desired order, until
527 all have been applied. Magit shows which commits have been applied by
528 changing their marker from @code{*} to @code{.}.
529
530 Using @kbd{A} will immediately commit the commit (as usual). If you
9ce8cb3 Fixed teh typos.
Marius Vollmer authored
531 want to combine multiple previous commits into a single new one, use
2733ae2 Document rewriting.
Marius Vollmer authored
532 @kbd{a} to apply them all to your working tree, and then commit them
9ce8cb3 Fixed teh typos.
Marius Vollmer authored
533 together.
2733ae2 Document rewriting.
Marius Vollmer authored
534
7419a8b Mention non-support for rewriting merge commits in the manual.
Marius Vollmer authored
535 Magit has no explicit support for rewriting merge commits. It will
536 happily include merge commits in the list of pending commits, but
537 there is no way of replaying them automatically. You have to redo the
538 merge explicitly.
539
2733ae2 Document rewriting.
Marius Vollmer authored
540 You can also use @kbd{v} to revert a commit when you have changed your
541 mind. This will change the @code{.} mark back to @code{*}.
542
543 Once you are done with the rewrite, type @kbd{r t} to remove the book
544 keeping information from the status buffer.
545
546 If you rather wish to start over, type @kbd{r a}. This will abort the
547 rewriting, resetting the current head back to the value it had before
548 the rewrite was started with @kbd{r s}.
549
550 Typing @kbd{r f} will @emph{finish} the rewrite: it will apply all
551 unused commits one after the other, as if you would us @kbd{A} with
552 all of them.
553
554 You can change the @kbd{*} and @kbd{.} marks of a pending commit
555 explicitly with @kbd{r *} and @kbd{r .}.
556
557 In addition to a list of pending commits, the status buffer will show
558 the @emph{Pending changes}. This section shows the diff between the
559 original head and the current head. You can use it to review the
560 changes that you still need to rewrite, and you can apply hunks from
561 it, like from any other diff.
562
ff21f5a Some content for the manual.
Marius Vollmer authored
563 @node Pushing and Pulling
564 @chapter Pushing and Pulling
565
157bee4 @mvollmer Even more control for pushing.
mvollmer authored
566 Magit will run @code{git push} when you type @kbd{P}. If you give a
567 prefix argument to @kbd{P}, you will be prompted for the repository to
568 push to. When no default remote repositor has been configured yet for
569 the current branch, you will be prompted as well. Typing @kbd{P} will
570 only push the current branch to the remote. In other words, it will
571 run @code{git push <remote> <branch>}.
151ae0a Redone key bindings for pulling, leaving 'U' free for unstage-all.
Marius Vollmer authored
572
573 Typing @kbd{f} will run @code{git remote update} and @kbd{F} will run
157bee4 @mvollmer Even more control for pushing.
mvollmer authored
574 @code{git pull}. You should have setup your Git configuration to do
575 the right thing for @code{git pull}.
14b1153 Manual additions.
Marius Vollmer authored
576
157bee4 @mvollmer Even more control for pushing.
mvollmer authored
577 If there is a default remote repository for the current branch, Magit
578 will show that repository in the status buffer header.
14b1153 Manual additions.
Marius Vollmer authored
579
580 In this case, the status buffer will also have a @emph{Unpushed
7ae8fab Typo in manual.
Marius Vollmer authored
581 commits} section that shows the commits on your current head that are
7a57506 Updated manual.
Marius Vollmer authored
582 not in the branch named @code{<remote>/<branch>}. This section works
151ae0a Redone key bindings for pulling, leaving 'U' free for unstage-all.
Marius Vollmer authored
583 just like the history buffer: you can see details about a commit with
c8cdc5e Manual updates.
Marius Vollmer authored
584 @kbd{RET}, compare two of them with @kbd{.} and @kbd{=}, and you can
585 reset your current head to one of them with @kbd{x}, for example.
14b1153 Manual additions.
Marius Vollmer authored
586
1017a27 Updated manual.
Marius Vollmer authored
587 When the remote branch has changes that are not in the current branch,
588 Magit shows them in a section called @emph{Unpulled changes}. Typing
589 @kbd{F} will merge them into the current branch.
590
fe7ffeb Add keybindings for git-svn commands.
Alex Ott authored
591 @node Interfacing with Subversion
592 @chapter Interfacing with Subversion
593
594 Typing @kbd{N r} runs @code{git svn rebase} and typing @kbd{N c} runs
595 @code{git svn dcommit}.
596
ff21f5a Some content for the manual.
Marius Vollmer authored
597 @bye
Something went wrong with that request. Please try again.