mirror of https://github.com/Chizi123/.emacs.d.git

Chizi123
2018-11-21 e75a20334813452c6912c090d70a0de2c805f94d
commit | author | age
5cb5f7 1 This is magit.info, produced by makeinfo version 6.5 from magit.texi.
C 2
3      Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
4
5      You can redistribute this document and/or modify it under the terms
6      of the GNU General Public License as published by the Free Software
7      Foundation, either version 3 of the License, or (at your option)
8      any later version.
9
10      This document is distributed in the hope that it will be useful,
11      but WITHOUT ANY WARRANTY; without even the implied warranty of
12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13      General Public License for more details.
14
15 INFO-DIR-SECTION Emacs
16 START-INFO-DIR-ENTRY
17 * Magit: (magit).       Using Git from Emacs with Magit.
18 END-INFO-DIR-ENTRY
19
20 
21 File: magit.info,  Node: Top,  Next: Introduction,  Up: (dir)
22
23 Magit User Manual
24 *****************
25
26 Magit is an interface to the version control system Git, implemented as
27 an Emacs package.  Magit aspires to be a complete Git porcelain.  While
28 we cannot (yet) claim that Magit wraps and improves upon each and every
29 Git command, it is complete enough to allow even experienced Git users
30 to perform almost all of their daily version control tasks directly from
31 within Emacs.  While many fine Git clients exist, only Magit and Git
32 itself deserve to be called porcelains.
33
34 This manual is for Magit version 2.90.1 (v2.90.1-9-gd2c84d9a5+1).
35
36      Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
37
38      You can redistribute this document and/or modify it under the terms
39      of the GNU General Public License as published by the Free Software
40      Foundation, either version 3 of the License, or (at your option)
41      any later version.
42
43      This document is distributed in the hope that it will be useful,
44      but WITHOUT ANY WARRANTY; without even the implied warranty of
45      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
46      General Public License for more details.
47
48 * Menu:
49
50 * Introduction::
51 * Installation::
52 * Getting Started::
53 * Interface Concepts::
54 * Inspecting::
55 * Manipulating::
56 * Transferring::
57 * Miscellaneous::
58 * Customizing::
59 * Plumbing::
60 * FAQ::
61 * Debugging Tools::
62 * Keystroke Index::
63 * Command Index::
64 * Function Index::
65 * Variable Index::
66
67 — The Detailed Node Listing —
68
69 Installation
70
71 * Installing from Melpa::
72 * Installing from the Git Repository::
73 * Post-Installation Tasks::
74
75 Interface Concepts
76
77 * Modes and Buffers::
78 * Sections::
79 * Popup Buffers and Prefix Commands::
80 * Completion, Confirmation and the Selection: Completion Confirmation and the Selection.
81 * Running Git::
82
83 Modes and Buffers
84
85 * Switching Buffers::
86 * Naming Buffers::
87 * Quitting Windows::
88 * Automatic Refreshing of Magit Buffers::
89 * Automatic Saving of File-Visiting Buffers::
90 * Automatic Reverting of File-Visiting Buffers::
91
92
93 Sections
94
95 * Section Movement::
96 * Section Visibility::
97 * Section Hooks::
98 * Section Types and Values::
99 * Section Options::
100
101
102 Completion, Confirmation and the Selection
103
104 * Action Confirmation::
105 * Completion and Confirmation::
106 * The Selection::
107 * The hunk-internal region::
108 * Support for Completion Frameworks::
109 * Additional Completion Options::
110
111
112 Running Git
113
114 * Viewing Git Output::
115 * Git Process Status::
116 * Running Git Manually::
117 * Git Executable::
118 * Global Git Arguments::
119
120
121 Inspecting
122
123 * Status Buffer::
124 * Repository List::
125 * Logging::
126 * Diffing::
127 * Ediffing::
128 * References Buffer::
129 * Bisecting::
130 * Visiting Blobs::
131 * Blaming::
132
133 Status Buffer
134
135 * Status Sections::
136 * Status Header Sections::
137 * Status Module Sections::
138 * Status Options::
139
140
141 Logging
142
143 * Refreshing Logs::
144 * Log Buffer::
145 * Log Margin::
146 * Select from Log::
147 * Reflog::
148 * Cherries::
149
150
151 Diffing
152
153 * Refreshing Diffs::
154 * Diff Buffer::
155 * Diff Options::
156 * Revision Buffer::
157
158
159 References Buffer
160
161 * References Sections::
162
163
164 Manipulating
165
166 * Repository Setup::
167 * Staging and Unstaging::
168 * Applying::
169 * Committing::
170 * Branching::
171 * Merging::
172 * Resolving Conflicts::
173 * Rebasing::
174 * Cherry Picking::
175 * Resetting::
176 * Stashing::
177
178 Staging and Unstaging
179
180 * Staging from File-Visiting Buffers::
181
182
183 Committing
184
185 * Initiating a Commit::
186 * Editing Commit Messages::
187
188
189 Branching
190
191 * The Two Remotes::
192 * The Branch Popup::
193 * The Branch Config Popup::
194 * Auxiliary Branch Commands::
195
196
197 Rebasing
198
199 * Editing Rebase Sequences::
200 * Information About In-Progress Rebase::
201
202
203 Cherry Picking
204
205 * Reverting::
206
207
208 Transferring
209
210 * Remotes::
211 * Fetching::
212 * Pulling::
213 * Pushing::
214 * Creating and Sending Patches::
215 * Applying Patches::
216
217 Remotes
218
219 * The Remote Popup::
220 * The Remote Config Popup::
221
222
223 Miscellaneous
224
225 * Tagging::
226 * Notes::
227 * Submodules::
228 * Subtree::
229 * Worktree::
230 * Common Commands::
231 * Wip Modes::
232 * Minor Mode for Buffers Visiting Files::
233 * Minor Mode for Buffers Visiting Blobs::
234
235 Submodules
236
237 * Listing Submodules::
238 * Submodule Popup::
239
240
241 Wip Modes
242
243 * Wip Graph::
244 * Legacy Wip Modes::
245
246
247 Customizing
248
249 * Per-Repository Configuration::
250 * Essential Settings::
251
252 Essential Settings
253
254 * Safety::
255 * Performance::
256
257
258 Plumbing
259
260 * Calling Git::
261 * Section Plumbing::
262 * Refreshing Buffers::
263 * Conventions::
264
265 Calling Git
266
267 * Getting a Value from Git::
268 * Calling Git for Effect::
269
270
271 Section Plumbing
272
273 * Creating Sections::
274 * Section Selection::
275 * Matching Sections::
276
277
278 Conventions
279
280 * Theming Faces::
281
282
283 FAQ
284
285 * FAQ - How to ...?::
286 * FAQ - Issues and Errors::
287
288 FAQ - How to ...?
289
290 * How to show git's output?::
291 * How to install the gitman info manual?::
292 * How to show diffs for gpg-encrypted files?::
293 * How does branching and pushing work?::
294 * Can Magit be used as ediff-version-control-package?::
295
296
297 FAQ - Issues and Errors
298
299 * Magit is slow::
300 * I changed several thousand files at once and now Magit is unusable::
301 * I am having problems committing::
302 * I am using MS Windows and cannot push with Magit::
303 * I am using OS X and SOMETHING works in shell, but not in Magit: I am using OS X and SOMETHING works in shell but not in Magit.
304 * Diffs contain control sequences::
305 * Expanding a file to show the diff causes it to disappear::
306 * Point is wrong in the COMMIT_EDITMSG buffer::
307 * The mode-line information isn't always up-to-date::
308 * A branch and tag sharing the same name breaks SOMETHING::
309 * My Git hooks work on the command-line but not inside Magit::
310 * git-commit-mode isn't used when committing from the command-line::
311 * Point ends up inside invisible text when jumping to a file-visiting buffer::
312
313
314
315 
316 File: magit.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top
317
318 1 Introduction
319 **************
320
321 Magit is an interface to the version control system Git, implemented as
322 an Emacs package.  Magit aspires to be a complete Git porcelain.  While
323 we cannot (yet) claim that Magit wraps and improves upon each and every
324 Git command, it is complete enough to allow even experienced Git users
325 to perform almost all of their daily version control tasks directly from
326 within Emacs.  While many fine Git clients exist, only Magit and Git
327 itself deserve to be called porcelains.
328
329    Staging and otherwise applying changes is one of the most important
330 features in a Git porcelain and here Magit outshines anything else,
331 including Git itself.  Git’s own staging interface (‘git add --patch’)
332 is so cumbersome that many users only use it in exceptional cases.  In
333 Magit staging a hunk or even just part of a hunk is as trivial as
334 staging all changes made to a file.
335
336    The most visible part of Magit’s interface is the status buffer,
337 which displays information about the current repository.  Its content is
338 created by running several Git commands and making their output
339 actionable.  Among other things, it displays information about the
340 current branch, lists unpulled and unpushed changes and contains
341 sections displaying the staged and unstaged changes.  That might sound
342 noisy, but, since sections are collapsible, it’s not.
343
344    To stage or unstage a change one places the cursor on the change and
345 then types ‘s’ or ‘u’.  The change can be a file or a hunk, or when the
346 region is active (i.e.  when there is a selection) several files or
347 hunks, or even just part of a hunk.  The change or changes that these
348 commands - and many others - would act on are highlighted.
349
350    Magit also implements several other "apply variants" in addition to
351 staging and unstaging.  One can discard or reverse a change, or apply it
352 to the working tree.  Git’s own porcelain only supports this for staging
353 and unstaging and you would have to do something like ‘git diff ... |
354 ??? | git apply ...’ to discard, revert, or apply a single hunk on the
355 command line.  In fact that’s exactly what Magit does internally (which
356 is what lead to the term "apply variants").
357
358    Magit isn’t just for Git experts, but it does assume some prior
359 experience with Git as well as Emacs.  That being said, many users have
360 reported that using Magit was what finally taught them what Git is
361 capable of and how to use it to its fullest.  Other users wished they
362 had switched to Emacs sooner so that they would have gotten their hands
363 on Magit earlier.
364
365    While one has to know the basic features of Emacs to be able to make
366 full use of Magit, acquiring just enough Emacs skills doesn’t take long
367 and is worth it, even for users who prefer other editors.  Vim users are
368 advised to give Evil (https://bitbucket.org/lyro/evil/wiki/Home), the
369 "Extensible VI Layer for Emacs", and Spacemacs
370 (https://github.com/syl20bnr/spacemacs), an "Emacs starter-kit focused
371 on Evil" a try.
372
373    Magit provides a consistent and efficient Git porcelain.  After a
374 short learning period, you will be able to perform most of your daily
375 version control tasks faster than you would on the command line.  You
376 will likely also start using features that seemed too daunting in the
377 past.
378
379    Magit fully embraces Git.  It exposes many advanced features using a
380 simple but flexible interface instead of only wrapping the trivial ones
381 like many GUI clients do.  Of course Magit supports logging, cloning,
382 pushing, and other commands that usually don’t fail in spectacular ways;
383 but it also supports tasks that often cannot be completed in a single
384 step.  Magit fully supports tasks such as merging, rebasing,
385 cherry-picking, reverting, and blaming by not only providing a command
386 to initiate these tasks but also by displaying context sensitive
387 information along the way and providing commands that are useful for
388 resolving conflicts and resuming the sequence after doing so.
389
390    Magit wraps and in many cases improves upon at least the following
391 Git porcelain commands: ‘add’, ‘am’, ‘bisect’, ‘blame’, ‘branch’,
392 ‘checkout’, ‘cherry’, ‘cherry-pick’, ‘clean’, ‘clone’, ‘commit’,
393 ‘config’, ‘describe’, ‘diff’, ‘fetch’, ‘format-patch’, ‘init’, ‘log’,
394 ‘merge’, ‘merge-tree’, ‘mv’, ‘notes’, ‘pull’, ‘rebase’, ‘reflog’,
395 ‘remote’, ‘request-pull’, ‘reset’, ‘revert’, ‘rm’, ‘show’, ‘stash’,
396 ‘submodule’, ‘subtree’, ‘tag’, and ‘worktree.’ Many more Magit porcelain
397 commands are implemented on top of Git plumbing commands.
398
399 
400 File: magit.info,  Node: Installation,  Next: Getting Started,  Prev: Introduction,  Up: Top
401
402 2 Installation
403 **************
404
405 Magit can be installed using Emacs’ package manager or manually from its
406 development repository.
407
408 * Menu:
409
410 * Installing from Melpa::
411 * Installing from the Git Repository::
412 * Post-Installation Tasks::
413
414 
415 File: magit.info,  Node: Installing from Melpa,  Next: Installing from the Git Repository,  Up: Installation
416
417 2.1 Installing from Melpa
418 =========================
419
420 Magit is available from Melpa and Melpa-Stable.  If you haven’t used
421 Emacs’ package manager before, then it is high time you familiarize
422 yourself with it by reading the documentation in the Emacs manual, see
423 *note (emacs)Packages::.  Then add one of the archives to
424 ‘package-archives’:
425
426    • To use Melpa:
427
428      (require 'package)
429      (add-to-list 'package-archives
430                   '("melpa" . "http://melpa.org/packages/") t)
431
432    • To use Melpa-Stable:
433
434      (require 'package)
435      (add-to-list 'package-archives
436                   '("melpa-stable" . "http://stable.melpa.org/packages/") t)
437
438    Once you have added your preferred archive, you need to update the
439 local package list using:
440
441      M-x package-refresh-contents RET
442
443    Once you have done that, you can install Magit and its dependencies
444 using:
445
446      M-x package-install RET magit RET
447
448    Now see *note Post-Installation Tasks::.
449
450 
451 File: magit.info,  Node: Installing from the Git Repository,  Next: Post-Installation Tasks,  Prev: Installing from Melpa,  Up: Installation
452
453 2.2 Installing from the Git Repository
454 ======================================
455
456 Magit depends on the ‘dash’, ‘ghub’, ‘graphql’, ‘magit-popup’, ‘treepy’
457 and ‘with-editor’ libraries which are available from Melpa and
458 Melpa-Stable.  Install them using ‘M-x package-install RET <package>
459 RET’.  Of course you may also install them manually from their
460 repository.
461
462    Then clone the Magit repository:
463
464      $ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit
465      $ cd ~/.emacs.d/site-lisp/magit
466
467    Then compile the libraries and generate the info manuals:
468
469      $ make
470
471    If you haven’t installed ‘dash’, ‘ghub’, ‘graphql’, ‘magit-popup’,
472 ‘treepy’ and ‘with-editor’ from Melpa or at
473 ‘/path/to/magit/../<package>’, then you have to tell ‘make’ where to
474 find them.  To do so create the file ‘/path/to/magit/config.mk’ with the
475 following content before running ‘make’:
476
477      LOAD_PATH  = -L /path/to/magit/lisp
478      LOAD_PATH += -L /path/to/dash
479      LOAD_PATH += -L /path/to/ghub
480      LOAD_PATH += -L /path/to/graphql
481      LOAD_PATH += -L /path/to/magit-popup
482      LOAD_PATH += -L /path/to/treepy
483      LOAD_PATH += -L /path/to/with-editor
484
485    Finally add this to your init file:
486
487      (add-to-list 'load-path "~/.emacs.d/site-lisp/magit/lisp")
488      (require 'magit)
489
490      (with-eval-after-load 'info
491        (info-initialize)
492        (add-to-list 'Info-directory-list
493                     "~/.emacs.d/site-lisp/magit/Documentation/"))
494
495    Note that you have to add the ‘lisp’ subdirectory to the ‘load-path’,
496 not the top-level of the repository, and that elements of ‘load-path’
497 should not end with a slash, while those of ‘Info-directory-list’
498 should.
499
500    Instead of requiring the feature ‘magit’, you could load just the
501 autoload definitions, by loading the file ‘magit-autoloads.el’.
502
503      (load "/path/to/magit/lisp/magit-autoloads")
504
505    Instead of running Magit directly from the repository by adding that
506 to the ‘load-path’, you might want to instead install it in some other
507 directory using ‘sudo make install’ and setting ‘load-path’ accordingly.
508
509    To update Magit use:
510
511      $ git pull
512      $ make
513
514    At times it might be necessary to run ‘make clean all’ instead.
515
516    To view all available targets use ‘make help’.
517
518    Now see *note Post-Installation Tasks::.
519
520 
521 File: magit.info,  Node: Post-Installation Tasks,  Prev: Installing from the Git Repository,  Up: Installation
522
523 2.3 Post-Installation Tasks
524 ===========================
525
526 After installing Magit you should verify that you are indeed using the
527 Magit, Git, and Emacs releases you think you are using.  It’s best to
528 restart Emacs before doing so, to make sure you are not using an
529 outdated value for ‘load-path’.
530
531      M-x magit-version RET
532
533    should display something like
534
535      Magit 2.8.0, Git 2.10.2, Emacs 25.1.1, gnu/linux
536
537    Then you might also want to read about options that many users likely
538 want to customize.  See *note Essential Settings::.
539
540    To be able to follow cross references to Git manpages found in this
541 manual, you might also have to manually install the ‘gitman’ info
542 manual, or advice ‘Info-follow-nearest-node’ to instead open the actual
543 manpage.  See *note How to install the gitman info manual?::.
544
545    If you are completely new to Magit then see *note Getting Started::.
546
547    If you run into problems, then please see the *note FAQ::.  Also see
548 the *note Debugging Tools::.
549
550    And last but not least please consider making a donation, to ensure
551 that I can keep working on Magit.  See <https://magit.vc/donations>.
552 for various donation options.
553
554 
555 File: magit.info,  Node: Getting Started,  Next: Interface Concepts,  Prev: Installation,  Up: Top
556
557 3 Getting Started
558 *****************
559
560 This short tutorial describes the most essential features that many
561 Magitians use on a daily basis.  It only scratches the surface but
562 should be enough to get you started.
563
564    IMPORTANT: It is safest if you clone some repository just for this
565 tutorial.  Alternatively you can use an existing local repository, but
566 if you do that, then you should commit all uncommitted changes before
567 proceeding.
568
569    To display information about the current Git repository, type ‘M-x
570 magit-status RET’.  You will be using this command a lot, and should
571 therefore give it a global key binding.  This is what we recommend:
572
573      (global-set-key (kbd "C-x g") 'magit-status)
574
575    Most Magit commands are commonly invoked from the status buffer.  It
576 can be considered the primary interface for interacting with Git using
577 Magit.  Many other Magit buffers may exist at a given time, but they are
578 often created from this buffer.
579
580    Depending on what state your repository is in, this buffer may
581 contain sections titled "Staged changes", "Unstaged changes", "Unmerged
582 into origin/master", "Unpushed to origin/master", and many others.
583
584    Since we are starting from a safe state, which you can easily return
585 to (by doing a ‘git reset --hard PRE-MAGIT-STATE’), there currently are
586 not staged or unstaged changes.  Edit some files and save the changes.
587 Then go back to the status buffer, while at the same time refreshing it,
588 by typing ‘C-x g’.  (When the status buffer, or any Magit buffer for
589 that matter, is the current buffer, then you can also use just ‘g’ to
590 refresh it).
591
592    Move between sections using ‘p’ and ‘n’.  Note that the bodies of
593 some sections are hidden.  Type ‘TAB’ to expand or collapse the section
594 at point.  You can also use ‘C-tab’ to cycle the visibility of the
595 current section and its children.  Move to a file section inside the
596 section named "Unstaged changes" and type ‘s’ to stage the changes you
597 have made to that file.  That file now appears under "Staged changes".
598
599    Magit can stage and unstage individual hunks, not just complete
600 files.  Move to the file you have just staged, expand it using ‘TAB’,
601 move to one of the hunks using ‘n’, and unstage just that by typing ‘u’.
602 Note how the staging (‘s’) and unstaging (‘u’) commands operate on the
603 change at point.  Many other commands behave the same way.
604
605    You can also un-/stage just part of a hunk.  Inside the body of a
606 hunk section (move there using ‘C-n’), set the mark using ‘C-SPC’ and
607 move down until some added and/or removed lines fall inside the region
608 but not all of them.  Again type ‘s’ to stage.
609
610    It is also possible to un-/stage multiple files at once.  Move to a
611 file section, type ‘C-SPC’, move to the next file using ‘n’, and then
612 ‘s’ to stage both files.  Note that both the mark and point have to be
613 on the headings of sibling sections for this to work.  If the region
614 looks like it does in other buffers, then it doesn’t select Magit
615 sections that can be acted on as a unit.
616
617    And then of course you want to commit your changes.  Type ‘c’.  This
618 shows the committing popup buffer featuring various commit variants and
619 arguments that can be passed to ‘git commit’.  Do not worry about those
620 for now.  We want to create a "normal" commit, which is done by typing
621 ‘c’ again.
622
623    Now two new buffers appear.  One is for writing the commit message,
624 the other shows a diff with the changes that you are about to committed.
625 Write a message and then type ‘C-c C-c’ to actually create the commit.
626
627    You probably don’t want to push the commit you just created because
628 you just committed some random changes, but if that is not the case you
629 could push it by typing ‘P’ to bring up the push popup and then ‘p’ to
630 push to a branch with the same name as the local branch onto the remote
631 configured as the push-remote.  (If the push-remote is not configured
632 yet, then you would first be prompted for the remote to push to.)
633
634    So far we have mentioned the commit, push, and log popups.  These are
635 probably among the popups you will be using the most, but many others
636 exist.  To show a popup that lists all other popups (as well as the
637 various apply commands and some other fundamental commands), type ‘h’.
638 Try a few.
639
640    The key bindings in that popup correspond to the bindings in Magit
641 buffers, including but not limited to the status buffer.  So you could
642 type ‘h d’ to bring up the diff popup, but once you remember that "d"
643 stands for "diff", you would usually do so by just typing ‘d’.  But the
644 "popup of popups" is useful even once you have memorized all the
645 bindings, as it can provide easy access to Magit commands from non-Magit
646 buffers.  You should create a global key binding for this command too:
647
648      (global-set-key (kbd "C-x M-g") 'magit-dispatch-popup)
649
650    In the same vein, you might also want to enable
651 ‘global-magit-file-mode’ to get some more Magit key bindings in regular
652 file-visiting buffers (see *note Minor Mode for Buffers Visiting
653 Files::).
654
655    It is not necessary that you do so now, but if you stick with Magit,
656 then it is highly recommended that you read the next section too.
657
658 
659 File: magit.info,  Node: Interface Concepts,  Next: Inspecting,  Prev: Getting Started,  Up: Top
660
661 4 Interface Concepts
662 ********************
663
664 * Menu:
665
666 * Modes and Buffers::
667 * Sections::
668 * Popup Buffers and Prefix Commands::
669 * Completion, Confirmation and the Selection: Completion Confirmation and the Selection.
670 * Running Git::
671
672 
673 File: magit.info,  Node: Modes and Buffers,  Next: Sections,  Up: Interface Concepts
674
675 4.1 Modes and Buffers
676 =====================
677
678 Magit provides several major-modes.  For each of these modes there
679 usually exists only one buffer per repository.  Separate modes and thus
680 buffers exist for commits, diffs, logs, and some other things.
681
682    Besides these special purpose buffers, there also exists an overview
683 buffer, called the *status buffer*.  It’s usually from this buffer that
684 the user invokes Git commands, or creates or visits other buffers.
685
686    In this manual we often speak about "Magit buffers".  By that we mean
687 buffers whose major-modes derive from ‘magit-mode’.
688
689 ‘M-x magit-toggle-buffer-lock’     (‘magit-toggle-buffer-lock’)
690
691      This command locks the current buffer to its value or if the buffer
692      is already locked, then it unlocks it.
693
694      Locking a buffer to its value prevents it from being reused to
695      display another value.  The name of a locked buffer contains its
696      value, which allows telling it apart from other locked buffers and
697      the unlocked buffer.
698
699      Not all Magit buffers can be locked to their values; for example,
700      it wouldn’t make sense to lock a status buffer.
701
702      There can only be a single unlocked buffer using a certain
703      major-mode per repository.  So when a buffer is being unlocked and
704      another unlocked buffer already exists for that mode and
705      repository, then the former buffer is instead deleted and the
706      latter is displayed in its place.
707
708 * Menu:
709
710 * Switching Buffers::
711 * Naming Buffers::
712 * Quitting Windows::
713 * Automatic Refreshing of Magit Buffers::
714 * Automatic Saving of File-Visiting Buffers::
715 * Automatic Reverting of File-Visiting Buffers::
716
717 
718 File: magit.info,  Node: Switching Buffers,  Next: Naming Buffers,  Up: Modes and Buffers
719
720 4.1.1 Switching Buffers
721 -----------------------
722
723  -- Function: magit-display-buffer buffer
724
725      This function is a wrapper around ‘display-buffer’ and is used to
726      display any Magit buffer.  It displays BUFFER in some window and,
727      unlike ‘display-buffer’, also selects that window, provided
728      ‘magit-display-buffer-noselect’ is ‘nil’.  It also runs the hooks
729      mentioned below.
730
731  -- Variable: magit-display-buffer-noselect
732
733      When this is non-nil, then ‘magit-display-buffer’ only displays the
734      buffer but forgoes also selecting the window.  This variable should
735      not be set globally, it is only intended to be let-bound, by code
736      that automatically updates "the other window".  This is used for
737      example when the revision buffer is updated when you move inside
738      the log buffer.
739
740  -- User Option: magit-display-buffer-function
741
742      The function specified here is called by ‘magit-display-buffer’
743      with one argument, a buffer, to actually display that buffer.  This
744      function should call ‘display-buffer’ with that buffer as first and
745      a list of display actions as second argument.
746
747      Magit provides several functions, listed below, that are suitable
748      values for this option.  If you want to use different rules, then a
749      good way of doing that is to start with a copy of one of these
750      functions and then adjust it to your needs.
751
752      Instead of using a wrapper around ‘display-buffer’, that function
753      itself can be used here, in which case the display actions have to
754      be specified by adding them to ‘display-buffer-alist’ instead.
755
756      To learn about display actions, see *note (elisp)Choosing a Window
757      for Display::.
758
759  -- Function: magit-display-buffer-traditional buffer
760
761      This function is the current default value of the option
762      ‘magit-display-buffer-function’.  Before that option and this
763      function were added, the behavior was hard-coded in many places all
764      over the code base but now all the rules are contained in this one
765      function (except for the "noselect" special case mentioned above).
766
767  -- Function: magit-display-buffer-same-window-except-diff-v1
768
769      This function displays most buffers in the currently selected
770      window.  If a buffer’s mode derives from ‘magit-diff-mode’ or
771      ‘magit-process-mode’, it is displayed in another window.
772
773  -- Function: magit-display-buffer-fullframe-status-v1
774
775      This function fills the entire frame when displaying a status
776      buffer.  Otherwise, it behaves like
777      ‘magit-display-buffer-traditional’.
778
779  -- Function: magit-display-buffer-fullframe-status-topleft-v1
780
781      This function fills the entire frame when displaying a status
782      buffer.  It behaves like ‘magit-display-buffer-fullframe-status-v1’
783      except that it displays buffers that derive from ‘magit-diff-mode’
784      or ‘magit-process-mode’ to the top or left of the current buffer
785      rather than to the bottom or right.  As a result, Magit buffers
786      tend to pop up on the same side as they would if
787      ‘magit-display-buffer-traditional’ were in use.
788
789  -- Function: magit-display-buffer-fullcolumn-most-v1
790
791      This function displays most buffers so that they fill the entire
792      height of the frame.  However, the buffer is displayed in another
793      window if (1) the buffer’s mode derives from ‘magit-process-mode’,
794      or (2) the buffer’s mode derives from ‘magit-diff-mode’, provided
795      that the mode of the current buffer derives from ‘magit-log-mode’
796      or ‘magit-cherry-mode’.
797
798  -- User Option: magit-pre-display-buffer-hook
799
800      This hook is run by ‘magit-display-buffer’ before displaying the
801      buffer.
802
803  -- Function: magit-save-window-configuration
804
805      This function saves the current window configuration.  Later when
806      the buffer is buried, it may be restored by
807      ‘magit-restore-window-configuration’.
808
809  -- User Option: magit-post-display-buffer-hook
810
811      This hook is run by ‘magit-display-buffer’ after displaying the
812      buffer.
813
814  -- Function: magit-maybe-set-dedicated
815
816      This function remembers if a new window had to be created to
817      display the buffer, or whether an existing window was reused.  This
818      information is later used by ‘magit-mode-quit-window’, to determine
819      whether the window should be deleted when its last Magit buffer is
820      buried.
821
822 
823 File: magit.info,  Node: Naming Buffers,  Next: Quitting Windows,  Prev: Switching Buffers,  Up: Modes and Buffers
824
825 4.1.2 Naming Buffers
826 --------------------
827
828  -- User Option: magit-generate-buffer-name-function
829
830      The function used to generate the names of Magit buffers.
831
832      Such a function should take the options
833      ‘magit-uniquify-buffer-names’ as well as ‘magit-buffer-name-format’
834      into account.  If it doesn’t, then should be clearly stated in the
835      doc-string.  And if it supports %-sequences beyond those mentioned
836      in the doc-string of the option ‘magit-buffer-name-format’, then
837      its own doc-string should describe the additions.
838
839  -- Function: magit-generate-buffer-name-default-function mode
840
841      This function returns a buffer name suitable for a buffer whose
842      major-mode is MODE and which shows information about the repository
843      in which ‘default-directory’ is located.
844
845      This function uses ‘magit-buffer-name-format’ and supporting all of
846      the %-sequences mentioned the documentation of that option.  It
847      also respects the option ‘magit-uniquify-buffer-names’.
848
849  -- User Option: magit-buffer-name-format
850
851      The format string used to name Magit buffers.
852
853      At least the following %-sequences are supported:
854
855         • ‘%m’
856
857           The name of the major-mode, but with the ‘-mode’ suffix
858           removed.
859
860         • ‘%M’
861
862           Like ‘%m’ but abbreviate ‘magit-status-mode’ as ‘magit’.
863
864         • ‘%v’
865
866           The value the buffer is locked to, in parentheses, or an empty
867           string if the buffer is not locked to a value.
868
869         • ‘%V’
870
871           Like ‘%v’, but the string is prefixed with a space, unless it
872           is an empty string.
873
874         • ‘%t’
875
876           The top-level directory of the working tree of the repository,
877           or if ‘magit-uniquify-buffer-names’ is non-nil an abbreviation
878           of that.
879
880         • ‘%x’
881
882           If ‘magit-uniquify-buffer-names’ is nil "*", otherwise the
883           empty string.  Due to limitations of the ‘uniquify’ package,
884           buffer names must end with the path.
885
886         • ‘%T’
887
888           Obsolete, use "%t%x" instead.  Like ‘%t’, but append an
889           asterisk if and only if ‘magit-uniquify-buffer-names’ is nil.
890
891      The value should always contain ‘%m’ or ‘%M’, ‘%v’ or ‘%V’, and
892      ‘%t’ (or the obsolete ‘%T’).  If ‘magit-uniquify-buffer-names’ is
893      non-nil, then the value must end with ‘%t’ or ‘%t%x’ (or the
894      obsolete ‘%T’).  See issue #2841.
895
896  -- User Option: magit-uniquify-buffer-names
897
898      This option controls whether the names of Magit buffers are
899      uniquified.  If the names are not being uniquified, then they
900      contain the full path of the top-level of the working tree of the
901      corresponding repository.  If they are being uniquified, then they
902      end with the basename of the top-level, or if that would conflict
903      with the name used for other buffers, then the names of all these
904      buffers are adjusted until they no longer conflict.
905
906      This is done using the ‘uniquify’ package; customize its options to
907      control how buffer names are uniquified.
908
909 
910 File: magit.info,  Node: Quitting Windows,  Next: Automatic Refreshing of Magit Buffers,  Prev: Naming Buffers,  Up: Modes and Buffers
911
912 4.1.3 Quitting Windows
913 ----------------------
914
915 ‘q’     (‘magit-mode-bury-buffer’)
916
917      This command buries the current Magit buffer.  With a prefix
918      argument, it instead kills the buffer.
919
920  -- User Option: magit-bury-buffer-function
921
922      The function used to actually bury or kill the current buffer.
923
924      ‘magit-mode-bury-buffer’ calls this function with one argument.  If
925      the argument is non-nil, then the function has to kill the current
926      buffer.  Otherwise it has to bury it alive.  The default value
927      currently is ‘magit-restore-window-configuration’.
928
929  -- Function: magit-restore-window-configuration kill-buffer
930
931      Bury or kill the current buffer using ‘quit-window’, which is
932      called with KILL-BUFFER as first and the selected window as second
933      argument.
934
935      Then restore the window configuration that existed right before the
936      current buffer was displayed in the selected frame.  Unfortunately
937      that also means that point gets adjusted in all the buffers, which
938      are being displayed in the selected frame.
939
940  -- Function: magit-mode-quit-window kill-buffer
941
942      Bury or kill the current buffer using ‘quit-window’, which is
943      called with KILL-BUFFER as first and the selected window as second
944      argument.
945
946      Then, if the window was originally created to display a Magit
947      buffer and the buried buffer was the last remaining Magit buffer
948      that was ever displayed in the window, then that is deleted.
949
950 
951 File: magit.info,  Node: Automatic Refreshing of Magit Buffers,  Next: Automatic Saving of File-Visiting Buffers,  Prev: Quitting Windows,  Up: Modes and Buffers
952
953 4.1.4 Automatic Refreshing of Magit Buffers
954 -------------------------------------------
955
956 After running a command which may change the state of the current
957 repository, the current Magit buffer and the corresponding status buffer
958 are refreshed.  The status buffer may optionally be automatically
959 refreshed whenever a buffer is saved to a file inside the respective
960 repository.
961
962    Automatically refreshing Magit buffers ensures that the displayed
963 information is up-to-date most of the time but can lead to a noticeable
964 delay in big repositories.  Other Magit buffers are not refreshed to
965 keep the delay to a minimum and also because doing so can sometimes be
966 undesirable.
967
968    Buffers can also be refreshed explicitly, which is useful in buffers
969 that weren’t current during the last refresh and after changes were made
970 to the repository outside of Magit.
971
972 ‘g’     (‘magit-refresh’)
973
974      This command refreshes the current buffer if its major mode derives
975      from ‘magit-mode’ as well as the corresponding status buffer.
976
977      If the option ‘magit-revert-buffers’ calls for it, then it also
978      reverts all unmodified buffers that visit files being tracked in
979      the current repository.
980
981 ‘G’     (‘magit-refresh-all’)
982
983      This command refreshes all Magit buffers belonging to the current
984      repository and also reverts all unmodified buffers that visit files
985      being tracked in the current repository.
986
987      The file-visiting buffers are always reverted, even if
988      ‘magit-revert-buffers’ is nil.
989
990  -- User Option: magit-refresh-buffer-hook
991
992      This hook is run in each Magit buffer that was refreshed during the
993      current refresh - normally the current buffer and the status
994      buffer.
995
996  -- User Option: magit-refresh-status-buffer
997
998      When this option is non-nil, then the status buffer is
999      automatically refreshed after running git for side-effects, in
1000      addition to the current Magit buffer, which is always refreshed
1001      automatically.
1002
1003      Only set this to nil after exhausting all other options to improve
1004      performance.
1005
1006  -- Function: magit-after-save-refresh-status
1007
1008      This function is intended to be added to ‘after-save-hook’.  After
1009      doing that the corresponding status buffer is refreshed whenever a
1010      buffer is saved to a file inside a repository.
1011
1012      Note that refreshing a Magit buffer is done by re-creating its
1013      contents from scratch, which can be slow in large repositories.  If
1014      you are not satisfied with Magit’s performance, then you should
1015      obviously not add this function to that hook.
1016
1017 
1018 File: magit.info,  Node: Automatic Saving of File-Visiting Buffers,  Next: Automatic Reverting of File-Visiting Buffers,  Prev: Automatic Refreshing of Magit Buffers,  Up: Modes and Buffers
1019
1020 4.1.5 Automatic Saving of File-Visiting Buffers
1021 -----------------------------------------------
1022
1023 File-visiting buffers are by default saved at certain points in time.
1024 This doesn’t guarantee that Magit buffers are always up-to-date, but,
1025 provided one only edits files by editing them in Emacs and uses only
1026 Magit to interact with Git, one can be fairly confident.  When in doubt
1027 or after outside changes, type ‘g’ (‘magit-refresh’) to save and refresh
1028 explicitly.
1029
1030  -- User Option: magit-save-repository-buffers
1031
1032      This option controls whether file-visiting buffers are saved before
1033      certain events.
1034
1035      If this is non-nil then all modified file-visiting buffers
1036      belonging to the current repository may be saved before running
1037      commands, before creating new Magit buffers, and before explicitly
1038      refreshing such buffers.  If this is ‘dontask’ then this is done
1039      without user intervention.  If it is ‘t’ then the user has to
1040      confirm each save.
1041
1042 
1043 File: magit.info,  Node: Automatic Reverting of File-Visiting Buffers,  Prev: Automatic Saving of File-Visiting Buffers,  Up: Modes and Buffers
1044
1045 4.1.6 Automatic Reverting of File-Visiting Buffers
1046 --------------------------------------------------
1047
1048 By default Magit automatically reverts buffers that are visiting files
1049 that are being tracked in a Git repository, after they have changed on
1050 disk.  When using Magit one often changes files on disk by running git,
1051 i.e.  "outside Emacs", making this a rather important feature.
1052
1053    For example, if you discard a change in the status buffer, then that
1054 is done by running ‘git apply --reverse ...’, and Emacs considers the
1055 file to have "changed on disk".  If Magit did not automatically revert
1056 the buffer, then you would have to type ‘M-x revert-buffer RET RET’ in
1057 the visiting buffer before you could continue making changes.
1058
1059  -- User Option: magit-auto-revert-mode
1060
1061      When this mode is enabled, then buffers that visit tracked files,
1062      are automatically reverted after the visited files changed on disk.
1063
1064  -- User Option: global-auto-revert-mode
1065
1066      When this mode is enabled, then any file-visiting buffer is
1067      automatically reverted after the visited file changed on disk.
1068
1069      If you like buffers that visit tracked files to be automatically
1070      reverted, then you might also like any buffer to be reverted, not
1071      just those visiting tracked files.  If that is the case, then
1072      enable this mode _instead of_ ‘magit-auto-revert-mode’.
1073
1074  -- User Option: magit-auto-revert-immediately
1075
1076      This option controls whether Magit reverts buffers immediately.
1077
1078      If this is non-nil and either ‘global-auto-revert-mode’ or
1079      ‘magit-auto-revert-mode’ is enabled, then Magit immediately reverts
1080      buffers by explicitly calling ‘auto-revert-buffers’ after running
1081      git for side-effects.
1082
1083      If ‘auto-revert-use-notify’ is non-nil (and file notifications are
1084      actually supported), then ‘magit-auto-revert-immediately’ does not
1085      have to be non-nil, because the reverts happen immediately anyway.
1086
1087      If ‘magit-auto-revert-immediately’ and ‘auto-revert-use-notify’ are
1088      both ‘nil’, then reverts happen after ‘auto-revert-interval’
1089      seconds of user inactivity.  That is not desirable.
1090
1091  -- User Option: auto-revert-use-notify
1092
1093      This option controls whether file notification functions should be
1094      used.  Note that this variable unfortunately defaults to ‘t’ even
1095      on systems on which file notifications cannot be used.
1096
1097  -- User Option: magit-auto-revert-tracked-only
1098
1099      This option controls whether ‘magit-auto-revert-mode’ only reverts
1100      tracked files or all files that are located inside Git
1101      repositories, including untracked files and files located inside
1102      Git’s control directory.
1103
1104  -- Command: auto-revert-mode
1105
1106      The global mode ‘magit-auto-revert-mode’ works by turning on this
1107      local mode in the appropriate buffers (but
1108      ‘global-auto-revert-mode’ is implemented differently).  You can
1109      also turn it on or off manually, which might be necessary if Magit
1110      does not notice that a previously untracked file now is being
1111      tracked or vice-versa.
1112
1113  -- User Option: auto-revert-stop-on-user-input
1114
1115      This option controls whether the arrival of user input suspends the
1116      automatic reverts for ‘auto-revert-interval’ seconds.
1117
1118  -- User Option: auto-revert-interval
1119
1120      This option controls for how many seconds Emacs waits before
1121      resuming suspended reverts.
1122
1123  -- User Option: auto-revert-buffer-list-filter
1124
1125      This option specifies an additional filter used by
1126      ‘auto-revert-buffers’ to determine whether a buffer should be
1127      reverted or not.
1128
1129      This option is provided by ‘magit’, which also redefines
1130      ‘auto-revert-buffers’ to respect it.  Magit users who do not turn
1131      on the local mode ‘auto-revert-mode’ themselves, are best served by
1132      setting the value to ‘magit-auto-revert-repository-buffers-p’.
1133
1134      However the default is nil, to not disturb users who do use the
1135      local mode directly.  If you experience delays when running Magit
1136      commands, then you should consider using one of the predicates
1137      provided by Magit - especially if you also use Tramp.
1138
1139      Users who do turn on ‘auto-revert-mode’ in buffers in which Magit
1140      doesn’t do that for them, should likely not use any filter.  Users
1141      who turn on ‘global-auto-revert-mode’, do not have to worry about
1142      this option, because it is disregarded if the global mode is
1143      enabled.
1144
1145  -- User Option: auto-revert-verbose
1146
1147      This option controls whether Emacs reports when a buffer has been
1148      reverted.
1149
1150    The options with the ‘auto-revert-’ prefix are located in the Custom
1151 group named ‘auto-revert’.  The other, magit-specific, options are
1152 located in the ‘magit’ group.
1153
1154 * Menu:
1155
1156 * Risk of Reverting Automatically::
1157
1158 
1159 File: magit.info,  Node: Risk of Reverting Automatically,  Up: Automatic Reverting of File-Visiting Buffers
1160
1161 Risk of Reverting Automatically
1162 ...............................
1163
1164 For the vast majority users automatically reverting file-visiting
1165 buffers after they have changed on disk is harmless.
1166
1167    If a buffer is modified (i.e.  it contains changes that haven’t been
1168 saved yet), then Emacs would refuse to automatically revert it.  If you
1169 save a previously modified buffer, then that results in what is seen by
1170 Git as an uncommitted change.  Git would then refuse to carry out any
1171 commands that would cause these changes to be lost.  In other words, if
1172 there is anything that could be lost, then either Git or Emacs would
1173 refuse to discard the changes.
1174
1175    However if you do use file-visiting buffers as a sort of ad hoc
1176 "staging area", then the automatic reverts could potentially cause data
1177 loss.  So far I have only heard from one user who uses such a workflow.
1178
1179    An example: You visit some file in a buffer, edit it, and save the
1180 changes.  Then, outside of Emacs (or at least not using Magit or by
1181 saving the buffer) you change the file on disk again.  At this point the
1182 buffer is the only place where the intermediate version still exists.
1183 You have saved the changes to disk, but that has since been overwritten.
1184 Meanwhile Emacs considers the buffer to be unmodified (because you have
1185 not made any changes to it since you last saved it to the visited file)
1186 and therefore would not object to it being automatically reverted.  At
1187 this point an Auto-Revert mode would kick in.  It would check whether
1188 the buffer is modified and since that is not the case it would revert
1189 it.  The intermediate version would be lost.  (Actually you could still
1190 get it back using the ‘undo’ command.)
1191
1192    If your workflow depends on Emacs preserving the intermediate version
1193 in the buffer, then you have to disable all Auto-Revert modes.  But
1194 please consider that such a workflow would be dangerous even without
1195 using an Auto-Revert mode, and should therefore be avoided.  If Emacs
1196 crashed or if you quit Emacs by mistake, then you would also lose the
1197 buffer content.  There would be no autosave file still containing the
1198 intermediate version (because that was deleted when you saved the
1199 buffer) and you would not be asked whether you want to save the buffer
1200 (because it isn’t modified).
1201
1202 
1203 File: magit.info,  Node: Sections,  Next: Popup Buffers and Prefix Commands,  Prev: Modes and Buffers,  Up: Interface Concepts
1204
1205 4.2 Sections
1206 ============
1207
1208 Magit buffers are organized into nested sections, which can be collapsed
1209 and expanded, similar to how sections are handled in Org mode.  Each
1210 section also has a type, and some sections also have a value.  For each
1211 section type there can also be a local keymap, shared by all sections of
1212 that type.
1213
1214    Taking advantage of the section value and type, many commands operate
1215 on the current section, or when the region is active and selects
1216 sections of the same type, all of the selected sections.  Commands that
1217 only make sense for a particular section type (as opposed to just
1218 behaving differently depending on the type) are usually bound in section
1219 type keymaps.
1220
1221 * Menu:
1222
1223 * Section Movement::
1224 * Section Visibility::
1225 * Section Hooks::
1226 * Section Types and Values::
1227 * Section Options::
1228
1229 
1230 File: magit.info,  Node: Section Movement,  Next: Section Visibility,  Up: Sections
1231
1232 4.2.1 Section Movement
1233 ----------------------
1234
1235 To move within a section use the usual keys (‘C-p’, ‘C-n’, ‘C-b’, ‘C-f’
1236 etc), whose global bindings are not shadowed.  To move to another
1237 section use the following commands.
1238
1239 ‘p’     (‘magit-section-backward’)
1240
1241      When not at the beginning of a section, then move to the beginning
1242      of the current section.  At the beginning of a section, instead
1243      move to the beginning of the previous visible section.
1244
1245 ‘n’     (‘magit-section-forward’)
1246
1247      Move to the beginning of the next visible section.
1248
1249 ‘M-p’     (‘magit-section-backward-siblings’)
1250
1251      Move to the beginning of the previous sibling section.  If there is
1252      no previous sibling section, then move to the parent section
1253      instead.
1254
1255 ‘M-n’     (‘magit-section-forward-siblings’)
1256
1257      Move to the beginning of the next sibling section.  If there is no
1258      next sibling section, then move to the parent section instead.
1259
1260 ‘^’     (‘magit-section-up’)
1261
1262      Move to the beginning of the parent of the current section.
1263
1264    The above commands all call the hook ‘magit-section-movement-hook’.
1265 Any of the functions listed below can be used as members of this hook.
1266
1267  -- Variable: magit-section-movement-hook
1268
1269      This hook is run by all of the above movement commands, after
1270      arriving at the destination.
1271
1272  -- Function: magit-hunk-set-window-start
1273
1274      This hook function ensures that the beginning of the current
1275      section is visible, provided it is a ‘hunk’ section.  Otherwise, it
1276      does nothing.  This function is a member of the hook’s default
1277      value.
1278
1279  -- Function: magit-section-set-window-start
1280
1281      This hook function ensures that the beginning of the current
1282      section is visible, regardless of the section’s type.  If you add
1283      this to ‘magit-section-movement-hook’, then you must remove the
1284      hunk-only variant in turn.
1285
1286  -- Function: magit-log-maybe-show-more-commits
1287
1288      This hook function only has an effect in log buffers, and ‘point’
1289      is on the "show more" section.  If that is the case, then it
1290      doubles the number of commits that are being shown.  This function
1291      is a member of the hook’s default value.
1292
1293  -- Function: magit-log-maybe-update-revision-buffer
1294
1295      When moving inside a log buffer, then this function updates the
1296      revision buffer, provided it is already being displayed in another
1297      window of the same frame.  This function is a member of the hook’s
1298      default value.
1299
1300  -- Function: magit-log-maybe-update-blob-buffer
1301
1302      When moving inside a log buffer and another window of the same
1303      frame displays a blob buffer, then this function instead displays
1304      the blob buffer for the commit at point in that window.
1305
1306  -- Function: magit-status-maybe-update-revision-buffer
1307
1308      When moving inside a status buffer, then this function updates the
1309      revision buffer, provided it is already being displayed in another
1310      window of the same frame.
1311
1312  -- Function: magit-status-maybe-update-blob-buffer
1313
1314      When moving inside a status buffer and another window of the same
1315      frame displays a blob buffer, then this function instead displays
1316      the blob buffer for the commit at point in that window.
1317
1318  -- User Option: magit-update-other-window-delay
1319
1320      Delay before automatically updating the other window.
1321
1322      When moving around in certain buffers, then certain other buffers,
1323      which are being displayed in another window, may optionally be
1324      updated to display information about the section at point.
1325
1326      When holding down a key to move by more than just one section, then
1327      that would update that buffer for each section on the way.  To
1328      prevent that, updating the revision buffer is delayed, and this
1329      option controls for how long.  For optimal experience you might
1330      have to adjust this delay and/or the keyboard repeat rate and delay
1331      of your graphical environment or operating system.
1332
1333 
1334 File: magit.info,  Node: Section Visibility,  Next: Section Hooks,  Prev: Section Movement,  Up: Sections
1335
1336 4.2.2 Section Visibility
1337 ------------------------
1338
1339 Magit provides many commands for changing the visibility of sections,
1340 but all you need to get started are the next two.
1341
1342 ‘TAB’     (‘magit-section-toggle’)
1343
1344      Toggle the visibility of the body of the current section.
1345
1346 ‘C-<tab>’     (‘magit-section-cycle’)
1347
1348      Cycle the visibility of current section and its children.
1349
1350 ‘M-<tab>’     (‘magit-section-cycle-diffs’)
1351
1352      Cycle the visibility of diff-related sections in the current
1353      buffer.
1354
1355 ‘S-<tab>’     (‘magit-section-cycle-global’)
1356
1357      Cycle the visibility of all sections in the current buffer.
1358
1359 ‘1’     (‘magit-section-show-level-1’)
1360 ‘2’     (‘magit-section-show-level-2’)
1361 ‘3’     (‘magit-section-show-level-3’)
1362 ‘4’     (‘magit-section-show-level-4’)
1363
1364      Show sections surrounding the current section up to level N.
1365
1366 ‘M-1’     (‘magit-section-show-level-1-all’)
1367 ‘M-2’     (‘magit-section-show-level-2-all’)
1368 ‘M-3’     (‘magit-section-show-level-3-all’)
1369 ‘M-4’     (‘magit-section-show-level-4-all’)
1370
1371      Show all sections up to level N.
1372
1373    Some functions, which are used to implement the above commands, are
1374 also exposed as commands themselves.  By default no keys are bound to
1375 these commands, as they are generally perceived to be much less useful.
1376 But your mileage may vary.
1377
1378  -- Command: magit-section-show
1379
1380      Show the body of the current section.
1381
1382  -- Command: magit-section-hide
1383
1384      Hide the body of the current section.
1385
1386  -- Command: magit-section-show-headings
1387
1388      Recursively show headings of children of the current section.  Only
1389      show the headings.  Previously shown text-only bodies are hidden.
1390
1391  -- Command: magit-section-show-children
1392
1393      Recursively show the bodies of children of the current section.
1394      With a prefix argument show children down to the level of the
1395      current section, and hide deeper children.
1396
1397  -- Command: magit-section-hide-children
1398
1399      Recursively hide the bodies of children of the current section.
1400
1401  -- Command: magit-section-toggle-children
1402
1403      Toggle visibility of bodies of children of the current section.
1404
1405    When a buffer is first created then some sections are shown expanded
1406 while others are not.  This is hard coded.  When a buffer is refreshed
1407 then the previous visibility is preserved.  The initial visibility of
1408 certain sections can also be overwritten using the hook
1409 ‘magit-section-set-visibility-hook’.
1410
1411  -- User Option: magit-section-initial-visibility-alist
1412
1413      This options can be used to override the initial visibility of
1414      sections.  In the future it will also be used to define the
1415      defaults, but currently a section’s default is still hardcoded.
1416
1417      The value is an alist.  Each element maps a section type or lineage
1418      to the initial visibility state for such sections.  The state has
1419      to be one of ‘show’ or ‘hide’, or a function that returns one of
1420      these symbols.  A function is called with the section as the only
1421      argument.
1422
1423      Use the command ‘magit-describe-section-briefly’ to determine a
1424      section’s lineage or type.  The vector in the output is the section
1425      lineage and the type is the first element of that vector.
1426      Wildcards can be used, see ‘magit-section-match’.
1427
1428  -- User Option: magit-section-cache-visibility
1429
1430      This option controls for which sections the previous visibility
1431      state should be restored if a section disappears and later appears
1432      again.  The value is a boolean or a list of section types.  If t,
1433      then the visibility of all sections is cached.  Otherwise this is
1434      only done for sections whose type matches one of the listed types.
1435
1436      This requires that the function ‘magit-section-cached-visibility’
1437      is a member of ‘magit-section-set-visibility-hook’.
1438
1439  -- Variable: magit-section-set-visibility-hook
1440
1441      This hook is run when first creating a buffer and also when
1442      refreshing an existing buffer, and is used to determine the
1443      visibility of the section currently being inserted.
1444
1445      Each function is called with one argument, the section being
1446      inserted.  It should return ‘hide’ or ‘show’, or to leave the
1447      visibility undefined ‘nil’.  If no function decides on the
1448      visibility and the buffer is being refreshed, then the visibility
1449      is preserved; or if the buffer is being created, then the hard
1450      coded default is used.
1451
1452      Usually this should only be used to set the initial visibility but
1453      not during refreshes.  If ‘magit-insert-section--oldroot’ is
1454      non-nil, then the buffer is being refreshed and these functions
1455      should immediately return ‘nil’.
1456
1457 
1458 File: magit.info,  Node: Section Hooks,  Next: Section Types and Values,  Prev: Section Visibility,  Up: Sections
1459
1460 4.2.3 Section Hooks
1461 -------------------
1462
1463 Which sections are inserted into certain buffers is controlled with
1464 hooks.  This includes the status and the refs buffers.  For other
1465 buffers, e.g.  log and diff buffers, this is not possible.  The command
1466 ‘magit-describe-section’ can be used to see which hook (if any) was
1467 responsible for inserting the section at point.
1468
1469    For buffers whose sections can be customized by the user, a hook
1470 variable called ‘magit-TYPE-sections-hook’ exists.  This hook should be
1471 changed using ‘magit-add-section-hook’.  Avoid using ‘add-hooks’ or the
1472 Custom interface.
1473
1474    The various available section hook variables are described later in
1475 this manual along with the appropriate "section inserter functions".
1476
1477  -- Function: magit-add-section-hook hook function &optional at append
1478           local
1479
1480      Add the function FUNCTION to the value of section hook HOOK.
1481
1482      Add FUNCTION at the beginning of the hook list unless optional
1483      APPEND is non-nil, in which case FUNCTION is added at the end.  If
1484      FUNCTION already is a member then move it to the new location.
1485
1486      If optional AT is non-nil and a member of the hook list, then add
1487      FUNCTION next to that instead.  Add before or after AT, or replace
1488      AT with FUNCTION depending on APPEND.  If APPEND is the symbol
1489      ‘replace’, then replace AT with FUNCTION.  For any other non-nil
1490      value place FUNCTION right after AT.  If nil, then place FUNCTION
1491      right before AT.  If FUNCTION already is a member of the list but
1492      AT is not, then leave FUNCTION where ever it already is.
1493
1494      If optional LOCAL is non-nil, then modify the hook’s buffer-local
1495      value rather than its global value.  This makes the hook local by
1496      copying the default value.  That copy is then modified.
1497
1498      HOOK should be a symbol.  If HOOK is void, it is first set to nil.
1499      HOOK’s value must not be a single hook function.  FUNCTION should
1500      be a function that takes no arguments and inserts one or multiple
1501      sections at point, moving point forward.  FUNCTION may choose not
1502      to insert its section(s), when doing so would not make sense.  It
1503      should not be abused for other side-effects.
1504
1505    To remove a function from a section hook, use ‘remove-hook’.
1506
1507 
1508 File: magit.info,  Node: Section Types and Values,  Next: Section Options,  Prev: Section Hooks,  Up: Sections
1509
1510 4.2.4 Section Types and Values
1511 ------------------------------
1512
1513 Each section has a type, for example ‘hunk’, ‘file’, and ‘commit’.
1514 Instances of certain section types also have a value.  The value of a
1515 section of type ‘file’, for example, is a file name.
1516
1517    Users usually do not have to worry about a section’s type and value,
1518 but knowing them can be handy at times.
1519
1520 ‘M-x magit-describe-section-briefly’     (‘magit-describe-section-briefly’)
1521
1522      Show information about the section at point in the echo area, as
1523      "#<magit-section VALUE [TYPE PARENT-TYPE...] BEGINNING-END>".
1524
1525    Many commands behave differently depending on the type of the section
1526 at point and/or somehow consume the value of that section.  But that is
1527 only one of the reasons why the same key may do something different,
1528 depending on what section is current.
1529
1530    Additionally for each section type a keymap *might* be defined, named
1531 ‘magit-TYPE-section-map’.  That keymap is used as text property keymap
1532 of all text belonging to any section of the respective type.  If such a
1533 map does not exist for a certain type, then you can define it yourself,
1534 and it will automatically be used.
1535
1536 
1537 File: magit.info,  Node: Section Options,  Prev: Section Types and Values,  Up: Sections
1538
1539 4.2.5 Section Options
1540 ---------------------
1541
1542 This section describes options that have an effect on more than just a
1543 certain type of sections.  As you can see there are not many of those.
1544
1545  -- User Option: magit-section-show-child-count
1546
1547      Whether to append the number of children to section headings.  This
1548      only affects sections that could benefit from this information.
1549
1550 
1551 File: magit.info,  Node: Popup Buffers and Prefix Commands,  Next: Completion Confirmation and the Selection,  Prev: Sections,  Up: Interface Concepts
1552
1553 4.3 Popup Buffers and Prefix Commands
1554 =====================================
1555
1556 Many Magit commands are implemented using *popup buffers*.  First the
1557 user invokes a *popup* or *prefix* command, which causes a popup buffer
1558 with the available *infix* arguments and *suffix* commands to be
1559 displayed.  The user then optionally toggles/sets some arguments and
1560 finally invokes one of the suffix commands.
1561
1562    This is implemented in the library ‘magit-popup’.  Earlier releases
1563 used the library ‘magit-key-mode’.  A future release will switch to a
1564 yet-to-be-written successor, which will likely be named ‘transient’.
1565
1566    Because ‘magit-popup’ can also be used by other packages without
1567 having to depend on all of Magit, it is documented in its own manual.
1568 See *note (magit-popup)Top::.
1569
1570 ‘C-c C-c’     (‘magit-dispatch-popup’)
1571
1572      This popup command shows a buffer featuring all other Magit popup
1573      commands as well as some other commands that are not popup commands
1574      themselves.
1575
1576    This command is also, or especially, useful outside Magit buffers, so
1577 you should setup a global binding:
1578
1579      (global-set-key (kbd "C-x M-g") 'magit-dispatch-popup)
1580
1581    Most popups set their initial arguments according to the
1582 corresponding ‘magit-*-arguments’ variable.  Two popups, the log and
1583 diff popups (see *note Logging:: and *note Diffing::), may behave a bit
1584 differently, depending on the value of ‘magit-use-sticky-arguments’.
1585
1586  -- User Option: magit-use-sticky-arguments
1587
1588      This option controls how diff and log commands reuse arguments from
1589      existing buffers.
1590
1591      When ‘t’ (the default value), the log or diff popup reuses the
1592      arguments from the current repository’s log or diff buffer,
1593      respectively.  When no log or diff buffer exists for the current
1594      repository, these popups use the default value of
1595      ‘magit-log-arguments’ or ‘magit-diff-arguments’.
1596
1597      When ‘current’, log and diff popups will only reuse the arguments
1598      if the current buffer is derived from ‘magit-log-mode’ or
1599      ‘magit-diff-mode’, respectively.
1600
1601      When ‘nil’, the default value of ‘magit-log-arguments’ or
1602      ‘magit-diff-arguments’ is always used.
1603
1604 
1605 File: magit.info,  Node: Completion Confirmation and the Selection,  Next: Running Git,  Prev: Popup Buffers and Prefix Commands,  Up: Interface Concepts
1606
1607 4.4 Completion, Confirmation and the Selection
1608 ==============================================
1609
1610 * Menu:
1611
1612 * Action Confirmation::
1613 * Completion and Confirmation::
1614 * The Selection::
1615 * The hunk-internal region::
1616 * Support for Completion Frameworks::
1617 * Additional Completion Options::
1618
1619 
1620 File: magit.info,  Node: Action Confirmation,  Next: Completion and Confirmation,  Up: Completion Confirmation and the Selection
1621
1622 4.4.1 Action Confirmation
1623 -------------------------
1624
1625 By default many actions that could potentially lead to data loss have to
1626 be confirmed.  This includes many very common actions, so this can
1627 quickly become annoying.  Many of these actions can be undone and if you
1628 have thought about how to undo certain mistakes, then it should be safe
1629 to disable confirmation for the respective actions.
1630
1631    The option ‘magit-no-confirm’ can be used to tell Magit to perform
1632 certain actions without the user having to confirm them.  Note that
1633 while this option can only be used to disable confirmation for a
1634 specific set of actions, the next section explains another way of
1635 telling Magit to ask fewer questions.
1636
1637  -- User Option: magit-no-confirm
1638
1639      The value of this option is a list of symbols, representing actions
1640      that do not have to be confirmed by the user before being carried
1641      out.
1642
1643      By default many potentially dangerous commands ask the user for
1644      confirmation.  Each of the below symbols stands for an action
1645      which, when invoked unintentionally or without being fully aware of
1646      the consequences, could lead to tears.  In many cases there are
1647      several commands that perform variations of a certain action, so we
1648      don’t use the command names but more generic symbols.
1649
1650         • Applying changes:
1651
1652              • ‘discard’ Discarding one or more changes (i.e.  hunks or
1653                the complete diff for a file) loses that change,
1654                obviously.
1655
1656              • ‘reverse’ Reverting one or more changes can usually be
1657                undone by reverting the reversion.
1658
1659              • ‘stage-all-changes’, ‘unstage-all-changes’ When there are
1660                both staged and unstaged changes, then un-/staging
1661                everything would destroy that distinction.  Of course
1662                that also applies when un-/staging a single change, but
1663                then less is lost and one does that so often that having
1664                to confirm every time would be unacceptable.
1665
1666         • Files:
1667
1668              • ‘delete’ When a file that isn’t yet tracked by Git is
1669                deleted, then it is completely lost, not just the last
1670                changes.  Very dangerous.
1671
1672              • ‘trash’ Instead of deleting a file it can also be move to
1673                the system trash.  Obviously much less dangerous than
1674                deleting it.
1675
1676                Also see option ‘magit-delete-by-moving-to-trash’.
1677
1678              • ‘resurrect’ A deleted file can easily be resurrected by
1679                "deleting" the deletion, which is done using the same
1680                command that was used to delete the same file in the
1681                first place.
1682
1683              • ‘untrack’ Untracking a file can be undone by tracking it
1684                again.
1685
1686              • ‘rename’ Renaming a file can easily be undone.
1687
1688         • Sequences:
1689
1690              • ‘reset-bisect’ Aborting (known to Git as "resetting") a
1691                bisect operation loses all information collected so far.
1692
1693              • ‘abort-rebase’ Aborting a rebase throws away all already
1694                modified commits, but it’s possible to restore those from
1695                the reflog.
1696
1697              • ‘abort-merge’ Aborting a merge throws away all conflict
1698                resolutions which have already been carried out by the
1699                user.
1700
1701              • ‘merge-dirty’ Merging with a dirty worktree can make it
1702                hard to go back to the state before the merge was
1703                initiated.
1704
1705         • References:
1706
1707              • ‘delete-unmerged-branch’ Once a branch has been deleted,
1708                it can only be restored using low-level recovery tools
1709                provided by Git.  And even then the reflog is gone.  The
1710                user always has to confirm the deletion of a branch by
1711                accepting the default choice (or selecting another
1712                branch), but when a branch has not been merged yet, also
1713                make sure the user is aware of that.
1714
1715              • ‘delete-pr-branch’ When deleting a branch that was
1716                created from a pull request and if no other branches
1717                still exist on that remote, then ‘magit-branch-delete’
1718                offers to delete the remote as well.  This should be safe
1719                because it only happens if no other refs exist in the
1720                remotes namespace, and you can recreate the remote if
1721                necessary.
1722
1723              • ‘drop-stashes’ Dropping a stash is dangerous because Git
1724                stores stashes in the reflog.  Once a stash is removed,
1725                there is no going back without using low-level recovery
1726                tools provided by Git.  When a single stash is dropped,
1727                then the user always has to confirm by accepting the
1728                default (or selecting another).  This action only
1729                concerns the deletion of multiple stashes at once.
1730
1731         • Edit published history:
1732
1733           Without adding these symbols here, you will be warned before
1734           editing commits that have already been pushed to one of the
1735           branches listed in ‘magit-published-branches’.
1736
1737              • ‘amend-published’ Affects most commands that amend to
1738                "HEAD".
1739
1740              • ‘rebase-published’ Affects commands that perform
1741                interactive rebases.  This includes commands from the
1742                commit popup that modify a commit other than "HEAD",
1743                namely the various fixup and squash variants.
1744
1745              • ‘edit-published’ Affects the commands
1746                ‘magit-edit-line-commit’ and
1747                ‘magit-diff-edit-hunk-commit’.  These two commands make
1748                it quite easy to accidentally edit a published commit, so
1749                you should think twice before configuring them not to ask
1750                for confirmation.
1751
1752           To disable confirmation completely, add all three symbols here
1753           or set ‘magit-published-branches’ to ‘nil’.
1754
1755         • Various:
1756
1757              • ‘kill-process’ There seldom is a reason to kill a
1758                process.
1759
1760         • Global settings:
1761
1762           Instead of adding all of the above symbols to the value of
1763           this option, you can also set it to the atom ‘t’, which has
1764           the same effect as adding all of the above symbols.  Doing
1765           that most certainly is a bad idea, especially because other
1766           symbols might be added in the future.  So even if you don’t
1767           want to be asked for confirmation for any of these actions,
1768           you are still better of adding all of the respective symbols
1769           individually.
1770
1771           When ‘magit-wip-before-change-mode’ is enabled, then the
1772           following actions can be undone fairly easily: ‘discard’,
1773           ‘reverse’, ‘stage-all-changes’, and ‘unstage-all-changes’.  If
1774           and only if this mode is enabled, then ‘safe-with-wip’ has the
1775           same effect as adding all of these symbols individually.
1776
1777 
1778 File: magit.info,  Node: Completion and Confirmation,  Next: The Selection,  Prev: Action Confirmation,  Up: Completion Confirmation and the Selection
1779
1780 4.4.2 Completion and Confirmation
1781 ---------------------------------
1782
1783 Many Magit commands ask the user to select from a list of possible
1784 things to act on, while offering the most likely choice as the default.
1785 For many of these commands the default is the thing at point, provided
1786 that it actually is a valid thing to act on.  For many commands that act
1787 on a branch, the current branch serves as the default if there is no
1788 branch at point.
1789
1790    These commands combine asking for confirmation and asking for a
1791 target to act on into a single action.  The user can confirm the default
1792 target using ‘RET’ or abort using ‘C-g’.  This is similar to a
1793 ‘y-or-n-p’ prompt, but the keys to confirm or abort differ.
1794
1795    At the same time the user is also given the opportunity to select
1796 another target, which is useful because for some commands and/or in some
1797 situations you might want to select the action before selecting the
1798 target by moving to it.
1799
1800    However you might find that for some commands you always want to use
1801 the default target, if any, or even that you want the command to act on
1802 the default without requiring any confirmation at all.  The option
1803 ‘magit-dwim-selection’ can be used to configure certain commands to that
1804 effect.
1805
1806    Note that when the region is active then many commands act on the
1807 things that are selected using a mechanism based on the region, in many
1808 cases after asking for confirmation.  This region-based mechanism is
1809 called the "selection" and is described in detail in the next section.
1810 When a selection exists that is valid for the invoked command, then that
1811 command never offers to act on something else, and whether it asks for
1812 confirmation is not controlled by this option.
1813
1814    Also note that Magit asks for confirmation of certain actions that
1815 are not coupled with completion (or the selection).  Such dialogs are
1816 also not affected by this option and are described in the previous
1817 section.
1818
1819  -- User Option: magit-dwim-selection
1820
1821    This option can be used to tell certain commands to use the thing at
1822 point instead of asking the user to select a candidate to act on, with
1823 or without confirmation.
1824
1825    The value has the form ‘((COMMAND nil|PROMPT DEFAULT)...)’.
1826
1827    • COMMAND is the command that should not prompt for a choice.  To
1828      have an effect, the command has to use the function
1829      ‘magit-completing-read’ or a utility function which in turn uses
1830      that function.
1831
1832    • If the command uses ‘magit-completing-read’ multiple times, then
1833      PROMPT can be used to only affect one of these uses.  PROMPT, if
1834      non-nil, is a regular expression that is used to match against the
1835      PROMPT argument passed to ‘magit-completing-read’.
1836
1837    • DEFAULT specifies how to use the default.  If it is ‘t’, then the
1838      DEFAULT argument passed to ‘magit-completing-read’ is used without
1839      confirmation.  If it is ‘ask’, then the user is given a chance to
1840      abort.  DEFAULT can also be ‘nil’, in which case the entry has no
1841      effect.
1842
1843 
1844 File: magit.info,  Node: The Selection,  Next: The hunk-internal region,  Prev: Completion and Confirmation,  Up: Completion Confirmation and the Selection
1845
1846 4.4.3 The Selection
1847 -------------------
1848
1849 If the region is active, then many Magit commands act on the things that
1850 are selected using a mechanism based on the region instead of one single
1851 thing.  When the region is not active, then these commands act on the
1852 thing at point or read a single thing to act on.  This is described in
1853 the previous section — this section only covers how multiple things are
1854 selected, how that is visualized, and how certain commands behave when
1855 that is the case.
1856
1857    Magit’s mechanism for selecting multiple things, or rather sections
1858 that represent these things, is based on the Emacs region, but the area
1859 that Magit considers to be selected is typically larger than the region
1860 and additional restrictions apply.
1861
1862    Magit makes a distinction between a region that qualifies as forming
1863 a valid Magit selection and a region that does not.  If the region does
1864 not qualify, then it is displayed as it is in other Emacs buffers.  If
1865 the region does qualify as a Magit selection, then the selection is
1866 always visualized, while the region itself is only visualized if it
1867 begins and ends on the same line.
1868
1869    For a region to qualify as a Magit selection, it must begin in the
1870 heading of one section and end in the heading of a sibling section.
1871 Note that if the end of the region is at the very beginning of section
1872 heading (i.e.  at the very beginning of a line) then that section is
1873 considered to be *inside* the selection.
1874
1875    This is not consistent with how the region is normally treated in
1876 Emacs — if the region ends at the beginning of a line, then that line is
1877 outside the region.  Due to how Magit visualizes the selection, it
1878 should be obvious that this difference exists.
1879
1880    Not every command acts on every valid selection.  Some commands do
1881 not even consider the location of point, others may act on the section
1882 at point but not support acting on the selection, and even commands that
1883 do support the selection of course only do so if it selects things that
1884 they can act on.
1885
1886    This is the main reason why the selection must include the section at
1887 point.  Even if a selection exists, the invoked command may disregard
1888 it, in which case it may act on the current section only.  It is much
1889 safer to only act on the current section but not the other selected
1890 sections than it is to act on the current section *instead* of the
1891 selected sections.  The latter would be much more surprising and if the
1892 current section always is part of the selection, then that cannot
1893 happen.
1894
1895  -- Variable: magit-keep-region-overlay
1896
1897      This variable controls whether the region is visualized as usual
1898      even when a valid Magit selection or a hunk-internal region exists.
1899      See the doc-string for more information.
1900
1901 
1902 File: magit.info,  Node: The hunk-internal region,  Next: Support for Completion Frameworks,  Prev: The Selection,  Up: Completion Confirmation and the Selection
1903
1904 4.4.4 The hunk-internal region
1905 ------------------------------
1906
1907 Somewhat related to the Magit selection described in the previous
1908 section is the hunk-internal region.
1909
1910    Like the selection, the hunk-internal region is based on the Emacs
1911 region but causes that region to not be visualized as it would in other
1912 Emacs buffers, and includes the line on which the region ends even if it
1913 ends at the very beginning of that line.
1914
1915    Unlike the selection, which is based on a region that must begin in
1916 the heading of one section and ends in the section of a sibling section,
1917 the hunk-internal region must begin inside the *body* of a hunk section
1918 and end in the body of the *same* section.
1919
1920    The hunk-internal region is honored by "apply" commands, which can,
1921 among other targets, act on a hunk.  If the hunk-internal region is
1922 active, then such commands act only on the marked part of the hunk
1923 instead of on the complete hunk.
1924
1925 
1926 File: magit.info,  Node: Support for Completion Frameworks,  Next: Additional Completion Options,  Prev: The hunk-internal region,  Up: Completion Confirmation and the Selection
1927
1928 4.4.5 Support for Completion Frameworks
1929 ---------------------------------------
1930
1931 The built-in option ‘completing-read-function’ specifies the low-level
1932 function used by ‘completing-read’ to ask a user to select from a list
1933 of choices.  Its default value is ‘completing-read-default’.
1934 Alternative completion frameworks typically activate themselves by
1935 substituting their own implementation.
1936
1937    Mostly for historic reasons Magit provides a similar option named
1938 ‘magit-completing-read-function’, which only controls the low-level
1939 function used by ‘magit-completing-read’.  This option also makes it
1940 possible to use a different completing mechanism for Magit than for the
1941 rest of Emacs, but doing that is not recommend.
1942
1943    You most likely don’t have to customize the magit-specific option to
1944 use an alternative completion framework.  For example, if you enable
1945 ‘ivy-mode’, then Magit will respect that, and if you enable ‘helm-mode’,
1946 then you are done too.
1947
1948    However if you want to use Ido, then ‘ido-mode’ won’t do the trick.
1949 You will also have to install the ‘ido-completing-read+’ package and use
1950 ‘magit-ido-completing-read’ as ‘magit-completing-read-function’.
1951
1952  -- User Option: magit-completing-read-function
1953
1954      The value of this variable is the low-level function used to
1955      perform completion by code that uses ‘magit-completing-read’ (as
1956      opposed to the built-in ‘completing-read’).
1957
1958      The default value, ‘magit-builtin-completing-read’, is suitable for
1959      the standard completion mechanism, ‘ivy-mode’, and ‘helm-mode’ at
1960      least.
1961
1962      The built-in ‘completing-read’ and ‘completing-read-default’ are
1963      *not* suitable to be used here.  ‘magit-builtin-completing-read’
1964      performs some additional work, and any function used in its place
1965      has to do the same.
1966
1967  -- Function: magit-builtin-completing-read prompt choices &optional
1968           predicate require-match initial-input hist def
1969
1970      This function performs completion using the built-in
1971      ‘completion-read’ and does some additional magit-specific work.
1972
1973  -- Function: magit-ido-completing-read prompt choices &optional
1974           predicate require-match initial-input hist def
1975
1976      This function performs completion using ‘ido-completing-read+’ from
1977      the package by the same name (which you have to explicitly install)
1978      and does some additional magit-specific work.
1979
1980      We have to use ‘ido-completing-read+’ instead of the
1981      ‘ido-completing-read’ that comes with Ido itself, because the
1982      latter, while intended as a drop-in replacement, cannot serve that
1983      purpose because it violates too many of the implicit conventions.
1984
1985  -- Function: magit-completing-read prompt choices &optional predicate
1986           require-match initial-input hist def fallback
1987
1988      This is the function that Magit commands use when they need the
1989      user to select a single thing to act on.  The arguments have the
1990      same meaning as for ‘completing-read’, except for FALLBACK, which
1991      is unique to this function and is described below.
1992
1993      Instead of asking the user to choose from a list of possible
1994      candidates, this function may just return the default specified by
1995      DEF, with or without requiring user confirmation.  Whether that is
1996      the case depends on PROMPT, ‘this-command’ and
1997      ‘magit-dwim-selection’.  See the documentation of the latter for
1998      more information.
1999
2000      If it does read a value in the minibuffer, then this function acts
2001      similar to ‘completing-read’, except for the following:
2002
2003         • If REQUIRE-MATCH is ‘nil’ and the user exits without a choice,
2004           then ‘nil’ is returned instead of an empty string.
2005
2006         • If REQUIRE-MATCH is non-nil and the users exits without a
2007           choice, an user-error is raised.
2008
2009         • FALLBACK specifies a secondary default that is only used if
2010           the primary default DEF is ‘nil’.  The secondary default is
2011           not subject to ‘magit-dwim-selection’ — if DEF is ‘nil’ but
2012           FALLBACK is not, then this function always asks the user to
2013           choose a candidate, just as if both defaults were ‘nil’.
2014
2015         • ": " is appended to PROMPT.
2016
2017         • PROMPT is modified to end with \" (default DEF|FALLBACK): \"
2018           provided that DEF or FALLBACK is non-nil, that neither
2019           ‘ivy-mode’ nor ‘helm-mode’ is enabled, and that
2020           ‘magit-completing-read-function’ is set to its default value
2021           of ‘magit-builtin-completing-read’.
2022
2023 
2024 File: magit.info,  Node: Additional Completion Options,  Prev: Support for Completion Frameworks,  Up: Completion Confirmation and the Selection
2025
2026 4.4.6 Additional Completion Options
2027 -----------------------------------
2028
2029  -- User Option: magit-list-refs-sortby
2030
2031      For many commands that read a ref or refs from the user, the value
2032      of this option can be used to control the order of the refs.  Valid
2033      values include any key accepted by the ‘--sort’ flag of ‘git
2034      for-each-ref’.  By default, refs are sorted alphabetically by their
2035      full name (e.g., "refs/heads/master").
2036
2037 
2038 File: magit.info,  Node: Running Git,  Prev: Completion Confirmation and the Selection,  Up: Interface Concepts
2039
2040 4.5 Running Git
2041 ===============
2042
2043 * Menu:
2044
2045 * Viewing Git Output::
2046 * Git Process Status::
2047 * Running Git Manually::
2048 * Git Executable::
2049 * Global Git Arguments::
2050
2051 
2052 File: magit.info,  Node: Viewing Git Output,  Next: Git Process Status,  Up: Running Git
2053
2054 4.5.1 Viewing Git Output
2055 ------------------------
2056
2057 Magit runs Git either for side-effects (e.g.  when pushing) or to get
2058 some value (e.g.  the name of the current branch).
2059
2060    When Git is run for side-effects, the process output is logged in a
2061 per-repository log buffer, which can be consulted using the
2062 ‘magit-process’ command when things don’t go as expected.
2063
2064    The output/errors for up to ‘magit-process-log-max’ Git commands are
2065 retained.
2066
2067 ‘$’     (‘magit-process’)
2068
2069      This commands displays the process buffer for the current
2070      repository.
2071
2072    Inside that buffer, the usual key bindings for navigating and showing
2073 sections are available.  There is one additional command.
2074
2075 ‘k’     (‘magit-process-kill’)
2076
2077      This command kills the process represented by the section at point.
2078
2079  -- User Option: magit-git-debug
2080
2081      When this is non-nil then the output of all calls to git are logged
2082      in the process buffer.  This is useful when debugging, otherwise it
2083      just negatively affects performance.
2084
2085 
2086 File: magit.info,  Node: Git Process Status,  Next: Running Git Manually,  Prev: Viewing Git Output,  Up: Running Git
2087
2088 4.5.2 Git Process Status
2089 ------------------------
2090
2091 When a Git process is running for side-effects, Magit displays an
2092 indicator in the mode line, using the ‘magit-mode-line-process’ face.
2093
2094    If the Git process exits successfully, the process indicator is
2095 removed from the mode line immediately.
2096
2097    In the case of a Git error, the process indicator is not removed, but
2098 is instead highlighted with the ‘magit-mode-line-process-error’ face,
2099 and the error details from the process buffer are provided as a tooltip
2100 for mouse users.  This error indicator persists in the mode line until
2101 the next magit buffer refresh.
2102
2103    If you do not wish process errors to be indicated in the mode line,
2104 customize the ‘magit-process-display-mode-line-error’ user option.
2105
2106    Process errors are additionally indicated at the top of the status
2107 buffer.
2108
2109 
2110 File: magit.info,  Node: Running Git Manually,  Next: Git Executable,  Prev: Git Process Status,  Up: Running Git
2111
2112 4.5.3 Running Git Manually
2113 --------------------------
2114
2115 While Magit provides many Emacs commands to interact with Git, it does
2116 not cover everything.  In those cases your existing Git knowledge will
2117 come in handy.  Magit provides some commands for running arbitrary Git
2118 commands by typing them into the minibuffer, instead of having to switch
2119 to a shell.
2120
2121 ‘!’     (‘magit-run-popup’)
2122
2123      Shows the popup buffer featuring the below suffix commands.
2124
2125 ‘! !’     (‘magit-git-command-topdir’)
2126
2127      This command reads a command from the user and executes it in the
2128      top-level directory of the current working tree.
2129
2130      The string "git " is used as initial input when prompting the user
2131      for the command.  It can be removed to run another command.
2132
2133 ‘! p’     (‘magit-git-command’)
2134
2135      This command reads a command from the user and executes it in
2136      ‘default-directory’.  With a prefix argument the command is
2137      executed in the top-level directory of the current working tree
2138      instead.
2139
2140      The string "git " is used as initial input when prompting the user
2141      for the command.  It can be removed to run another command.
2142
2143 ‘! s’     (‘magit-shell-command-topdir’)
2144
2145      This command reads a command from the user and executes it in the
2146      top-level directory of the current working tree.
2147
2148 ‘! S’     (‘magit-shell-command’)
2149
2150      This command reads a command from the user and executes it in
2151      ‘default-directory’.  With a prefix argument the command is
2152      executed in the top-level directory of the current working tree
2153      instead.
2154
2155  -- User Option: magit-shell-command-verbose-prompt
2156
2157      Whether the prompt, used by the the above commands when reading a
2158      shell command, shows the directory in which it will be run.
2159
2160    These suffix commands start external gui tools.
2161
2162 ‘! k’     (‘magit-run-gitk’)
2163
2164      This command runs ‘gitk’ in the current repository.
2165
2166 ‘! a’     (‘magit-run-gitk-all’)
2167
2168      This command runs ‘gitk --all’ in the current repository.
2169
2170 ‘! b’     (‘magit-run-gitk-branches’)
2171
2172      This command runs ‘gitk --branches’ in the current repository.
2173
2174 ‘! g’     (‘magit-run-git-gui’)
2175
2176      This command runs ‘git gui’ in the current repository.
2177
2178 
2179 File: magit.info,  Node: Git Executable,  Next: Global Git Arguments,  Prev: Running Git Manually,  Up: Running Git
2180
2181 4.5.4 Git Executable
2182 --------------------
2183
2184 Except on MS Windows, Magit defaults to running Git without specifying
2185 the path to the git executable.  Instead the first executable found by
2186 Emacs on ‘exec-path’ is used (whose value in turn is set based on the
2187 value of the environment variable ‘$PATH’ when Emacs was started).
2188
2189    This has the advantage that it continues to work even when using
2190 Tramp to connect to a remote machine on which the executable is found in
2191 a different place.  The downside is that if you have multiple versions
2192 of Git installed, then you might end up using another version than the
2193 one you think you are using.
2194
2195 ‘M-x magit-version’     (‘magit-version’)
2196
2197      This command shows the currently used versions of Magit, Git, and
2198      Emacs in the echo area.  Non-interactively this just returns the
2199      Magit version.
2200
2201    When the ‘system-type’ is ‘windows-nt’, then ‘magit-git-executable’
2202 is set to an absolute path when Magit is first loaded.  This is
2203 necessary because Git on that platform comes with several wrapper
2204 scripts for the actual git binary, which are also placed on ‘$PATH’, and
2205 using one of these wrappers instead of the binary would degrade
2206 performance horribly.
2207
2208    If Magit doesn’t find the correct executable then you *can* work
2209 around that by setting ‘magit-git-executable’ to an absolute path.  But
2210 note that doing so is a kludge.  It is better to make sure the order in
2211 the environment variable ‘$PATH’ is correct, and that Emacs is started
2212 with that environment in effect.  The command
2213 ‘magit-debug-git-executable’ can be useful to find out where Emacs is
2214 searching for git.  If you have to connect from Windows to a non-Windows
2215 machine, then you must change the value to "git".
2216
2217  -- User Option: magit-git-executable
2218
2219      The git executable used by Magit, either the full path to the
2220      executable or the string "git" to let Emacs find the executable
2221      itself, using the standard mechanism for doing such things.
2222
2223 ‘M-x magit-debug-git-executable’     (‘magit-debug-git-executable’)
2224
2225      Display a buffer with information about ‘magit-git-executable’.
2226
2227 
2228 File: magit.info,  Node: Global Git Arguments,  Prev: Git Executable,  Up: Running Git
2229
2230 4.5.5 Global Git Arguments
2231 --------------------------
2232
2233  -- User Option: magit-git-global-arguments
2234
2235      The arguments set here are used every time the git executable is
2236      run as a subprocess.  They are placed right after the executable
2237      itself and before the git command - as in ‘git HERE... COMMAND
2238      REST’.  For valid arguments see *note (gitman)git::.
2239
2240      Be careful what you add here, especially if you are using Tramp to
2241      connect to servers with ancient Git versions.  Never remove
2242      anything that is part of the default value, unless you really know
2243      what you are doing.  And think very hard before adding something;
2244      it will be used every time Magit runs Git for any purpose.
2245
2246 
2247 File: magit.info,  Node: Inspecting,  Next: Manipulating,  Prev: Interface Concepts,  Up: Top
2248
2249 5 Inspecting
2250 ************
2251
2252 The functionality provided by Magit can be roughly divided into three
2253 groups: inspecting existing data, manipulating existing data or adding
2254 new data, and transferring data.  Of course that is a rather crude
2255 distinction that often falls short, but it’s more useful than no
2256 distinction at all.  This section is concerned with inspecting data, the
2257 next two with manipulating and transferring it.  Then follows a section
2258 about miscellaneous functionality, which cannot easily be fit into this
2259 distinction.
2260
2261    Of course other distinctions make sense too, e.g.  Git’s distinction
2262 between porcelain and plumbing commands, which for the most part is
2263 equivalent to Emacs’ distinction between interactive commands and
2264 non-interactive functions.  All of the sections mentioned before are
2265 mainly concerned with the porcelain – Magit’s plumbing layer is
2266 described later.
2267
2268 * Menu:
2269
2270 * Status Buffer::
2271 * Repository List::
2272 * Logging::
2273 * Diffing::
2274 * Ediffing::
2275 * References Buffer::
2276 * Bisecting::
2277 * Visiting Blobs::
2278 * Blaming::
2279
2280 
2281 File: magit.info,  Node: Status Buffer,  Next: Repository List,  Up: Inspecting
2282
2283 5.1 Status Buffer
2284 =================
2285
2286 While other Magit buffers contain e.g.  one particular diff or one
2287 particular log, the status buffer contains the diffs for staged and
2288 unstaged changes, logs for unpushed and unpulled commits, lists of
2289 stashes and untracked files, and information related to the current
2290 branch.
2291
2292    During certain incomplete operations – for example when a merge
2293 resulted in a conflict – additional information is displayed that helps
2294 proceeding with or aborting the operation.
2295
2296    The command ‘magit-status’ displays the status buffer belonging to
2297 the current repository in another window.  This command is used so often
2298 that it should be bound globally.  We recommend using ‘C-x g’:
2299
2300      (global-set-key (kbd "C-x g") 'magit-status)
2301
2302 ‘C-x g’     (‘magit-status’)
2303
2304      Show the status of the current Git repository in a buffer.  With a
2305      prefix argument prompt for a repository to be shown.  With two
2306      prefix arguments prompt for an arbitrary directory.  If that
2307      directory isn’t the root of an existing repository, then offer to
2308      initialize it as a new repository.
2309
2310  -- User Option: magit-repository-directories
2311
2312      List of directories that are Git repositories or contain Git
2313      repositories.
2314
2315      Each element has the form ‘(DIRECTORY . DEPTH)’.  DIRECTORY has to
2316      be a directory or a directory file-name, a string.  DEPTH, an
2317      integer, specifies the maximum depth to look for Git repositories.
2318      If it is 0, then only add DIRECTORY itself.
2319
2320  -- User Option: magit-repository-directories-depth
2321
2322      The maximum depth to look for Git repositories.  This option is
2323      obsolete and only used for elements of the option
2324      ‘magit-repository-directories’ (which see) that don’t specify the
2325      depth directly.
2326
2327  -- Command: ido-enter-magit-status
2328
2329      From an Ido prompt used to open a file, instead drop into
2330      ‘magit-status’.  This is similar to ‘ido-magic-delete-char’, which,
2331      despite its name, usually causes a Dired buffer to be created.
2332
2333      To make this command available, use something like:
2334
2335           (add-hook 'ido-setup-hook
2336                     (lambda ()
2337                       (define-key ido-completion-map
2338                         (kbd \"C-x g\") 'ido-enter-magit-status)))
2339
2340      Starting with Emacs 25.1 the Ido keymaps are defined just once
2341      instead of every time Ido is invoked, so now you can modify it like
2342      pretty much every other keymap:
2343
2344           (define-key ido-common-completion-map
2345             (kbd \"C-x g\") 'ido-enter-magit-status)
2346
2347 * Menu:
2348
2349 * Status Sections::
2350 * Status Header Sections::
2351 * Status Module Sections::
2352 * Status Options::
2353
2354 
2355 File: magit.info,  Node: Status Sections,  Next: Status Header Sections,  Up: Status Buffer
2356
2357 5.1.1 Status Sections
2358 ---------------------
2359
2360 The contents of status buffers is controlled using the hook
2361 ‘magit-status-sections-hook’.  See *note Section Hooks:: to learn about
2362 such hooks and how to customize them.
2363
2364  -- User Option: magit-status-sections-hook
2365
2366      Hook run to insert sections into a status buffer.
2367
2368    The first function on that hook by default is
2369 ‘magit-insert-status-headers’; it is described in the next section.  By
2370 default the following functions are also members of that hook:
2371
2372  -- Function: magit-insert-merge-log
2373
2374      Insert section for the on-going merge.  Display the heads that are
2375      being merged.  If no merge is in progress, do nothing.
2376
2377  -- Function: magit-insert-rebase-sequence
2378
2379      Insert section for the on-going rebase sequence.  If no such
2380      sequence is in progress, do nothing.
2381
2382  -- Function: magit-insert-am-sequence
2383
2384      Insert section for the on-going patch applying sequence.  If no
2385      such sequence is in progress, do nothing.
2386
2387  -- Function: magit-insert-sequencer-sequence
2388
2389      Insert section for the on-going cherry-pick or revert sequence.  If
2390      no such sequence is in progress, do nothing.
2391
2392  -- Function: magit-insert-bisect-output
2393
2394      While bisecting, insert section with output from ‘git bisect’.
2395
2396  -- Function: magit-insert-bisect-rest
2397
2398      While bisecting, insert section visualizing the bisect state.
2399
2400  -- Function: magit-insert-bisect-log
2401
2402      While bisecting, insert section logging bisect progress.
2403
2404  -- Function: magit-insert-untracked-files
2405
2406      Maybe insert a list or tree of untracked files.
2407
2408      Do so depending on the value of ‘status.showUntrackedFiles’.  Note
2409      that even if the value is ‘all’, Magit still initially only shows
2410      directories.  But the directory sections can then be expanded using
2411      ‘TAB’.
2412
2413  -- Function: magit-insert-unstaged-changes
2414
2415      Insert section showing unstaged changes.
2416
2417  -- Function: magit-insert-staged-changes
2418
2419      Insert section showing staged changes.
2420
2421  -- Function: magit-insert-stashes &optional ref heading
2422
2423      Insert the ‘stashes’ section showing reflog for "refs/stash".  If
2424      optional REF is non-nil show reflog for that instead.  If optional
2425      HEADING is non-nil use that as section heading instead of
2426      "Stashes:".
2427
2428  -- Function: magit-insert-unpulled-from-upstream
2429
2430      Insert section showing commits that haven’t been pulled from the
2431      upstream branch yet.
2432
2433  -- Function: magit-insert-unpulled-from-pushremote
2434
2435      Insert section showing commits that haven’t been pulled from the
2436      push-remote branch yet.
2437
2438  -- Function: magit-insert-unpushed-to-upstream
2439
2440      Insert section showing commits that haven’t been pushed to the
2441      upstream yet.
2442
2443  -- Function: magit-insert-unpushed-to-pushremote
2444
2445      Insert section showing commits that haven’t been pushed to the
2446      push-remote yet.
2447
2448    The following functions can also be added to the above hook:
2449
2450  -- Function: magit-insert-tracked-files
2451
2452      Insert a tree of tracked files.
2453
2454  -- Function: magit-insert-ignored-files
2455
2456      Insert a tree of ignored files.
2457
2458      If the first element of ‘magit-diff-section-arguments’ is a
2459      directory, then limit the list to files below that.  The value of
2460      that variable can be set using ‘D = f <DIRECTORY> RET g’.
2461
2462  -- Function: magit-insert-unpulled-or-recent-commits
2463
2464      Insert section showing unpulled or recent commits.  If an upstream
2465      is configured for the current branch and it is ahead of the current
2466      branch, then show the missing commits.  Otherwise, show the last
2467      ‘magit-log-section-commit-count’ commits.
2468
2469  -- Function: magit-insert-recent-commits
2470
2471      Insert section showing the last ‘magit-log-section-commit-count’
2472      commits.
2473
2474  -- User Option: magit-log-section-commit-count
2475
2476      How many recent commits ‘magit-insert-recent-commits’ and
2477      ‘magit-insert-unpulled-or-recent-commits’ (provided there are no
2478      unpulled commits) show.
2479
2480  -- Function: magit-insert-unpulled-cherries
2481
2482      Insert section showing unpulled commits.  Like
2483      ‘magit-insert-unpulled-commits’ but prefix each commit that has not
2484      been applied yet (i.e.  a commit with a patch-id not shared with
2485      any local commit) with "+", and all others with "-".
2486
2487  -- Function: magit-insert-unpushed-cherries
2488
2489      Insert section showing unpushed commits.  Like
2490      ‘magit-insert-unpushed-commits’ but prefix each commit which has
2491      not been applied to upstream yet (i.e.  a commit with a patch-id
2492      not shared with any upstream commit) with "+" and all others with
2493      "-".
2494
2495    See *note References Buffer:: for some more section inserters, which
2496 could be used here.
2497
2498 
2499 File: magit.info,  Node: Status Header Sections,  Next: Status Module Sections,  Prev: Status Sections,  Up: Status Buffer
2500
2501 5.1.2 Status Header Sections
2502 ----------------------------
2503
2504 The contents of status buffers is controlled using the hook
2505 ‘magit-status-sections-hook’ (see *note Status Sections::).
2506
2507    By default ‘magit-insert-status-headers’ is the first member of that
2508 hook variable.
2509
2510  -- Function: magit-insert-status-headers
2511
2512      Insert headers sections appropriate for ‘magit-status-mode’
2513      buffers.  The sections are inserted by running the functions on the
2514      hook ‘magit-status-headers-hook’.
2515
2516  -- User Option: magit-status-headers-hook
2517
2518      Hook run to insert headers sections into the status buffer.
2519
2520      This hook is run by ‘magit-insert-status-headers’, which in turn
2521      has to be a member of ‘magit-status-sections-hook’ to be used at
2522      all.
2523
2524    By default the following functions are members of the above hook:
2525
2526  -- Function: magit-insert-error-header
2527
2528      Insert a header line showing the message about the Git error that
2529      just occurred.
2530
2531      This function is only aware of the last error that occur when Git
2532      was run for side-effects.  If, for example, an error occurs while
2533      generating a diff, then that error won’t be inserted.  Refreshing
2534      the status buffer causes this section to disappear again.
2535
2536  -- Function: magit-insert-diff-filter-header
2537
2538      Insert a header line showing the effective diff filters.
2539
2540  -- Function: magit-insert-head-branch-header
2541
2542      Insert a header line about the current branch or detached ‘HEAD’.
2543
2544  -- Function: magit-insert-upstream-branch-header
2545
2546      Insert a header line about the branch that is usually pulled into
2547      the current branch.
2548
2549  -- Function: magit-insert-push-branch-header
2550
2551      Insert a header line about the branch that the current branch is
2552      usually pushed to.
2553
2554  -- Function: magit-insert-tags-header
2555
2556      Insert a header line about the current and/or next tag, along with
2557      the number of commits between the tag and ‘HEAD’.
2558
2559    The following functions can also be added to the above hook:
2560
2561  -- Function: magit-insert-repo-header
2562
2563      Insert a header line showing the path to the repository top-level.
2564
2565  -- Function: magit-insert-remote-header
2566
2567      Insert a header line about the remote of the current branch.
2568
2569      If no remote is configured for the current branch, then fall back
2570      showing the "origin" remote, or if that does not exist the first
2571      remote in alphabetic order.
2572
2573  -- Function: magit-insert-user-header
2574
2575      Insert a header line about the current user.
2576
2577 
2578 File: magit.info,  Node: Status Module Sections,  Next: Status Options,  Prev: Status Header Sections,  Up: Status Buffer
2579
2580 5.1.3 Status Module Sections
2581 ----------------------------
2582
2583 The contents of status buffers is controlled using the hook
2584 ‘magit-status-sections-hook’ (see *note Status Sections::).
2585
2586    By default ‘magit-insert-modules’ is _not_ a member of that hook
2587 variable.
2588
2589  -- Function: magit-insert-modules
2590
2591      Insert submodule sections.
2592
2593      Hook ‘magit-module-sections-hook’ controls which module sections
2594      are inserted, and option ‘magit-module-sections-nested’ controls
2595      whether they are wrapped in an additional section.
2596
2597  -- User Option: magit-module-sections-hook
2598
2599      Hook run by ‘magit-insert-modules’.
2600
2601  -- User Option: magit-module-sections-nested
2602
2603      This option controls whether ‘magit-insert-modules’ wraps inserted
2604      sections in an additional section.
2605
2606      If this is non-nil, then only a single top-level section is
2607      inserted.  If it is nil, then all sections listed in
2608      ‘magit-module-sections-hook’ become top-level sections.
2609
2610  -- Function: magit-insert-modules-overview
2611
2612      Insert sections for all submodules.  For each section insert the
2613      path, the branch, and the output of ‘git describe --tags’, or,
2614      failing that, the abbreviated HEAD commit hash.
2615
2616      Press ‘RET’ on such a submodule section to show its own status
2617      buffer.  Press ‘RET’ on the "Modules" section to display a list of
2618      submodules in a separate buffer.  This shows additional information
2619      not displayed in the super-repository’s status buffer.
2620
2621  -- Function: magit-insert-modules-unpulled-from-upstream
2622
2623      Insert sections for modules that haven’t been pulled from the
2624      upstream yet.  These sections can be expanded to show the
2625      respective commits.
2626
2627  -- Function: magit-insert-modules-unpulled-from-pushremote
2628
2629      Insert sections for modules that haven’t been pulled from the
2630      push-remote yet.  These sections can be expanded to show the
2631      respective commits.
2632
2633  -- Function: magit-insert-modules-unpushed-to-upstream
2634
2635      Insert sections for modules that haven’t been pushed to the
2636      upstream yet.  These sections can be expanded to show the
2637      respective commits.
2638
2639  -- Function: magit-insert-modules-unpushed-to-pushremote
2640
2641      Insert sections for modules that haven’t been pushed to the
2642      push-remote yet.  These sections can be expanded to show the
2643      respective commits.
2644
2645 
2646 File: magit.info,  Node: Status Options,  Prev: Status Module Sections,  Up: Status Buffer
2647
2648 5.1.4 Status Options
2649 --------------------
2650
2651  -- User Option: magit-status-refresh-hook
2652
2653      Hook run after a status buffer has been refreshed.
2654
2655  -- User Option: magit-status-margin
2656
2657      This option specifies whether the margin is initially shown in
2658      Magit-Status mode buffers and how it is formatted.
2659
2660      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
2661
2662         • If INIT is non-nil, then the margin is shown initially.
2663
2664         • STYLE controls how to format the committer date.  It can be
2665           one of ‘age’ (to show the age of the commit),
2666           ‘age-abbreviated’ (to abbreviate the time unit to a
2667           character), or a string (suitable for ‘format-time-string’) to
2668           show the actual date.
2669
2670         • WIDTH controls the width of the margin.  This exists for
2671           forward compatibility and currently the value should not be
2672           changed.
2673
2674         • AUTHOR controls whether the name of the author is also shown
2675           by default.
2676
2677         • AUTHOR-WIDTH has to be an integer.  When the name of the
2678           author is shown, then this specifies how much space is used to
2679           do so.
2680
2681  -- User Option: magit-log-section-args
2682
2683      Additional Git arguments used when creating log sections.  Only
2684      ‘--graph’, ‘--decorate’, and ‘--show-signature’ are supported.
2685      This option is only a temporary kludge and will be removed.
2686
2687      Note that due to an issue in Git the use of ‘--graph’ is very slow
2688      with long histories, so you probably don’t want to add this here.
2689
2690    Also see the proceeding section for more options concerning status
2691 buffers.
2692
2693 
2694 File: magit.info,  Node: Repository List,  Next: Logging,  Prev: Status Buffer,  Up: Inspecting
2695
2696 5.2 Repository List
2697 ===================
2698
2699  -- Command: magit-list-repositories
2700
2701      This command displays a list of repositories in a separate buffer.
2702
2703      The options ‘magit-repository-directories’ and
2704      ‘magit-repository-directories-depth’ control which repositories are
2705      displayed.
2706
2707  -- User Option: magit-repolist-columns
2708
2709      This option controls what columns are displayed by the command
2710      ‘magit-list-repositories’ and how they are displayed.
2711
2712      Each element has the form ‘(HEADER WIDTH FORMAT PROPS)’.
2713
2714      HEADER is the string displayed in the header.  WIDTH is the width
2715      of the column.  FORMAT is a function that is called with one
2716      argument, the repository identification (usually its basename), and
2717      with ‘default-directory’ bound to the toplevel of its working tree.
2718      It has to return a string to be inserted or nil.  PROPS is an alist
2719      that supports the keys ‘:right-align’ and ‘:pad-right’.
2720
2721    The following functions can be added to the above option:
2722
2723  -- Function: magit-repolist-column-ident
2724
2725      This function inserts the identification of the repository.
2726      Usually this is just its basename.
2727
2728  -- Function: magit-repolist-column-path
2729
2730      This function inserts the absolute path of the repository.
2731
2732  -- Function: magit-repolist-column-version
2733
2734      This function inserts a description of the repository’s ‘HEAD’
2735      revision.
2736
2737  -- Function: magit-repolist-column-unpulled-from-upstream
2738
2739      This function inserts the number of upstream commits not in the
2740      current branch.
2741
2742  -- Function: magit-repolist-column-unpulled-from-pushremote
2743
2744      This function inserts the number of commits in the push branch but
2745      not the current branch.
2746
2747  -- Function: magit-repolist-column-unpushed-to-upstream
2748
2749      This function inserts the number of commits in the current branch
2750      but not its upstream.
2751
2752  -- Function: magit-repolist-column-unpushed-to-pushremote
2753
2754      This function inserts the number of commits in the current branch
2755      but not its push branch.
2756
2757 
2758 File: magit.info,  Node: Logging,  Next: Diffing,  Prev: Repository List,  Up: Inspecting
2759
2760 5.3 Logging
2761 ===========
2762
2763 The status buffer contains logs for the unpushed and unpulled commits,
2764 but that obviously isn’t enough.  The prefix command ‘magit-log-popup’,
2765 on ‘l’, features several suffix commands, which show a specific log in a
2766 separate log buffer.
2767
2768    Like other popups, the log popup also features several arguments that
2769 can be changed before invoking one of the suffix commands.  However, in
2770 the case of the log popup, these arguments may be taken from those
2771 currently in use in the current repository’s log buffer, depending on
2772 the value of ‘magit-use-sticky-arguments’ (see *note Popup Buffers and
2773 Prefix Commands::).
2774
2775    For information about the various arguments, see *note
2776 (gitman)git-log::.
2777
2778    The switch ‘++order=VALUE’ is converted to one of
2779 ‘--author-date-order’, ‘--date-order’, or ‘--topo-order’ before being
2780 passed to ‘git log’.
2781
2782    The log popup also features several reflog commands.  See *note
2783 Reflog::.
2784
2785 ‘l’     (‘magit-log-popup’)
2786
2787      This prefix command shows the following suffix commands along with
2788      the appropriate infix arguments in a popup buffer.
2789
2790 ‘l l’     (‘magit-log-current’)
2791
2792      Show log for the current branch.  When ‘HEAD’ is detached or with a
2793      prefix argument, show log for one or more revs read from the
2794      minibuffer.
2795
2796 ‘l o’     (‘magit-log-other’)
2797
2798      Show log for one or more revs read from the minibuffer.  The user
2799      can input any revision or revisions separated by a space, or even
2800      ranges, but only branches, tags, and a representation of the commit
2801      at point are available as completion candidates.
2802
2803 ‘l h’     (‘magit-log-head’)
2804
2805      Show log for ‘HEAD’.
2806
2807 ‘l L’     (‘magit-log-branches’)
2808
2809      Show log for all local branches and ‘HEAD’.
2810
2811 ‘l b’     (‘magit-log-all-branches’)
2812
2813      Show log for all local and remote branches and ‘HEAD’.
2814
2815 ‘l a’     (‘magit-log-all’)
2816
2817      Show log for all references and ‘HEAD’.
2818
2819    Two additional commands that show the log for the file or blob that
2820 is being visited in the current buffer exists, see *note Minor Mode for
2821 Buffers Visiting Files::.  The command ‘magit-cherry’ also shows a log,
2822 see *note Cherries::.
2823
2824 * Menu:
2825
2826 * Refreshing Logs::
2827 * Log Buffer::
2828 * Log Margin::
2829 * Select from Log::
2830 * Reflog::
2831 * Cherries::
2832
2833 
2834 File: magit.info,  Node: Refreshing Logs,  Next: Log Buffer,  Up: Logging
2835
2836 5.3.1 Refreshing Logs
2837 ---------------------
2838
2839 The prefix command ‘magit-log-refresh-popup’, on ‘L’, can be used to
2840 change the log arguments used in the current buffer, without changing
2841 which log is shown.  This works in dedicated log buffers, but also in
2842 the status buffer.
2843
2844 ‘L’     (‘magit-log-refresh-popup’)
2845
2846      This prefix command shows the following suffix commands along with
2847      the appropriate infix arguments in a popup buffer.
2848
2849 ‘L g’     (‘magit-log-refresh’)
2850
2851      This suffix command sets the local log arguments for the current
2852      buffer.
2853
2854 ‘L s’     (‘magit-log-set-default-arguments’)
2855
2856      This suffix command sets the default log arguments for buffers of
2857      the same type as that of the current buffer.  Other existing
2858      buffers of the same type are not affected because their local
2859      values have already been initialized.
2860
2861 ‘L w’     (‘magit-log-save-default-arguments’)
2862
2863      This suffix command sets the default log arguments for buffers of
2864      the same type as that of the current buffer, and saves the value
2865      for future sessions.  Other existing buffers of the same type are
2866      not affected because their local values have already been
2867      initialized.
2868
2869 ‘L t’     (‘magit-toggle-margin’)
2870
2871      Show or hide the margin.
2872
2873 
2874 File: magit.info,  Node: Log Buffer,  Next: Log Margin,  Prev: Refreshing Logs,  Up: Logging
2875
2876 5.3.2 Log Buffer
2877 ----------------
2878
2879 ‘L’     (‘magit-log-refresh-popup’)
2880
2881      This prefix command shows the following suffix commands along with
2882      the appropriate infix arguments in a popup buffer.  See *note
2883      Refreshing Logs::.
2884
2885 ‘q’     (‘magit-log-bury-buffer’)
2886
2887      Bury the current buffer or the revision buffer in the same frame.
2888      Like ‘magit-mode-bury-buffer’ (which see) but with a negative
2889      prefix argument instead bury the revision buffer, provided it is
2890      displayed in the current frame.
2891
2892 ‘C-c C-b’     (‘magit-go-backward’)
2893
2894      Move backward in current buffer’s history.
2895
2896 ‘C-c C-f’     (‘magit-go-forward’)
2897
2898      Move forward in current buffer’s history.
2899
2900 ‘C-c C-n’     (‘magit-log-move-to-parent’)
2901
2902      Move to a parent of the current commit.  By default, this is the
2903      first parent, but a numeric prefix can be used to specify another
2904      parent.
2905
2906 ‘SPC’     (‘magit-diff-show-or-scroll-up’)
2907
2908      Update the commit or diff buffer for the thing at point.
2909
2910      Either show the commit or stash at point in the appropriate buffer,
2911      or if that buffer is already being displayed in the current frame
2912      and contains information about that commit or stash, then instead
2913      scroll the buffer up.  If there is no commit or stash at point,
2914      then prompt for a commit.
2915
2916 ‘DEL’     (‘magit-diff-show-or-scroll-down’)
2917
2918      Update the commit or diff buffer for the thing at point.
2919
2920      Either show the commit or stash at point in the appropriate buffer,
2921      or if that buffer is already being displayed in the current frame
2922      and contains information about that commit or stash, then instead
2923      scroll the buffer down.  If there is no commit or stash at point,
2924      then prompt for a commit.
2925
2926 ‘=’     (‘magit-log-toggle-commit-limit’)
2927
2928      Toggle the number of commits the current log buffer is limited to.
2929      If the number of commits is currently limited, then remove that
2930      limit.  Otherwise set it to 256.
2931
2932 ‘+’     (‘magit-log-double-commit-limit’)
2933
2934      Double the number of commits the current log buffer is limited to.
2935
2936 ‘-’     (‘magit-log-half-commit-limit’)
2937
2938      Half the number of commits the current log buffer is limited to.
2939
2940  -- User Option: magit-log-auto-more
2941
2942      Insert more log entries automatically when moving past the last
2943      entry.  Only considered when moving past the last entry with
2944      ‘magit-goto-*-section’ commands.
2945
2946  -- User Option: magit-log-show-refname-after-summary
2947
2948      Whether to show the refnames after the commit summaries.  This is
2949      useful if you use really long branch names.
2950
2951    Magit displays references in logs a bit differently from how Git does
2952 it.
2953
2954    Local branches are blue and remote branches are green.  Of course
2955 that depends on the used theme, as do the colors used for other types of
2956 references.  The current branch has a box around it, as do remote
2957 branches that are their respective remote’s ‘HEAD’ branch.
2958
2959    If a local branch and its push-target point at the same commit, then
2960 their names are combined to preserve space and to make that relationship
2961 visible.  For example:
2962
2963      origin/feature
2964      [green][blue-]
2965
2966      instead of
2967
2968      feature origin/feature
2969      [blue-] [green-------]
2970
2971    Also note that while the popup features the ‘--show-signature’
2972 argument, that won’t actually be used when enabled, because Magit
2973 defaults to use just one line per commit.  Instead the commit colorized
2974 to indicate the validity of the signed commit object, using the faces
2975 named ‘magit-signature-*’ (which see).
2976
2977    For a description of ‘magit-log-margin’ see *note Log Margin::.
2978
2979 
2980 File: magit.info,  Node: Log Margin,  Next: Select from Log,  Prev: Log Buffer,  Up: Logging
2981
2982 5.3.3 Log Margin
2983 ----------------
2984
2985 In buffers which show one or more logs, it is possible to show
2986 additional information about each commit in the margin.  The options
2987 used to configure the margin are named ‘magit-INFIX-margin’, where INFIX
2988 is the same as in the respective major-mode ‘magit-INFIX-mode’.  In
2989 regular log buffers that would be ‘magit-log-margin’.
2990
2991  -- User Option: magit-log-margin
2992
2993      This option specifies whether the margin is initially shown in
2994      Magit-Log mode buffers and how it is formatted.
2995
2996      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
2997
2998         • If INIT is non-nil, then the margin is shown initially.
2999
3000         • STYLE controls how to format the committer date.  It can be
3001           one of ‘age’ (to show the age of the commit),
3002           ‘age-abbreviated’ (to abbreviate the time unit to a
3003           character), or a string (suitable for ‘format-time-string’) to
3004           show the actual date.
3005
3006         • WIDTH controls the width of the margin.  This exists for
3007           forward compatibility and currently the value should not be
3008           changed.
3009
3010         • AUTHOR controls whether the name of the author is also shown
3011           by default.
3012
3013         • AUTHOR-WIDTH has to be an integer.  When the name of the
3014           author is shown, then this specifies how much space is used to
3015           do so.
3016
3017    You can change the STYLE and AUTHOR-WIDTH of all ‘magit-INFIX-margin’
3018 options to the same values by customizing ‘magit-log-margin’ *before*
3019 ‘magit’ is loaded.  If you do that, then the respective values for the
3020 other options will default to what you have set for that variable.
3021 Likewise if you set INIT in ‘magit-log-margin’ to ‘nil’, then that is
3022 used in the default of all other options.  But setting it to ‘t’, i.e.
3023 re-enforcing the default for that option, does not carry to other
3024 options.
3025
3026 ‘L’     (‘magit-margin-popup’)
3027
3028      This prefix command features the following commands for changing
3029      the appearance of the margin.
3030
3031    In some buffers that support the margin, "L" is bound to
3032 ‘magit-log-refresh-popup’, but that popup features the same commands,
3033 and then some other unrelated commands.
3034
3035 ‘L L’     (‘magit-toggle-margin’)
3036
3037      This command shows or hides the margin.
3038
3039 ‘L l’     (‘magit-cycle-margin-style’)
3040
3041      This command cycles the style used for the margin.
3042
3043 ‘L d’     (‘magit-toggle-margin-details’)
3044
3045      This command shows or hides details in the margin.
3046
3047 
3048 File: magit.info,  Node: Select from Log,  Next: Reflog,  Prev: Log Margin,  Up: Logging
3049
3050 5.3.4 Select from Log
3051 ---------------------
3052
3053 When the user has to select a recent commit that is reachable from
3054 ‘HEAD’, using regular completion would be inconvenient (because most
3055 humans cannot remember hashes or "HEAD~5", at least not without double
3056 checking).  Instead a log buffer is used to select the commit, which has
3057 the advantage that commits are presented in order and with the commit
3058 message.
3059
3060    Such selection logs are used when selecting the beginning of a rebase
3061 and when selecting the commit to be squashed into.
3062
3063    In addition to the key bindings available in all log buffers, the
3064 following additional key bindings are available in selection log
3065 buffers:
3066
3067 ‘C-c C-c’     (‘magit-log-select-pick’)
3068
3069      Select the commit at point and act on it.  Call
3070      ‘magit-log-select-pick-function’ with the selected commit as
3071      argument.
3072
3073 ‘C-c C-k’     (‘magit-log-select-quit’)
3074
3075      Abort selecting a commit, don’t act on any commit.
3076
3077  -- User Option: magit-log-select-margin
3078
3079      This option specifies whether the margin is initially shown in
3080      Magit-Log-Select mode buffers and how it is formatted.
3081
3082      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
3083
3084         • If INIT is non-nil, then the margin is shown initially.
3085
3086         • STYLE controls how to format the committer date.  It can be
3087           one of ‘age’ (to show the age of the commit),
3088           ‘age-abbreviated’ (to abbreviate the time unit to a
3089           character), or a string (suitable for ‘format-time-string’) to
3090           show the actual date.
3091
3092         • WIDTH controls the width of the margin.  This exists for
3093           forward compatibility and currently the value should not be
3094           changed.
3095
3096         • AUTHOR controls whether the name of the author is also shown
3097           by default.
3098
3099         • AUTHOR-WIDTH has to be an integer.  When the name of the
3100           author is shown, then this specifies how much space is used to
3101           do so.
3102
3103 
3104 File: magit.info,  Node: Reflog,  Next: Cherries,  Prev: Select from Log,  Up: Logging
3105
3106 5.3.5 Reflog
3107 ------------
3108
3109 Also see *note (gitman)git-reflog::.
3110
3111    These reflog commands are available from the log popup.  See *note
3112 Logging::.
3113
3114 ‘l r’     (‘magit-reflog-current’)
3115
3116      Display the reflog of the current branch.
3117
3118 ‘l O’     (‘magit-reflog-other’)
3119
3120      Display the reflog of a branch or another ref.
3121
3122 ‘l H’     (‘magit-reflog-head’)
3123
3124      Display the ‘HEAD’ reflog.
3125
3126  -- User Option: magit-reflog-margin
3127
3128      This option specifies whether the margin is initially shown in
3129      Magit-Reflog mode buffers and how it is formatted.
3130
3131      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
3132
3133         • If INIT is non-nil, then the margin is shown initially.
3134
3135         • STYLE controls how to format the committer date.  It can be
3136           one of ‘age’ (to show the age of the commit),
3137           ‘age-abbreviated’ (to abbreviate the time unit to a
3138           character), or a string (suitable for ‘format-time-string’) to
3139           show the actual date.
3140
3141         • WIDTH controls the width of the margin.  This exists for
3142           forward compatibility and currently the value should not be
3143           changed.
3144
3145         • AUTHOR controls whether the name of the author is also shown
3146           by default.
3147
3148         • AUTHOR-WIDTH has to be an integer.  When the name of the
3149           author is shown, then this specifies how much space is used to
3150           do so.
3151
3152 
3153 File: magit.info,  Node: Cherries,  Prev: Reflog,  Up: Logging
3154
3155 5.3.6 Cherries
3156 --------------
3157
3158 Cherries are commits that haven’t been applied upstream (yet), and are
3159 usually visualized using a log.  Each commit is prefixed with ‘-’ if it
3160 has an equivalent in the upstream and ‘+’ if it does not, i.e.  if it is
3161 a cherry.
3162
3163    The command ‘magit-cherry’ shows cherries for a single branch, but
3164 the references buffer (see *note References Buffer::) can show cherries
3165 for multiple "upstreams" at once.
3166
3167    Also see *note (gitman)git-reflog::.
3168
3169 ‘Y’     (‘magit-cherry’)
3170
3171      Show commits that are in a certain branch but that have not been
3172      merged in the upstream branch.
3173
3174  -- User Option: magit-cherry-margin
3175
3176      This option specifies whether the margin is initially shown in
3177      Magit-Cherry mode buffers and how it is formatted.
3178
3179      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
3180
3181         • If INIT is non-nil, then the margin is shown initially.
3182
3183         • STYLE controls how to format the committer date.  It can be
3184           one of ‘age’ (to show the age of the commit),
3185           ‘age-abbreviated’ (to abbreviate the time unit to a
3186           character), or a string (suitable for ‘format-time-string’) to
3187           show the actual date.
3188
3189         • WIDTH controls the width of the margin.  This exists for
3190           forward compatibility and currently the value should not be
3191           changed.
3192
3193         • AUTHOR controls whether the name of the author is also shown
3194           by default.
3195
3196         • AUTHOR-WIDTH has to be an integer.  When the name of the
3197           author is shown, then this specifies how much space is used to
3198           do so.
3199
3200 
3201 File: magit.info,  Node: Diffing,  Next: Ediffing,  Prev: Logging,  Up: Inspecting
3202
3203 5.4 Diffing
3204 ===========
3205
3206 The status buffer contains diffs for the staged and unstaged commits,
3207 but that obviously isn’t enough.  The prefix command ‘magit-diff-popup’,
3208 on ‘d’, features several suffix commands, which show a specific diff in
3209 a separate diff buffer.
3210
3211    Like other popups, the diff popup also features several arguments
3212 that can be changed before invoking one of the suffix commands.
3213 However, in the case of the diff popup, these arguments may be taken
3214 from those currently in use in the current repository’s log buffer,
3215 depending on the value of ‘magit-use-sticky-arguments’ (see *note Popup
3216 Buffers and Prefix Commands::).
3217
3218    Also see *note (gitman)git-diff::.
3219
3220 ‘d’     (‘magit-diff-popup’)
3221
3222      This prefix command shows the following suffix commands along with
3223      the appropriate infix arguments in a popup buffer.
3224
3225 ‘d d’     (‘magit-diff-dwim’)
3226
3227      Show changes for the thing at point.
3228
3229 ‘d r’     (‘magit-diff-range’)
3230
3231      Show differences between two commits.
3232
3233      RANGE should be a range (A..B or A...B) but can also be a single
3234      commit.  If one side of the range is omitted, then it defaults to
3235      ‘HEAD’.  If just a commit is given, then changes in the working
3236      tree relative to that commit are shown.
3237
3238      If the region is active, use the revisions on the first and last
3239      line of the region.  With a prefix argument, instead of diffing the
3240      revisions, choose a revision to view changes along, starting at the
3241      common ancestor of both revisions (i.e., use a "..." range).
3242
3243 ‘d w’     (‘magit-diff-working-tree’)
3244
3245      Show changes between the current working tree and the ‘HEAD’
3246      commit.  With a prefix argument show changes between the working
3247      tree and a commit read from the minibuffer.
3248
3249 ‘d s’     (‘magit-diff-staged’)
3250
3251      Show changes between the index and the ‘HEAD’ commit.  With a
3252      prefix argument show changes between the index and a commit read
3253      from the minibuffer.
3254
3255 ‘d u’     (‘magit-diff-unstaged’)
3256
3257      Show changes between the working tree and the index.
3258
3259 ‘d p’     (‘magit-diff-paths’)
3260
3261      Show changes between any two files on disk.
3262
3263    All of the above suffix commands update the repository’s diff buffer.
3264 The diff popup also features two commands which show differences in
3265 another buffer:
3266
3267 ‘d c’     (‘magit-show-commit’)
3268
3269      Show the commit at point.  If there is no commit at point or with a
3270      prefix argument, prompt for a commit.
3271
3272 ‘d t’     (‘magit-stash-show’)
3273
3274      Show all diffs of a stash in a buffer.
3275
3276    Two additional commands that show the diff for the file or blob that
3277 is being visited in the current buffer exists, see *note Minor Mode for
3278 Buffers Visiting Files::.
3279
3280 * Menu:
3281
3282 * Refreshing Diffs::
3283 * Diff Buffer::
3284 * Diff Options::
3285 * Revision Buffer::
3286
3287 
3288 File: magit.info,  Node: Refreshing Diffs,  Next: Diff Buffer,  Up: Diffing
3289
3290 5.4.1 Refreshing Diffs
3291 ----------------------
3292
3293 The prefix command ‘magit-diff-refresh-popup’, on ‘D’, can be used to
3294 change the diff arguments used in the current buffer, without changing
3295 which diff is shown.  This works in dedicated diff buffers, but also in
3296 the status buffer.
3297
3298 ‘D’     (‘magit-diff-refresh-popup’)
3299
3300      This prefix command shows the following suffix commands along with
3301      the appropriate infix arguments in a popup buffer.
3302
3303 ‘D g’     (‘magit-diff-refresh’)
3304
3305      This suffix command sets the local diff arguments for the current
3306      buffer.
3307
3308 ‘D s’     (‘magit-diff-set-default-arguments’)
3309
3310      This suffix command sets the default diff arguments for buffers of
3311      the same type as that of the current buffer.  Other existing
3312      buffers of the same type are not affected because their local
3313      values have already been initialized.
3314
3315 ‘D w’     (‘magit-diff-save-default-arguments’)
3316
3317      This suffix command sets the default diff arguments for buffers of
3318      the same type as that of the current buffer, and saves the value
3319      for future sessions.  Other existing buffers of the same type are
3320      not affected because their local values have already been
3321      initialized.
3322
3323 ‘D t’     (‘magit-diff-toggle-refine-hunk’)
3324
3325      This command toggles hunk refinement on or off.
3326
3327 ‘D r’     (‘magit-diff-switch-range-type’)
3328
3329      This command converts the diff range type from "revA..revB" to
3330      "revB...revA", or vice versa.
3331
3332 ‘D f’     (‘magit-diff-flip-revs’)
3333
3334      This command swaps revisions in the diff range from "revA..revB" to
3335      "revB..revA", or vice versa.
3336
3337 ‘D F’     (‘magit-diff-toggle-file-filter’)
3338
3339      This command toggles the file restriction of the diffs in the
3340      current buffer, allowing you to quickly switch between viewing all
3341      the changes in the commit and the restricted subset.  As a special
3342      case, when this command is called from a log buffer, it toggles the
3343      file restriction in the repository’s revision buffer, which is
3344      useful when you display a revision from a log buffer that is
3345      restricted to a file or files.
3346
3347    In addition to the above popup, which allows changing any of the
3348 supported arguments, there also exist some commands which change a
3349 particular argument.
3350
3351 ‘-’     (‘magit-diff-less-context’)
3352
3353      This command decreases the context for diff hunks by COUNT lines.
3354
3355 ‘+’     (‘magit-diff-more-context’)
3356
3357      This command increases the context for diff hunks by COUNT lines.
3358
3359 ‘0’     (‘magit-diff-default-context’)
3360
3361      This command resets the context for diff hunks to the default
3362      height.
3363
3364    The following commands quickly change what diff is being displayed
3365 without having to using one of the diff popups.
3366
3367 ‘C-c C-d’     (‘magit-diff-while-committing’)
3368
3369      While committing, this command shows the changes that are about to
3370      be committed.  While amending, invoking the command again toggles
3371      between showing just the new changes or all the changes that will
3372      be committed.
3373
3374      This binding is available in the diff buffer as well as the commit
3375      message buffer.
3376
3377 ‘C-c C-b’     (‘magit-go-backward’)
3378
3379      This command moves backward in current buffer’s history.
3380
3381 ‘C-c C-f’     (‘magit-go-forward’)
3382
3383      This command moves forward in current buffer’s history.
3384
3385 
3386 File: magit.info,  Node: Diff Buffer,  Next: Diff Options,  Prev: Refreshing Diffs,  Up: Diffing
3387
3388 5.4.2 Diff Buffer
3389 -----------------
3390
3391 These commands are available in diff buffers.
3392
3393 ‘RET’     (‘magit-diff-visit-file’)
3394
3395      From a diff, visit the corresponding file at the appropriate
3396      position.
3397
3398      If the diff shows changes in the worktree, the index, or ‘HEAD’,
3399      then visit the actual file.  Otherwise, when the diff is about an
3400      older commit or a range, then visit the appropriate blob.
3401
3402      If point is on a removed line, then visit the blob for the first
3403      parent of the commit which removed that line, i.e.  the last commit
3404      where that line still existed.  Otherwise visit the blob for the
3405      commit whose changes are being shown.
3406
3407      Interactively, when the file or blob to be displayed is already
3408      being displayed in another window of the same frame, then just
3409      select that window and adjust point.  Otherwise, or with a prefix
3410      argument, display the buffer in another window.  The meaning of the
3411      prefix argument can be inverted or further modified using the
3412      option ‘magit-display-file-buffer-function’.
3413
3414      Non-interactively the optional OTHER-WINDOW argument is taken
3415      literally.  DISPLAY-FN can be used to specify the display function
3416      explicitly, in which case OTHER-WINDOW is ignored.
3417
3418      The optional FORCE-WORKTREE means to force visiting the worktree
3419      version of the file.  To do this interactively use the command
3420      ‘magit-diff-visit-file-worktree’ instead.
3421
3422  -- User Option: magit-diff-visit-previous-blob
3423
3424      This option controls whether ‘magit-diff-visit-file’ may visit the
3425      previous blob.  When this is ‘t’ and point is on a removed line in
3426      a diff for a committed change, then ‘magit-diff-visit-file’ visits
3427      the blob from the last revision which still had that line.
3428
3429      Currently this is only supported for committed changes, for staged
3430      and unstaged changes ‘magit-diff-visit-file’ always visits the file
3431      in the working tree.
3432
3433 ‘C-<return>’     (‘magit-diff-visit-file-worktree’)
3434
3435      From a diff, visit the corresponding file at the appropriate
3436      position.
3437
3438      When the file is already being displayed in another window of the
3439      same frame, then just select that window and adjust point.  With a
3440      prefix argument also display in another window.
3441
3442      The actual file in the worktree is visited.  The positions in the
3443      hunk headers get less useful the "older" the changes are, and as a
3444      result, jumping to the appropriate position gets less reliable.
3445
3446      Also see ‘magit-diff-visit-file’, which visits the respective blob,
3447      unless the diff shows changes in the worktree, the index, or
3448      ‘HEAD’.
3449
3450  -- Command: magit-diff-visit-file-other-window
3451
3452      From a diff, visit the corresponding file at the appropriate
3453      position in another window.
3454
3455 ‘C-c C-t’     (‘magit-diff-trace-definition’)
3456
3457      From a diff, show log for the definition at point.
3458
3459  -- User Option: magit-log-trace-definition-function
3460
3461      The function used by ‘magit-log-trace-definition’ to determine the
3462      function at point.  For major-modes that have special needs, you
3463      could set that using the mode’s hook.
3464
3465 ‘C-c C-e’     (‘magit-diff-edit-hunk-commit’)
3466
3467      From a hunk, edit the respective commit and visit the file.
3468
3469      First visit the file being modified by the hunk at the correct
3470      location using ‘magit-diff-visit-file’.  This actually visits a
3471      blob.  When point is on a diff header, not within an individual
3472      hunk, then this visits the blob the first hunk is about.
3473
3474      Then invoke ‘magit-edit-line-commit’, which uses an interactive
3475      rebase to make the commit editable, or if that is not possible
3476      because the commit is not reachable from ‘HEAD’ by checking out
3477      that commit directly.  This also causes the actual worktree file to
3478      be visited.
3479
3480      Neither the blob nor the file buffer are killed when finishing the
3481      rebase.  If that is undesirable, then it might be better to use
3482      ‘magit-rebase-edit-command’ instead of this command.
3483
3484 ‘j’     (‘magit-jump-to-diffstat-or-diff’)
3485
3486      Jump to the diffstat or diff.  When point is on a file inside the
3487      diffstat section, then jump to the respective diff section.
3488      Otherwise, jump to the diffstat section or a child thereof.
3489
3490 ‘SPC’     (‘scroll-up’)
3491
3492      Scroll text upward.
3493
3494 ‘DEL’     (‘scroll-down’)
3495
3496      Scroll text downward.
3497
3498 
3499 File: magit.info,  Node: Diff Options,  Next: Revision Buffer,  Prev: Diff Buffer,  Up: Diffing
3500
3501 5.4.3 Diff Options
3502 ------------------
3503
3504  -- User Option: magit-diff-refine-hunk
3505
3506      Whether to show word-granularity differences within diff hunks.
3507
3508         • ‘nil’ never show fine differences.
3509
3510         • ‘t’ show fine differences for the current diff hunk only.
3511
3512         • ‘all’ show fine differences for all displayed diff hunks.
3513
3514  -- User Option: magit-diff-adjust-tab-width
3515
3516      Whether to adjust the width of tabs in diffs.
3517
3518      Determining the correct width can be expensive if it requires
3519      opening large and/or many files, so the widths are cached in the
3520      variable ‘magit-diff--tab-width-cache’.  Set that to nil to
3521      invalidate the cache.
3522
3523         • ‘nil’ Never adjust tab width.  Use ‘tab-width’s value from the
3524           Magit buffer itself instead.
3525
3526         • ‘t’ If the corresponding file-visiting buffer exits, then use
3527           ‘tab-width’’s value from that buffer.  Doing this is cheap, so
3528           this value is used even if a corresponding cache entry exists.
3529
3530         • ‘always’ If there is no such buffer, then temporarily visit
3531           the file to determine the value.
3532
3533         • NUMBER Like ‘always’, but don’t visit files larger than NUMBER
3534           bytes.
3535
3536  -- User Option: magit-diff-paint-whitespace
3537
3538      Specify where to highlight whitespace errors.
3539
3540      See ‘magit-diff-highlight-trailing’,
3541      ‘magit-diff-highlight-indentation’.  The symbol ‘t’ means in all
3542      diffs, ‘status’ means only in the status buffer, and nil means
3543      nowhere.
3544
3545  -- User Option: magit-diff-highlight-trailing
3546
3547      Whether to highlight whitespace at the end of a line in diffs.
3548      Used only when ‘magit-diff-paint-whitespace’ is non-nil.
3549
3550  -- User Option: magit-diff-highlight-indentation
3551
3552      Highlight the "wrong" indentation style.  Used only when
3553      ‘magit-diff-paint-whitespace’ is non-nil.
3554
3555      The value is a list of cons cells.  The car is a regular
3556      expression, and the cdr is the value that applies to repositories
3557      whose directory matches the regular expression.  If more than one
3558      element matches, then the *last* element in the list applies.  The
3559      default value should therefore come first in the list.
3560
3561      If the value is ‘tabs’, highlight indentation with tabs.  If the
3562      value is an integer, highlight indentation with at least that many
3563      spaces.  Otherwise, highlight neither.
3564
3565  -- User Option: magit-diff-hide-trailing-cr-characters
3566
3567      Whether to hide ^M characters at the end of a line in diffs.
3568
3569  -- User Option: magit-diff-highlight-hunk-region-functions
3570
3571      This option specifies the functions used to highlight the
3572      hunk-internal region.
3573
3574      ‘magit-diff-highlight-hunk-region-dim-outside’ overlays the outside
3575      of the hunk internal selection with a face that causes the added
3576      and removed lines to have the same background color as context
3577      lines.  This function should not be removed from the value of this
3578      option.
3579
3580      ‘magit-diff-highlight-hunk-region-using-overlays’ and
3581      ‘magit-diff-highlight-hunk-region-using-underline’ emphasize the
3582      region by placing delimiting horizontal lines before and after it.
3583      Both of these functions have glitches which cannot be fixed due to
3584      limitations of Emacs’ display engine.  For more information see
3585      <https://github.com/magit/magit/issues/2758> ff.
3586
3587      Instead of, or in addition to, using delimiting horizontal lines,
3588      to emphasize the boundaries, you may which to emphasize the text
3589      itself, using ‘magit-diff-highlight-hunk-region-using-face’.
3590
3591      In terminal frames it’s not possible to draw lines as the overlay
3592      and underline variants normally do, so there they fall back to
3593      calling the face function instead.
3594
3595  -- User Option: magit-diff-unmarked-lines-keep-foreground
3596
3597      This option controls whether added and removed lines outside the
3598      hunk-internal region only lose their distinct background color or
3599      also the foreground color.  Whether the outside of the region is
3600      dimmed at all depends on
3601      ‘magit-diff-highlight-hunk-region-functions’.
3602
3603 
3604 File: magit.info,  Node: Revision Buffer,  Prev: Diff Options,  Up: Diffing
3605
3606 5.4.4 Revision Buffer
3607 ---------------------
3608
3609  -- User Option: magit-revision-insert-related-refs
3610
3611      Whether to show related branches in revision buffers.
3612
3613         • ‘nil’ Don’t show any related branches.
3614
3615         • ‘t’ Show related local branches.
3616
3617         • ‘all’ Show related local and remote branches.
3618
3619         • ‘mixed’ Show all containing branches and local merged
3620           branches.
3621
3622  -- User Option: magit-revision-show-gravatars
3623
3624      Whether to show gravatar images in revision buffers.
3625
3626      If ‘nil’, then don’t insert any gravatar images.  If ‘t’, then
3627      insert both images.  If ‘author’ or ‘committer’, then insert only
3628      the respective image.
3629
3630      If you have customized the option ‘magit-revision-header-format’
3631      and want to insert the images then you might also have to specify
3632      where to do so.  In that case the value has to be a cons-cell of
3633      two regular expressions.  The car specifies where to insert the
3634      author’s image.  The top half of the image is inserted right after
3635      the matched text, the bottom half on the next line in the same
3636      column.  The cdr specifies where to insert the committer’s image,
3637      accordingly.  Either the car or the cdr may be nil."
3638
3639  -- User Option: magit-revision-use-hash-sections
3640
3641      Whether to turn hashes inside the commit message into sections.
3642
3643      If non-nil, then hashes inside the commit message are turned into
3644      ‘commit’ sections.  There is a trade off to be made between
3645      performance and reliability:
3646
3647         • ‘slow’ calls git for every word to be absolutely sure.
3648
3649         • ‘quick’ skips words less than seven characters long.
3650
3651         • ‘quicker’ additionally skips words that don’t contain a
3652           number.
3653
3654         • ‘quickest’ uses all words that are at least seven characters
3655           long and which contain at least one number as well as at least
3656           one letter.
3657
3658      If nil, then no hashes are turned into sections, but you can still
3659      visit the commit at point using "RET".
3660
3661    The diffs shown in the revision buffer may be automatically
3662 restricted to a subset of the changed files.  If the revision buffer is
3663 displayed from a log buffer, the revision buffer will share the same
3664 file restriction as that log buffer (also see the command
3665 ‘magit-diff-toggle-file-filter’).  Note, however, that the log’s file
3666 restriction will be ignored when ‘magit-log-arguments’ includes
3667 ‘--follow’.  In this case, the ‘-u’ argument of the log popup can be
3668 used to show the file-restricted diffs inline.
3669
3670    If the revision buffer is not displayed from a log buffer, the file
3671 restriction is determined by the file restriction in the repository’s
3672 diff buffer, if it exists, and the value of the option
3673 ‘magit-use-sticky-arguments’.
3674
3675 
3676 File: magit.info,  Node: Ediffing,  Next: References Buffer,  Prev: Diffing,  Up: Inspecting
3677
3678 5.5 Ediffing
3679 ============
3680
3681 This section describes how to enter Ediff from Magit buffers.  For
3682 information on how to use Ediff itself, see *note (ediff)Top::.
3683
3684 ‘e’     (‘magit-ediff-dwim’)
3685
3686      Compare, stage, or resolve using Ediff.
3687
3688      This command tries to guess what file, and what commit or range the
3689      user wants to compare, stage, or resolve using Ediff.  It might
3690      only be able to guess either the file, or range/commit, in which
3691      case the user is asked about the other.  It might not always guess
3692      right, in which case the appropriate ‘magit-ediff-*’ command has to
3693      be used explicitly.  If it cannot read the user’s mind at all, then
3694      it asks the user for a command to run.
3695
3696 ‘E’     (‘magit-ediff-popup’)
3697
3698      This prefix command shows the following suffix commands in a popup
3699      buffer.
3700
3701 ‘E r’     (‘magit-ediff-compare’)
3702
3703      Compare two revisions of a file using Ediff.
3704
3705      If the region is active, use the revisions on the first and last
3706      line of the region.  With a prefix argument, instead of diffing the
3707      revisions, choose a revision to view changes along, starting at the
3708      common ancestor of both revisions (i.e., use a "..." range).
3709
3710 ‘E m’     (‘magit-ediff-resolve’)
3711
3712      Resolve outstanding conflicts in a file using Ediff, defaulting to
3713      the file at point.
3714
3715      Provided that the value of ‘merge.conflictstyle’ is ‘diff3’, you
3716      can view the file’s merge-base revision using ‘/’ in the Ediff
3717      control buffer.
3718
3719      In the rare event that you want to manually resolve all conflicts,
3720      including those already resolved by Git, use
3721      ‘ediff-merge-revisions-with-ancestor’.
3722
3723 ‘E s’     (‘magit-ediff-stage’)
3724
3725      Stage and unstage changes to a file using Ediff, defaulting to the
3726      file at point.
3727
3728 ‘E u’     (‘magit-ediff-show-unstaged’)
3729
3730      Show unstaged changes to a file using Ediff.
3731
3732 ‘E i’     (‘magit-ediff-show-staged’)
3733
3734      Show staged changes to a file using Ediff.
3735
3736 ‘E w’     (‘magit-ediff-show-working-tree’)
3737
3738      Show changes in a file between ‘HEAD’ and working tree using Ediff.
3739
3740 ‘E c’     (‘magit-ediff-show-commit’)
3741
3742      Show changes to a file introduced by a commit using Ediff.
3743
3744 ‘E z’     (‘magit-ediff-show-stash’)
3745
3746      Show changes to a file introduced by a stash using Ediff.
3747
3748  -- User Option: magit-ediff-dwim-show-on-hunks
3749
3750      This option controls what command ‘magit-ediff-dwim’ calls when
3751      point is on uncommitted hunks.  When nil, always run
3752      ‘magit-ediff-stage’.  Otherwise, use ‘magit-ediff-show-staged’ and
3753      ‘magit-ediff-show-unstaged’ to show staged and unstaged changes,
3754      respectively.
3755
3756  -- User Option: magit-ediff-show-stash-with-index
3757
3758      This option controls whether ‘magit-ediff-show-stash’ includes a
3759      buffer containing the file’s state in the index at the time the
3760      stash was created.  This makes it possible to tell which changes in
3761      the stash were staged.
3762
3763  -- User Option: magit-ediff-quit-hook
3764
3765      This hook is run after quitting an Ediff session that was created
3766      using a Magit command.  The hook functions are run inside the Ediff
3767      control buffer, and should not change the current buffer.
3768
3769      This is similar to ‘ediff-quit-hook’ but takes the needs of Magit
3770      into account.  The regular ‘ediff-quit-hook’ is ignored by Ediff
3771      sessions that were created using a Magit command.
3772
3773 
3774 File: magit.info,  Node: References Buffer,  Next: Bisecting,  Prev: Ediffing,  Up: Inspecting
3775
3776 5.6 References Buffer
3777 =====================
3778
3779 ‘y’     (‘magit-show-refs-popup’)
3780
3781      List and compare references in a dedicated buffer.  By default all
3782      refs are compared with ‘HEAD’, but with a prefix argument this
3783      command instead acts as a prefix command and shows the following
3784      suffix commands along with the appropriate infix arguments in a
3785      popup buffer.
3786
3787 ‘y y’     (‘magit-show-refs-head’)
3788
3789      List and compare references in a dedicated buffer.  Refs are
3790      compared with ‘HEAD’.
3791
3792 ‘y c’     (‘magit-show-refs-current’)
3793
3794      List and compare references in a dedicated buffer.  Refs are
3795      compared with the current branch or ‘HEAD’ if it is detached.
3796
3797 ‘y o’     (‘magit-show-refs’)
3798
3799      List and compare references in a dedicated buffer.  Refs are
3800      compared with a branch read from the user.
3801
3802  -- User Option: magit-refs-show-commit-count
3803
3804      Whether to show commit counts in Magit-Refs mode buffers.
3805
3806         • ‘all’ Show counts for branches and tags.
3807
3808         • ‘branch’ Show counts for branches only.
3809
3810         • ‘nil’ Never show counts.
3811
3812      The default is ‘nil’ because anything else can be very expensive.
3813
3814  -- User Option: magit-refs-pad-commit-counts
3815
3816      Whether to pad all commit counts on all sides in Magit-Refs mode
3817      buffers.
3818
3819      If this is nil, then some commit counts are displayed right next to
3820      one of the branches that appear next to the count, without any
3821      space in between.  This might look bad if the branch name faces
3822      look too similar to ‘magit-dimmed’.
3823
3824      If this is non-nil, then spaces are placed on both sides of all
3825      commit counts.
3826
3827  -- User Option: magit-refs-show-remote-prefix
3828
3829      Whether to show the remote prefix in lists of remote branches.
3830
3831      Showing the prefix is redundant because the name of the remote is
3832      already shown in the heading preceding the list of its branches.
3833
3834  -- User Option: magit-refs-primary-column-width
3835
3836      Width of the primary column in ‘magit-refs-mode’ buffers.  The
3837      primary column is the column that contains the name of the branch
3838      that the current row is about.
3839
3840      If this is an integer, then the column is that many columns wide.
3841      Otherwise it has to be a cons-cell of two integers.  The first
3842      specifies the minimal width, the second the maximal width.  In that
3843      case the actual width is determined using the length of the names
3844      of the shown local branches.  (Remote branches and tags are not
3845      taken into account when calculating to optimal width.)
3846
3847  -- User Option: magit-refs-focus-column-width
3848
3849      Width of the focus column in ‘magit-refs-mode’ buffers.
3850
3851      The focus column is the first column, which marks one branch
3852      (usually the current branch) as the focused branch using ‘*’ or
3853      ‘@’.  For each other reference, this column optionally shows how
3854      many commits it is ahead of the focused branch and ‘<’, or if it
3855      isn’t ahead then the commits it is behind and ‘>’, or if it isn’t
3856      behind either, then a ‘=’.
3857
3858      This column may also display only ‘*’ or ‘@’ for the focused
3859      branch, in which case this option is ignored.  Use ‘L v’ to change
3860      the verbosity of this column.
3861
3862  -- User Option: magit-refs-margin
3863
3864      This option specifies whether the margin is initially shown in
3865      Magit-Refs mode buffers and how it is formatted.
3866
3867      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
3868
3869         • If INIT is non-nil, then the margin is shown initially.
3870
3871         • STYLE controls how to format the committer date.  It can be
3872           one of ‘age’ (to show the age of the commit),
3873           ‘age-abbreviated’ (to abbreviate the time unit to a
3874           character), or a string (suitable for ‘format-time-string’) to
3875           show the actual date.
3876
3877         • WIDTH controls the width of the margin.  This exists for
3878           forward compatibility and currently the value should not be
3879           changed.
3880
3881         • AUTHOR controls whether the name of the author is also shown
3882           by default.
3883
3884         • AUTHOR-WIDTH has to be an integer.  When the name of the
3885           author is shown, then this specifies how much space is used to
3886           do so.
3887
3888  -- User Option: magit-refs-margin-for-tags
3889
3890      This option specifies whether to show information about tags in the
3891      margin.  This is disabled by default because it is slow if there
3892      are many tags.
3893
3894    The following variables control how individual refs are displayed.
3895 If you change one of these variables (especially the "%c" part), then
3896 you should also change the others to keep things aligned.  The following
3897 %-sequences are supported:
3898
3899    • ‘%a’ Number of commits this ref has over the one we compare to.
3900
3901    • ‘%b’ Number of commits the ref we compare to has over this one.
3902
3903    • ‘%c’ Number of commits this ref has over the one we compare to.
3904      For the ref which all other refs are compared this is instead "@",
3905      if it is the current branch, or "#" otherwise.
3906
3907    • ‘%C’ For the ref which all other refs are compared this is "@", if
3908      it is the current branch, or "#" otherwise.  For all other refs "
3909      ".
3910
3911    • ‘%h’ Hash of this ref’s tip.
3912
3913    • ‘%m’ Commit summary of the tip of this ref.
3914
3915    • ‘%n’ Name of this ref.
3916
3917    • ‘%u’ Upstream of this local branch.
3918
3919    • ‘%U’ Upstream of this local branch and additional local vs.
3920      upstream information.
3921
3922  -- User Option: magit-refs-filter-alist
3923
3924      This alist controls which tags and branches are omitted from being
3925      displayed in ‘magit-refs-mode’ buffers.  If it is ‘nil’, then all
3926      refs are displayed (subject to ‘magit-refs-sections-hook’).
3927
3928      All keys are tried in order until one matches.  Then its value is
3929      used and subsequent elements are ignored.  If the value is non-nil,
3930      then the reference is displayed, otherwise it is not.  If no
3931      element matches, then the reference is displayed.
3932
3933      A key can either be a regular expression that the refname has to
3934      match, or a function that takes the refname as only argument and
3935      returns a boolean.  Contrary to how they are displayed in the
3936      buffer, for comparison each tag begins with "tags/" and each remote
3937      branch with "<remote>/".
3938
3939 ‘RET’     (‘magit-visit-ref’)
3940
3941      This command visits the reference or revision at point in another
3942      buffer.  If there is no revision at point or with a prefix argument
3943      then it prompts for a revision.
3944
3945      This command behaves just like ‘magit-show-commit’ as described
3946      above, except if point is on a reference in a ‘magit-refs-mode’
3947      buffer, in which case the behavior may be different, but only if
3948      you have customized the option ‘magit-visit-ref-behavior’.
3949
3950  -- User Option: magit-visit-ref-behavior
3951
3952      This option controls how ‘magit-visit-ref’ behaves in
3953      ‘magit-refs-mode’ buffers.
3954
3955      By default ‘magit-visit-ref’ behaves like ‘magit-show-commit’, in
3956      all buffers, including ‘magit-refs-mode’ buffers.  When the type of
3957      the section at point is ‘commit’ then "RET" is bound to
3958      ‘magit-show-commit’, and when the type is either ‘branch’ or ‘tag’
3959      then it is bound to ‘magit-visit-ref’.
3960
3961      "RET" is one of Magit’s most essential keys and at least by default
3962      it should behave consistently across all of Magit, especially
3963      because users quickly learn that it does something very harmless;
3964      it shows more information about the thing at point in another
3965      buffer.
3966
3967      However "RET" used to behave differently in ‘magit-refs-mode’
3968      buffers, doing surprising things, some of which cannot really be
3969      described as "visit this thing".  If you’ve grown accustomed this
3970      behavior, you can restore it by adding one or more of the below
3971      symbols to the value of this option.  But keep in mind that by
3972      doing so you don’t only introduce inconsistencies, you also lose
3973      some functionality and might have to resort to ‘M-x
3974      magit-show-commit’ to get it back.
3975
3976      ‘magit-visit-ref’ looks for these symbols in the order in which
3977      they are described here.  If the presence of a symbol applies to
3978      the current situation, then the symbols that follow do not affect
3979      the outcome.
3980
3981         • ‘focus-on-ref’
3982
3983           With a prefix argument update the buffer to show commit counts
3984           and lists of cherry commits relative to the reference at point
3985           instead of relative to the current buffer or ‘HEAD’.
3986
3987           Instead of adding this symbol, consider pressing "C-u y o
3988           RET".
3989
3990         • ‘create-branch’
3991
3992           If point is on a remote branch, then create a new local branch
3993           with the same name, use the remote branch as its upstream, and
3994           then check out the local branch.
3995
3996           Instead of adding this symbol, consider pressing "b c RET
3997           RET", like you would do in other buffers.
3998
3999         • ‘checkout-any’
4000
4001           Check out the reference at point.  If that reference is a tag
4002           or a remote branch, then this results in a detached ‘HEAD’.
4003
4004           Instead of adding this symbol, consider pressing "b b RET",
4005           like you would do in other buffers.
4006
4007         • ‘checkout-branch’
4008
4009           Check out the local branch at point.
4010
4011           Instead of adding this symbol, consider pressing "b b RET",
4012           like you would do in other buffers.
4013
4014 * Menu:
4015
4016 * References Sections::
4017
4018 
4019 File: magit.info,  Node: References Sections,  Up: References Buffer
4020
4021 5.6.1 References Sections
4022 -------------------------
4023
4024 The contents of references buffers is controlled using the hook
4025 ‘magit-refs-sections-hook’.  See *note Section Hooks:: to learn about
4026 such hooks and how to customize them.  All of the below functions are
4027 members of the default value.  Note that it makes much less sense to
4028 customize this hook than it does for the respective hook used for the
4029 status buffer.
4030
4031  -- User Option: magit-refs-sections-hook
4032
4033      Hook run to insert sections into a references buffer.
4034
4035  -- Function: magit-insert-local-branches
4036
4037      Insert sections showing all local branches.
4038
4039  -- Function: magit-insert-remote-branches
4040
4041      Insert sections showing all remote-tracking branches.
4042
4043  -- Function: magit-insert-tags
4044
4045      Insert sections showing all tags.
4046
4047 
4048 File: magit.info,  Node: Bisecting,  Next: Visiting Blobs,  Prev: References Buffer,  Up: Inspecting
4049
4050 5.7 Bisecting
4051 =============
4052
4053 Also see *note (gitman)git-bisect::.
4054
4055 ‘B’     (‘magit-bisect-popup’)
4056
4057      This prefix command shows the following suffix commands in a popup
4058      buffer.
4059
4060    When bisecting is not in progress, then the popup buffer features the
4061 following commands.
4062
4063 ‘B B’     (‘magit-bisect-start’)
4064
4065      Start a bisect session.
4066
4067      Bisecting a bug means to find the commit that introduced it.  This
4068      command starts such a bisect session by asking for a known good and
4069      a bad commit.
4070
4071 ‘B s’     (‘magit-bisect-run’)
4072
4073      Bisect automatically by running commands after each step.
4074
4075    When bisecting is in progress, then the popup buffer features these
4076 commands instead.
4077
4078 ‘B b’     (‘magit-bisect-bad’)
4079
4080      Mark the current commit as bad.  Use this after you have asserted
4081      that the commit does contain the bug in question.
4082
4083 ‘B g’     (‘magit-bisect-good’)
4084
4085      Mark the current commit as good.  Use this after you have asserted
4086      that the commit does not contain the bug in question.
4087
4088 ‘B k’     (‘magit-bisect-skip’)
4089
4090      Skip the current commit.  Use this if for some reason the current
4091      commit is not a good one to test.  This command lets Git choose a
4092      different one.
4093
4094 ‘B r’     (‘magit-bisect-reset’)
4095
4096      After bisecting, cleanup bisection state and return to original
4097      ‘HEAD’.
4098
4099    By default the status buffer shows information about the ongoing
4100 bisect session.
4101
4102  -- User Option: magit-bisect-show-graph
4103
4104      This option controls whether a graph is displayed for the log of
4105      commits that still have to be bisected.
4106
4107 
4108 File: magit.info,  Node: Visiting Blobs,  Next: Blaming,  Prev: Bisecting,  Up: Inspecting
4109
4110 5.8 Visiting Blobs
4111 ==================
4112
4113 ‘M-x magit-find-file’     (‘magit-find-file’)
4114
4115      View FILE from REV.  Switch to a buffer visiting blob REV:FILE,
4116      creating one if none already exists.
4117
4118 ‘M-x magit-find-file-other-window’     (‘magit-find-file-other-window’)
4119
4120      View FILE from REV, in another window.  Like ‘magit-find-file’, but
4121      create a new window or reuse an existing one.
4122
4123 
4124 File: magit.info,  Node: Blaming,  Prev: Visiting Blobs,  Up: Inspecting
4125
4126 5.9 Blaming
4127 ===========
4128
4129 Also see *note (gitman)git-blame::.
4130
4131    To start blaming you can use ‘M-x’ in a file-visiting buffer to
4132 invoke one of the following commands.  You can also invoke these
4133 commands using the blame popup, which is available on ‘b’ in
4134 file-visiting buffers that already contain blame information and, also
4135 on ‘b’, in all blob-visiting buffers.  You can also enter the blame
4136 popup from the file popup, which is available on ‘C-c M-g’, provided
4137 ‘magit-file-mode’ is enabled, see *note Minor Mode for Buffers Visiting
4138 Files::.
4139
4140  -- Command: magit-blame-addition
4141
4142      This command augments each line or chunk of lines in the current
4143      file- or blob-visiting buffer with information about what commits
4144      last touched these lines.
4145
4146      If the buffer visits a revision of that file, then history up to
4147      that revision is considered.  Otherwise, the file’s full history is
4148      considered, including uncommitted changes.
4149
4150      If Magit-Blame mode is already turned on in the current buffer then
4151      blaming is done recursively, by visiting REVISION:FILE (using
4152      ‘magit-find-file’), where REVISION is a parent of the revision that
4153      added the current line or chunk of lines.
4154
4155  -- Command: magit-blame-echo
4156
4157      This command is like ‘magit-blame-addition’ except that it doesn’t
4158      turn on ‘read-only-mode’ and that it initially uses the
4159      visualization style specified by option ‘magit-blame-echo-style’.
4160
4161  -- Command: magit-blame-removal
4162
4163      This command augments each line or chunk of lines in the current
4164      blob-visiting buffer with information about the revision that
4165      removes it.  It cannot be used in file-visiting buffers.
4166
4167      Like ‘magit-blame-addition’, this command can be used recursively.
4168
4169  -- Command: magit-blame-reverse
4170
4171      This command augments each line or chunk of lines in the current
4172      file- or blob-visiting buffer with information about the last
4173      revision in which a line still existed.
4174
4175      Like ‘magit-blame-addition’, this command can be used recursively.
4176
4177    The following key bindings are available when Magit-Blame mode is
4178 enabled and Read-Only mode is not enabled.  These commands are also
4179 available in other buffers; here only the behavior is described that is
4180 relevant in file-visiting buffers that are being blamed.
4181
4182 ‘RET’     (‘magit-show-commit’)
4183
4184      This command shows the commit that last touched the line at point.
4185
4186 ‘SPC’     (‘magit-diff-show-or-scroll-up’)
4187
4188      This command updates the commit buffer.
4189
4190      This either shows the commit that last touched the line at point in
4191      the appropriate buffer, or if that buffer is already being
4192      displayed in the current frame and if that buffer contains
4193      information about that commit, then the buffer is scrolled up
4194      instead.
4195
4196 ‘DEL’     (‘magit-diff-show-or-scroll-down’)
4197
4198      This command updates the commit buffer.
4199
4200      This either shows the commit that last touched the line at point in
4201      the appropriate buffer, or if that buffer is already being
4202      displayed in the current frame and if that buffer contains
4203      information about that commit, then the buffer is scrolled down
4204      instead.
4205
4206    The following key bindings are available when Magit-Blame mode is
4207 enabled and Read-Only mode is not enabled.
4208
4209 ‘b’     (‘magit-blame-popup’)
4210
4211      This prefix command shows the above suffix command along with the
4212      appropriate infix arguments in a popup buffer.
4213
4214 ‘n’     (‘magit-blame-next-chunk’)
4215
4216      This command moves to the next chunk.
4217
4218 ‘N’     (‘magit-blame-next-chunk-same-commit’)
4219
4220      This command moves to the next chunk from the same commit.
4221
4222 ‘p’     (‘magit-blame-previous-chunk’)
4223
4224      This command moves to the previous chunk.
4225
4226 ‘P’     (‘magit-blame-previous-chunk-same-commit’)
4227
4228      This command moves to the previous chunk from the same commit.
4229
4230 ‘q’     (‘magit-blame-quit’)
4231
4232      This command turns off Magit-Blame mode.  If the buffer was created
4233      during a recursive blame, then it also kills the buffer.
4234
4235 ‘M-w’     (‘magit-blame-copy-hash’)
4236
4237      This command saves the hash of the current chunk’s commit to the
4238      kill ring.
4239
4240      When the region is active, the command saves the region’s content
4241      instead of the hash, like ‘kill-ring-save’ would.
4242
4243 ‘c’     (‘magit-blame-cycle-style’)
4244
4245      This command changes how blame information is visualized in the
4246      current buffer by cycling through the styles specified using the
4247      option ‘magit-blame-styles’.
4248
4249    Blaming is also controlled using the following options.
4250
4251  -- User Option: magit-blame-styles
4252
4253      This option defines a list of styles used to visualize blame
4254      information.  For now see its doc-string to learn more.
4255
4256  -- User Option: magit-blame-echo-style
4257
4258      This option specifies the blame visualization style used by the
4259      command ‘magit-blame-echo’.  This must be a symbol that is used as
4260      the identifier for one of the styles defined in
4261      ‘magit-blame-styles’.
4262
4263  -- User Option: magit-blame-time-format
4264
4265      This option specifies the format string used to display times when
4266      showing blame information.
4267
4268  -- User Option: magit-blame-read-only
4269
4270      This option controls whether blaming a buffer also makes
4271      temporarily read-only.
4272
4273  -- User Option: magit-blame-disable-modes
4274
4275      This option lists incompatible minor-modes that should be disabled
4276      temporarily when a buffer contains blame information.  They are
4277      enabled again when the buffer no longer shows blame information.
4278
4279  -- User Option: magit-blame-goto-chunk-hook
4280
4281      This hook is run when moving between chunks.
4282
4283 
4284 File: magit.info,  Node: Manipulating,  Next: Transferring,  Prev: Inspecting,  Up: Top
4285
4286 6 Manipulating
4287 **************
4288
4289 * Menu:
4290
4291 * Repository Setup::
4292 * Staging and Unstaging::
4293 * Applying::
4294 * Committing::
4295 * Branching::
4296 * Merging::
4297 * Resolving Conflicts::
4298 * Rebasing::
4299 * Cherry Picking::
4300 * Resetting::
4301 * Stashing::
4302
4303 
4304 File: magit.info,  Node: Repository Setup,  Next: Staging and Unstaging,  Up: Manipulating
4305
4306 6.1 Repository Setup
4307 ====================
4308
4309 ‘M-x magit-init’     (‘magit-init’)
4310
4311      This command initializes a repository and then shows the status
4312      buffer for the new repository.
4313
4314      If the directory is below an existing repository, then the user has
4315      to confirm that a new one should be created inside.  If the
4316      directory is the root of the existing repository, then the user has
4317      to confirm that it should be reinitialized.
4318
4319 ‘M-x magit-clone’     (‘magit-clone’)
4320
4321      This command clones a repository and then shows the status buffer
4322      for the new repository.
4323
4324      The user is queried for a remote url and a local directory.
4325
4326  -- User Option: magit-clone-set-remote.pushDefault
4327
4328      Whether to set the value of ‘remote.pushDefault’ after cloning.
4329
4330      If ‘t’, then set without asking.  If ‘nil’, then don’t set.  If
4331      ‘ask’, then ask the user every time she clones a repository.
4332
4333 
4334 File: magit.info,  Node: Staging and Unstaging,  Next: Applying,  Prev: Repository Setup,  Up: Manipulating
4335
4336 6.2 Staging and Unstaging
4337 =========================
4338
4339 Like Git, Magit can of course stage and unstage complete files.  Unlike
4340 Git, it also allows users to gracefully un-/stage individual hunks and
4341 even just part of a hunk.  To stage individual hunks and parts of hunks
4342 using Git directly, one has to use the very modal and rather clumsy
4343 interface of a ‘git add --interactive’ session.
4344
4345    With Magit, on the other hand, one can un-/stage individual hunks by
4346 just moving point into the respective section inside a diff displayed in
4347 the status buffer or a separate diff buffer and typing ‘s’ or ‘u’.  To
4348 operate on just parts of a hunk, mark the changes that should be
4349 un-/staged using the region and then press the same key that would be
4350 used to un-/stage.  To stage multiple files or hunks at once use a
4351 region that starts inside the heading of such a section and ends inside
4352 the heading of a sibling section of the same type.
4353
4354    Besides staging and unstaging, Magit also provides several other
4355 "apply variants" that can also operate on a file, multiple files at
4356 once, a hunk, multiple hunks at once, and on parts of a hunk.  These
4357 apply variants are described in the next section.
4358
4359    You can also use Ediff to stage and unstage.  See *note Ediffing::.
4360
4361 ‘s’     (‘magit-stage’)
4362
4363      Add the change at point to the staging area.
4364
4365      With a prefix argument and an untracked file (or files) at point,
4366      stage the file but not its content.  This makes it possible to
4367      stage only a subset of the new file’s changes.
4368
4369 ‘S’     (‘magit-stage-modified’)
4370
4371      Stage all changes to files modified in the worktree.  Stage all new
4372      content of tracked files and remove tracked files that no longer
4373      exist in the working tree from the index also.  With a prefix
4374      argument also stage previously untracked (but not ignored) files.
4375
4376 ‘u’     (‘magit-unstage’)
4377
4378      Remove the change at point from the staging area.
4379
4380      Only staged changes can be unstaged.  But by default this command
4381      performs an action that is somewhat similar to unstaging, when it
4382      is called on a committed change: it reverses the change in the
4383      index but not in the working tree.
4384
4385 ‘U’     (‘magit-unstage-all’)
4386
4387      Remove all changes from the staging area.
4388
4389  -- User Option: magit-unstage-committed
4390
4391      This option controls whether ‘magit-unstage’ "unstages" committed
4392      changes by reversing them in the index but not the working tree.
4393      The alternative is to raise an error.
4394
4395 ‘M-x magit-reverse-in-index’     (‘magit-reverse-in-index’)
4396
4397      This command reverses the committed change at point in the index
4398      but not the working tree.  By default no key is bound directly to
4399      this command, but it is indirectly called when ‘u’
4400      (‘magit-unstage’) is pressed on a committed change.
4401
4402      This allows extracting a change from ‘HEAD’, while leaving it in
4403      the working tree, so that it can later be committed using a
4404      separate commit.  A typical workflow would be:
4405
4406         • Optionally make sure that there are no uncommitted changes.
4407
4408         • Visit the ‘HEAD’ commit and navigate to the change that should
4409           not have been included in that commit.
4410
4411         • Type ‘u’ (‘magit-unstage’) to reverse it in the index.  This
4412           assumes that ‘magit-unstage-committed-changes’ is non-nil.
4413
4414         • Type ‘c e’ to extend ‘HEAD’ with the staged changes, including
4415           those that were already staged before.
4416
4417         • Optionally stage the remaining changes using ‘s’ or ‘S’ and
4418           then type ‘c c’ to create a new commit.
4419
4420 ‘M-x magit-reset-index’     (‘magit-reset-index’)
4421
4422      Reset the index to some commit.  The commit is read from the user
4423      and defaults to the commit at point.  If there is no commit at
4424      point, then it defaults to ‘HEAD’.
4425
4426 * Menu:
4427
4428 * Staging from File-Visiting Buffers::
4429
4430 
4431 File: magit.info,  Node: Staging from File-Visiting Buffers,  Up: Staging and Unstaging
4432
4433 6.2.1 Staging from File-Visiting Buffers
4434 ----------------------------------------
4435
4436 Fine-grained un-/staging has to be done from the status or a diff
4437 buffer, but it’s also possible to un-/stage all changes made to the file
4438 visited in the current buffer right from inside that buffer.
4439
4440 ‘M-x magit-stage-file’     (‘magit-stage-file’)
4441
4442      When invoked inside a file-visiting buffer, then stage all changes
4443      to that file.  In a Magit buffer, stage the file at point if any.
4444      Otherwise prompt for a file to be staged.  With a prefix argument
4445      always prompt the user for a file, even in a file-visiting buffer
4446      or when there is a file section at point.
4447
4448 ‘M-x magit-unstage-file’     (‘magit-unstage-file’)
4449
4450      When invoked inside a file-visiting buffer, then unstage all
4451      changes to that file.  In a Magit buffer, unstage the file at point
4452      if any.  Otherwise prompt for a file to be unstaged.  With a prefix
4453      argument always prompt the user for a file, even in a file-visiting
4454      buffer or when there is a file section at point.
4455
4456 
4457 File: magit.info,  Node: Applying,  Next: Committing,  Prev: Staging and Unstaging,  Up: Manipulating
4458
4459 6.3 Applying
4460 ============
4461
4462 Magit provides several "apply variants": stage, unstage, discard,
4463 reverse, and "regular apply".  At least when operating on a hunk they
4464 are all implemented using ‘git apply’, which is why they are called
4465 "apply variants".
4466
4467    • Stage.  Apply a change from the working tree to the index.  The
4468      change also remains in the working tree.
4469
4470    • Unstage.  Remove a change from the index.  The change remains in
4471      the working tree.
4472
4473    • Discard.  On a staged change, remove it from the working tree and
4474      the index.  On an unstaged change, remove it from the working tree
4475      only.
4476
4477    • Reverse.  Reverse a change in the working tree.  Both committed and
4478      staged changes can be reversed.  Unstaged changes cannot be
4479      reversed.  Discard them instead.
4480
4481    • Apply.  Apply a change to the working tree.  Both committed and
4482      staged changes can be applied.  Unstaged changes cannot be applied
4483      - as they already have been applied.
4484
4485    The previous section described the staging and unstaging commands.
4486 What follows are the commands which implement the remaining apply
4487 variants.
4488
4489 ‘a’     (‘magit-apply’)
4490
4491      Apply the change at point to the working tree.
4492
4493      With a prefix argument fallback to a 3-way merge.  Doing so causes
4494      the change to be applied to the index as well.
4495
4496 ‘k’     (‘magit-discard’)
4497
4498      Remove the change at point from the working tree.
4499
4500 ‘v’     (‘magit-reverse’)
4501
4502      Reverse the change at point in the working tree.
4503
4504      With a prefix argument fallback to a 3-way merge.  Doing so causes
4505      the change to be applied to the index as well.
4506
4507    With a prefix argument all apply variants attempt a 3-way merge when
4508 appropriate (i.e.  when ‘git apply’ is used internally).
4509
4510 
4511 File: magit.info,  Node: Committing,  Next: Branching,  Prev: Applying,  Up: Manipulating
4512
4513 6.4 Committing
4514 ==============
4515
4516 When the user initiates a commit, Magit calls ‘git commit’ without any
4517 arguments, so Git has to get it from the user.  It creates the file
4518 ‘.git/COMMIT_EDITMSG’ and then opens that file in an editor.  Magit
4519 arranges for that editor to be the Emacsclient.  Once the user finishes
4520 the editing session, the Emacsclient exits and Git creates the commit
4521 using the file’s content as message.
4522
4523 * Menu:
4524
4525 * Initiating a Commit::
4526 * Editing Commit Messages::
4527
4528 
4529 File: magit.info,  Node: Initiating a Commit,  Next: Editing Commit Messages,  Up: Committing
4530
4531 6.4.1 Initiating a Commit
4532 -------------------------
4533
4534 Also see *note (gitman)git-commit::.
4535
4536 ‘c’     (‘magit-commit-popup’)
4537
4538      This prefix command shows the following suffix commands along with
4539      the appropriate infix arguments in a popup buffer.
4540
4541 ‘c c’     (‘magit-commit-create’)
4542
4543      Create a new commit on ‘HEAD’.  With a prefix argument amend to the
4544      commit at ‘HEAD’ instead.
4545
4546 ‘c a’     (‘magit-commit-amend’)
4547
4548      Amend the last commit.
4549
4550 ‘c e’     (‘magit-commit-extend’)
4551
4552      Amend the last commit, without editing the message.  With a prefix
4553      argument keep the committer date, otherwise change it.  The option
4554      ‘magit-commit-extend-override-date’ can be used to inverse the
4555      meaning of the prefix argument.
4556
4557      Non-interactively respect the optional OVERRIDE-DATE argument and
4558      ignore the option.
4559
4560 ‘c w’     (‘magit-commit-reword’)
4561
4562      Reword the last commit, ignoring staged changes.  With a prefix
4563      argument keep the committer date, otherwise change it.  The option
4564      ‘magit-commit-reword-override-date’ can be used to inverse the
4565      meaning of the prefix argument.
4566
4567      Non-interactively respect the optional OVERRIDE-DATE argument and
4568      ignore the option.
4569
4570 ‘c f’     (‘magit-commit-fixup’)
4571
4572      Create a fixup commit.
4573
4574      With a prefix argument the target commit has to be confirmed.
4575      Otherwise the commit at point may be used without confirmation
4576      depending on the value of option ‘magit-commit-squash-confirm’.
4577
4578 ‘c F’     (‘magit-commit-instant-fixup’)
4579
4580      Create a fixup commit and instantly rebase.
4581
4582 ‘c s’     (‘magit-commit-squash’)
4583
4584      Create a squash commit, without editing the squash message.
4585
4586      With a prefix argument the target commit has to be confirmed.
4587      Otherwise the commit at point may be used without confirmation
4588      depending on the value of option ‘magit-commit-squash-confirm’.
4589
4590 ‘c S’     (‘magit-commit-instant-squash’)
4591
4592      Create a squash commit and instantly rebase.
4593
4594 ‘c A’     (‘magit-commit-augment’)
4595
4596      Create a squash commit, editing the squash message.
4597
4598      With a prefix argument the target commit has to be confirmed.
4599      Otherwise the commit at point may be used without confirmation
4600      depending on the value of option ‘magit-commit-squash-confirm’.
4601
4602  -- User Option: magit-commit-ask-to-stage
4603
4604      Whether to ask to stage all unstaged changes when committing and
4605      nothing is staged.
4606
4607  -- User Option: magit-commit-extend-override-date
4608
4609      Whether using ‘magit-commit-extend’ changes the committer date.
4610
4611  -- User Option: magit-commit-reword-override-date
4612
4613      Whether using ‘magit-commit-reword’ changes the committer date.
4614
4615  -- User Option: magit-commit-squash-confirm
4616
4617      Whether the commit targeted by squash and fixup has to be
4618      confirmed.  When non-nil then the commit at point (if any) is used
4619      as default choice.  Otherwise it has to be confirmed.  This option
4620      only affects ‘magit-commit-squash’ and ‘magit-commit-fixup’.  The
4621      "instant" variants always require confirmation because making an
4622      error while using those is harder to recover from.
4623
4624 
4625 File: magit.info,  Node: Editing Commit Messages,  Prev: Initiating a Commit,  Up: Committing
4626
4627 6.4.2 Editing Commit Messages
4628 -----------------------------
4629
4630 After initiating a commit as described in the previous section, two new
4631 buffers appear.  One shows the changes that are about to committed,
4632 while the other is used to write the message.  All regular editing
4633 commands are available in the commit message buffer.  This section only
4634 describes the additional commands.
4635
4636    Commit messages are edited in an edit session - in the background Git
4637 is waiting for the editor, in our case the Emacsclient, to save the
4638 commit message in a file (in most cases ‘.git/COMMIT_EDITMSG’) and then
4639 return.  If the Emacsclient returns with a non-zero exit status then Git
4640 does not create the commit.  So the most important commands are those
4641 for finishing and aborting the commit.
4642
4643 ‘C-c C-c’     (‘with-editor-finish’)
4644
4645      Finish the current editing session by returning with exit code 0.
4646      Git then creates the commit using the message it finds in the file.
4647
4648 ‘C-c C-k’     (‘with-editor-cancel’)
4649
4650      Cancel the current editing session by returning with exit code 1.
4651      Git then cancels the commit, but leaves the file untouched.
4652
4653    In addition to being used by Git, these messages may also be stored
4654 in a ring that persists until Emacs is closed.  By default the message
4655 is stored at the beginning and the end of an edit session (regardless of
4656 whether the session is finished successfully or was canceled).  It is
4657 sometimes useful to bring back messages from that ring.
4658
4659 ‘C-c M-s’     (‘git-commit-save-message’)
4660
4661      Save the current buffer content to the commit message ring.
4662
4663 ‘M-p’     (‘git-commit-prev-message’)
4664
4665      Cycle backward through the commit message ring, after saving the
4666      current message to the ring.  With a numeric prefix ARG, go back
4667      ARG comments.
4668
4669 ‘M-n’     (‘git-commit-next-message’)
4670
4671      Cycle forward through the commit message ring, after saving the
4672      current message to the ring.  With a numeric prefix ARG, go back
4673      ARG comments.
4674
4675    By default the diff for the changes that are about to be committed
4676 are automatically shown when invoking the commit.  When amending to an
4677 existing commit it may be useful to show either the changes that are
4678 about to be added to that commit or to show those changes together with
4679 those that are already committed.
4680
4681 ‘C-c C-d’     (‘magit-diff-while-committing’)
4682
4683      While committing, show the changes that are about to be committed.
4684      While amending, invoking the command again toggles between showing
4685      just the new changes or all the changes that will be committed.
4686
4687 ‘C-c C-w’     (‘magit-pop-revision-stack’)
4688
4689      This command inserts a representation of a revision into the
4690      current buffer.  It can be used inside buffers used to write commit
4691      messages but also in other buffers such as buffers used to edit
4692      emails or ChangeLog files.
4693
4694      By default this command pops the revision which was last added to
4695      the ‘magit-revision-stack’ and inserts it into the current buffer
4696      according to ‘magit-pop-revision-stack-format’.  Revisions can be
4697      put on the stack using ‘magit-copy-section-value’ and
4698      ‘magit-copy-buffer-revision’.
4699
4700      If the stack is empty or with a prefix argument it instead reads a
4701      revision in the minibuffer.  By using the minibuffer history this
4702      allows selecting an item which was popped earlier or to insert an
4703      arbitrary reference or revision without first pushing it onto the
4704      stack.
4705
4706      When reading the revision from the minibuffer, then it might not be
4707      possible to guess the correct repository.  When this command is
4708      called inside a repository (e.g.  while composing a commit
4709      message), then that repository is used.  Otherwise (e.g.  while
4710      composing an email) then the repository recorded for the top
4711      element of the stack is used (even though we insert another
4712      revision).  If not called inside a repository and with an empty
4713      stack, or with two prefix arguments, then read the repository in
4714      the minibuffer too.
4715
4716  -- User Option: magit-pop-revision-stack-format
4717
4718      This option controls how the command ‘magit-pop-revision-stack’
4719      inserts a revision into the current buffer.
4720
4721      The entries on the stack have the format ‘(HASH TOPLEVEL)’ and this
4722      option has the format ‘(POINT-FORMAT EOB-FORMAT INDEX-REGEXP)’, all
4723      of which may be nil or a string (though either one of EOB-FORMAT or
4724      POINT-FORMAT should be a string, and if INDEX-REGEXP is non-nil,
4725      then the two formats should be too).
4726
4727      First INDEX-REGEXP is used to find the previously inserted entry,
4728      by searching backward from point.  The first submatch must match
4729      the index number.  That number is incremented by one, and becomes
4730      the index number of the entry to be inserted.  If you don’t want to
4731      number the inserted revisions, then use nil for INDEX-REGEXP.
4732
4733      If INDEX-REGEXP is non-nil then both POINT-FORMAT and EOB-FORMAT
4734      should contain \"%N\", which is replaced with the number that was
4735      determined in the previous step.
4736
4737      Both formats, if non-nil and after removing %N, are then expanded
4738      using ‘git show –format=FORMAT ...’ inside TOPLEVEL.
4739
4740      The expansion of POINT-FORMAT is inserted at point, and the
4741      expansion of EOB-FORMAT is inserted at the end of the buffer (if
4742      the buffer ends with a comment, then it is inserted right before
4743      that).
4744
4745    Some projects use pseudo headers in commit messages.  Magit colorizes
4746 such headers and provides some commands to insert such headers.
4747
4748  -- User Option: git-commit-known-pseudo-headers
4749
4750      A list of Git pseudo headers to be highlighted.
4751
4752 ‘C-c C-a’     (‘git-commit-ack’)
4753
4754      Insert a header acknowledging that you have looked at the commit.
4755
4756 ‘C-c C-r’     (‘git-commit-review’)
4757
4758      Insert a header acknowledging that you have reviewed the commit.
4759
4760 ‘C-c C-s’     (‘git-commit-signoff’)
4761
4762      Insert a header to sign off the commit.
4763
4764 ‘C-c C-t’     (‘git-commit-test’)
4765
4766      Insert a header acknowledging that you have tested the commit.
4767
4768 ‘C-c C-o’     (‘git-commit-cc’)
4769
4770      Insert a header mentioning someone who might be interested.
4771
4772 ‘C-c C-p’     (‘git-commit-reported’)
4773
4774      Insert a header mentioning the person who reported the issue being
4775      fixed by the commit.
4776
4777 ‘C-c C-i’     (‘git-commit-suggested’)
4778
4779      Insert a header mentioning the person who suggested the change.
4780
4781    ‘git-commit-mode’ is a minor mode that is only used to establish the
4782 above key bindings.  This allows using an arbitrary major mode when
4783 editing the commit message.  It’s even possible to use a different major
4784 mode in different repositories, which is useful when different projects
4785 impose different commit message conventions.
4786
4787  -- User Option: git-commit-major-mode
4788
4789      The value of this option is the major mode used to edit Git commit
4790      messages.
4791
4792    Because ‘git-commit-mode’ is a minor mode, we don’t use its mode hook
4793 to setup the buffer, except for the key bindings.  All other setup
4794 happens in the function ‘git-commit-setup’, which among other things
4795 runs the hook ‘git-commit-setup-hook’.  The following functions are
4796 suitable for that hook.
4797
4798  -- User Option: git-commit-setup-hook
4799
4800      Hook run at the end of ‘git-commit-setup’.
4801
4802  -- Function: magit-revert-buffers &optional force
4803
4804      Revert unmodified file-visiting buffers of the current repository.
4805
4806      If either ‘magit-revert-buffers’ is non-nil and
4807      ‘inhibit-magit-revert’ is nil, or if optional FORCE is non-nil,
4808      then revert all unmodified buffers that visit files being tracked
4809      in the current repository.
4810
4811  -- Function: git-commit-save-message
4812
4813      Save the current buffer content to the commit message ring.
4814
4815  -- Function: git-commit-setup-changelog-support
4816
4817      After this function is called, ChangeLog entries are treated as
4818      paragraphs.
4819
4820  -- Function: git-commit-turn-on-auto-fill
4821
4822      Turn on ‘auto-fill-mode’ and set ‘fill-column’ to the value of
4823      ‘git-commit-fill-column’.
4824
4825  -- Function: git-commit-turn-on-flyspell
4826
4827      Turn on Flyspell mode.  Also prevent comments from being checked
4828      and finally check current non-comment text.
4829
4830  -- Function: git-commit-propertize-diff
4831
4832      Propertize the diff shown inside the commit message buffer.  Git
4833      inserts such diffs into the commit message template when the
4834      ‘--verbose’ argument is used.  Magit’s commit popup by default does
4835      not offer that argument because the diff that is shown in a
4836      separate buffer is more useful.  But some users disagree, which is
4837      why this function exists.
4838
4839  -- Function: with-editor-usage-message
4840
4841      Show usage information in the echo area.
4842
4843    Magit also helps with writing *good* commit messages by complaining
4844 when certain rules are violated.
4845
4846  -- User Option: git-commit-summary-max-length
4847
4848      The intended maximal length of the summary line of commit messages.
4849      Characters beyond this column are colorized to indicate that this
4850      preference has been violated.
4851
4852  -- User Option: git-commit-fill-column
4853
4854      Column beyond which automatic line-wrapping should happen in commit
4855      message buffers.
4856
4857  -- User Option: git-commit-finish-query-functions
4858
4859      List of functions called to query before performing commit.
4860
4861      The commit message buffer is current while the functions are
4862      called.  If any of them returns nil, then the commit is not
4863      performed and the buffer is not killed.  The user should then fix
4864      the issue and try again.
4865
4866      The functions are called with one argument.  If it is non-nil then
4867      that indicates that the user used a prefix argument to force
4868      finishing the session despite issues.  Functions should usually
4869      honor this wish and return non-nil.
4870
4871  -- Function: git-commit-check-style-conventions
4872
4873      Check for violations of certain basic style conventions.  For each
4874      violation ask the user if she wants to proceed anyway.  This makes
4875      sure the summary line isn’t too long and that the second line is
4876      empty.
4877
4878    To show no diff while committing remove ‘magit-commit-diff’ from
4879 ‘server-switch-hook’.
4880
4881 
4882 File: magit.info,  Node: Branching,  Next: Merging,  Prev: Committing,  Up: Manipulating
4883
4884 6.5 Branching
4885 =============
4886
4887 * Menu:
4888
4889 * The Two Remotes::
4890 * The Branch Popup::
4891 * The Branch Config Popup::
4892 * Auxiliary Branch Commands::
4893
4894 
4895 File: magit.info,  Node: The Two Remotes,  Next: The Branch Popup,  Up: Branching
4896
4897 6.5.1 The Two Remotes
4898 ---------------------
4899
4900 The upstream branch of some local branch is the branch into which the
4901 commits on that local branch should eventually be merged, usually
4902 something like ‘origin/master’.  For the ‘master’ branch itself the
4903 upstream branch and the branch it is being pushed to, are usually the
4904 same remote branch.  But for a feature branch the upstream branch and
4905 the branch it is being pushed to should differ.
4906
4907    The commits on feature branches too should _eventually_ end up in a
4908 remote branch such as ‘origin/master’ or ‘origin/maint’.  Such a branch
4909 should therefore be used as the upstream.  But feature branches
4910 shouldn’t be pushed directly to such branches.  Instead a feature branch
4911 ‘my-feature’ is usually pushed to ‘my-fork/my-feature’ or if you are a
4912 contributor ‘origin/my-feature’.  After the new feature has been
4913 reviewed, the maintainer merges the feature into ‘master’.  And finally
4914 ‘master’ (not ‘my-feature’ itself) is pushed to ‘origin/master’.
4915
4916    But new features seldom are perfect on the first try, and so feature
4917 branches usually have to be reviewed, improved, and re-pushed several
4918 times.  Pushing should therefore be easy to do, and for that reason many
4919 Git users have concluded that it is best to use the remote branch to
4920 which the local feature branch is being pushed as its upstream.
4921
4922    But luckily Git has long ago gained support for a push-remote which
4923 can be configured separately from the upstream branch, using the
4924 variables ‘branch.<name>.pushRemote’ and ‘remote.pushDefault’.  So we no
4925 longer have to choose which of the two remotes should be used as "the
4926 remote".
4927
4928    Each of the fetching, pulling, and pushing popups features three
4929 commands that act on the current branch and some other branch.  Of
4930 these, ‘p’ is bound to a command which acts on the push-remote, ‘u’ is
4931 bound to a command which acts on the upstream, and ‘e’ is bound to a
4932 command which acts on any other branch.  The status buffer shows
4933 unpushed and unpulled commits for both the push-remote and the upstream.
4934
4935    It’s fairly simple to configure these two remotes.  The values of all
4936 the variables that are related to fetching, pulling, and pushing (as
4937 well as some other branch-related variables) can be inspected and
4938 changed using the popup ‘magit-branch-config-popup’, which is a
4939 sub-popup of many popups that deal with branches.  It is also possible
4940 to set the push-remote or upstream while pushing (see *note Pushing::).
4941
4942 
4943 File: magit.info,  Node: The Branch Popup,  Next: The Branch Config Popup,  Prev: The Two Remotes,  Up: Branching
4944
4945 6.5.2 The Branch Popup
4946 ----------------------
4947
4948 The popup ‘magit-branch-popup’ is used to create and checkout branches,
4949 and to make changes to existing branches.  It is not used to fetch,
4950 pull, merge, rebase, or push branches, i.e.  this popup deals with
4951 branches themselves, not with the commits reachable from them.  Those
4952 features are available from separate popups.
4953
4954 ‘b’     (‘magit-branch-popup’)
4955
4956      This prefix command shows the following suffix commands in a popup
4957      buffer.
4958
4959      By default it also displays the values of some branch-related Git
4960      variables and allows changing their values, just like the
4961      specialized ‘magit-branch-config-popup’ does.
4962
4963  -- User Option: magit-branch-popup-show-variables
4964
4965      Whether the ‘magit-branch-popup’ shows Git variables.  This
4966      defaults to t to avoid changing key bindings.  When set to nil, no
4967      variables are displayed directly in this popup, and the sub-popup
4968      ‘magit-branch-config-popup’ has to be used instead to view and
4969      change branch related variables.
4970
4971 ‘b C’     (‘magit-branch-config-popup’)
4972
4973      This command shows branch related variables in a separate popup.
4974      By default this asks the user for which branch the variables should
4975      be shown.  When ‘magit-branch-popup-show-variables’ is ‘nil’, then
4976      it shows the variables for the current branch, unless a prefix
4977      argument is used.
4978
4979 ‘b b’     (‘magit-checkout’)
4980
4981      Checkout a revision read in the minibuffer and defaulting to the
4982      branch or arbitrary revision at point.  If the revision is a local
4983      branch then that becomes the current branch.  If it is something
4984      else then ‘HEAD’ becomes detached.  Checkout fails if the working
4985      tree or the staging area contain changes.
4986
4987 ‘b n’     (‘magit-branch-create’)
4988
4989      Create a new branch.  The user is asked for a branch or arbitrary
4990      revision to use as the starting point of the new branch.  When a
4991      branch name is provided, then that becomes the upstream branch of
4992      the new branch.  The name of the new branch is also read in the
4993      minibuffer.
4994
4995      Also see option ‘magit-branch-prefer-remote-upstream’.
4996
4997 ‘b c’     (‘magit-branch-and-checkout’)
4998
4999      This command creates a new branch like ‘magit-branch’, but then
5000      also checks it out.
5001
5002      Also see option ‘magit-branch-prefer-remote-upstream’.
5003
5004 ‘b l’     (‘magit-branch-checkout’)
5005
5006      This command checks out an existing or new local branch.  It reads
5007      a branch name from the user offering all local branches and a
5008      subset of remote branches as candidates.  Remote branches for which
5009      a local branch by the same name exists are omitted from the list of
5010      candidates.  The user can also enter a completely new branch name.
5011
5012         • If the user selects an existing local branch, then that is
5013           checked out.
5014
5015         • If the user selects a remote branch, then it creates and
5016           checks out a new local branch with the same name, and
5017           configures the selected remote branch as the push target.
5018
5019         • If the user enters a new branch name, then it creates and
5020           checks that out, after also reading the starting-point from
5021           the user.
5022
5023      In the latter two cases the upstream is also set.  Whether it is
5024      set to the chosen starting point or something else depends on the
5025      value of ‘magit-branch-adjust-remote-upstream-alist’.
5026
5027 ‘b s’     (‘magit-branch-spinoff’)
5028
5029      This command creates and checks out a new branch starting at and
5030      tracking the current branch.  That branch in turn is reset to the
5031      last commit it shares with its upstream.  If the current branch has
5032      no upstream or no unpushed commits, then the new branch is created
5033      anyway and the previously current branch is not touched.
5034
5035      This is useful to create a feature branch after work has already
5036      began on the old branch (likely but not necessarily "master").
5037
5038      If the current branch is a member of the value of option
5039      ‘magit-branch-prefer-remote-upstream’ (which see), then the current
5040      branch will be used as the starting point as usual, but the
5041      upstream of the starting-point may be used as the upstream of the
5042      new branch, instead of the starting-point itself.
5043
5044      If optional FROM is non-nil, then the source branch is reset to
5045      ‘FROM~’, instead of to the last commit it shares with its upstream.
5046      Interactively, FROM is only ever non-nil, if the region selects
5047      some commits, and among those commits, FROM is the commit that is
5048      the fewest commits ahead of the source branch.
5049
5050      The commit at the other end of the selection actually does not
5051      matter, all commits between FROM and ‘HEAD’ are moved to the new
5052      branch.  If FROM is not reachable from ‘HEAD’ or is reachable from
5053      the source branch’s upstream, then an error is raised.
5054
5055 ‘b Y’     (‘magit-branch-pull-request’)
5056
5057      This command creates and configures a new branch from a Github
5058      pull-request, creating and configuring a new remote if necessary.
5059
5060      The name of the local branch is the same as the name of the remote
5061      branch that you are being asked to merge, unless the contributor
5062      could not be bother to properly name the branch before opening the
5063      pull-request.  The most likely such case is when you are being
5064      asked to merge something like "fork/master" into "origin/master".
5065      In such cases the local branch will be named "pr-N", where ‘N’ is
5066      the pull-request number.
5067
5068      These variables are always set by this command:
5069
5070         • ‘branch.<name>.pullRequest’ is set to the pull-request number.
5071
5072         • ‘branch.<name>.pullRequestRemote’ is set to the remote on
5073           which the pull-request branch is located.
5074
5075         • ‘branch.<name>.pushRemote’ is set to the same remote as
5076           ‘branch.<name>.pullRequestRemote’ if that is possible,
5077           otherwise it is set to the upstream remote.
5078
5079         • ‘branch.<name>.description’ is set to the pull-request title.
5080
5081         • ‘branch.<name>.rebase’ is set to ‘true’ because there should
5082           be no merge commits among the commits in a pull-request.
5083
5084      This command also configures the upstream and the push-remote of
5085      the local branch that it creates.
5086
5087      The branch against which the pull-request was opened, is always
5088      used as the upstream.  This makes it easy to see what commits you
5089      are being asked to merge in the section titled something like
5090      "Unmerged into origin/master".
5091
5092      Like for other commands that create a branch it depends on the
5093      option ‘magit-branch-prefer-remote-upstream’ whether the remote
5094      branch itself or the respective local branch is used as the
5095      upstream, so this section may also be titled e.g.  "Unmerged into
5096      master".
5097
5098      When necessary and possible, then the remote pull-request branch is
5099      configured to be used as the push-target.  This makes it easy to
5100      see what further changes the contributor has made since you last
5101      reviewed their changes in the section titled something like
5102      "Unpulled from origin/new-feature" or "Unpulled from
5103      fork/new-feature".
5104
5105         • If the pull-request branch is located in the upstream
5106           repository, then you probably have set ‘remote.pushDefault’ to
5107           that repository.  However some users like to set that variable
5108           to their personal fork, even if they have push access to the
5109           upstream, so ‘branch.<name>.pushRemote’ is set anyway.
5110
5111         • If the pull-request branch is located inside a fork, then you
5112           are usually able to push to that branch, because Github by
5113           default allows the recipient of a pull-request to push to the
5114           remote pull-request branch even if it is located in a fork.
5115           The contributor has to explicitly disable this.
5116
5117              • If you are not allowed to push to the pull-request branch
5118                on the fork, then a branch by the same name located in
5119                the upstream repository is configured as the push-target.
5120
5121              • A — sadly rather common — special case is when the
5122                contributor didn’t bother to use a dedicated branch for
5123                the pull-request.
5124
5125                The most likely such case is when you are being asked to
5126                merge something like "fork/master" into "origin/master".
5127                The special push permission mentioned above is never
5128                granted for the branch that is the repository’s default
5129                branch, and that would almost certainly be the case in
5130                this scenario.
5131
5132                To enable you to easily push somewhere anyway, the local
5133                branch is named "pr-N" (where ‘N’ is the pull-request
5134                number) and the upstream repository is used as the
5135                push-remote.
5136
5137              • Finally, if you are allowed to push to the pull-request
5138                branch and the contributor had the foresight to use a
5139                dedicated branch, then the fork is configured as the
5140                push-remote.
5141
5142           The push-remote is configured using
5143           ‘branch.<name>.pushRemote’, even if the used value is
5144           identical to that of ‘remote.pushDefault’, just in case you
5145           change the value of the latter later on.  Additionally the
5146           variable ‘branch.<name>.pullRequestRemote’ is set to the
5147           remote on which the pull-request branch is located.
5148
5149      When you later delete the local pull-request branch, then you are
5150      offered to also delete the corresponding remote, provided it is not
5151      the upstream remote and that the tracking branch that corresponds
5152      to the deleted branch is the only remaining tracked branch.  If you
5153      don’t confirm, then only the tracking branch itself is deleted in
5154      addition to the local branch.
5155
5156      Do not delete the tracking branch instead of the local branch.  The
5157      cleanup mentioned in the previous paragraph is not performed if you
5158      do that.
5159
5160 ‘b y’     (‘magit-checkout-pull-request’)
5161
5162      This command creates and configures a new branch from a pull
5163      request, the same way ‘magit-branch-pull-request’ does.
5164      Additionally it checks out the new branch.
5165
5166 ‘b x’     (‘magit-branch-reset’)
5167
5168      This command resets a branch, defaulting to the branch at point, to
5169      the tip of another branch or any other commit.
5170
5171      When the branch being reset is the current branch, then a hard
5172      reset is performed.  If there are any uncommitted changes, then the
5173      user has to confirm the reset because those changes would be lost.
5174
5175      This is useful when you have started work on a feature branch but
5176      realize it’s all crap and want to start over.
5177
5178      When resetting to another branch and a prefix argument is used,
5179      then the target branch is set as the upstream of the branch that is
5180      being reset.
5181
5182 ‘b k’     (‘magit-branch-delete’)
5183
5184      Delete one or multiple branches.  If the region marks multiple
5185      branches, then offer to delete those.  Otherwise, prompt for a
5186      single branch to be deleted, defaulting to the branch at point.
5187
5188 ‘b r’     (‘magit-branch-rename’)
5189
5190      Rename a branch.  The branch and the new name are read in the
5191      minibuffer.  With prefix argument the branch is renamed even if
5192      that name conflicts with an existing branch.
5193
5194  -- User Option: magit-branch-read-upstream-first
5195
5196      When creating a branch, whether to read the upstream branch before
5197      the name of the branch that is to be created.  The default is
5198      ‘nil’, and I recommend you leave it at that.
5199
5200  -- User Option: magit-branch-prefer-remote-upstream
5201
5202      This option specifies whether remote upstreams are favored over
5203      local upstreams when creating new branches.
5204
5205      When a new branch is created, then the branch, commit, or stash at
5206      point is suggested as the starting point of the new branch, or if
5207      there is no such revision at point the current branch.  In either
5208      case the user may choose another starting point.
5209
5210      If the chosen starting point is a branch, then it may also be set
5211      as the upstream of the new branch, depending on the value of the
5212      Git variable ‘branch.autoSetupMerge’.  By default this is done for
5213      remote branches, but not for local branches.
5214
5215      You might prefer to always use some remote branch as upstream.  If
5216      the chosen starting point is (1) a local branch, (2) whose name
5217      matches a member of the value of this option, (3) the upstream of
5218      that local branch is a remote branch with the same name, and (4)
5219      that remote branch can be fast-forwarded to the local branch, then
5220      the chosen branch is used as starting point, but its own upstream
5221      is used as the upstream of the new branch.
5222
5223      Members of this option’s value are treated as branch names that
5224      have to match exactly unless they contain a character that makes
5225      them invalid as a branch name.  Recommended characters to use to
5226      trigger interpretation as a regexp are "*" and "^".  Some other
5227      characters which you might expect to be invalid, actually are not,
5228      e.g.  ".+$" are all perfectly valid.  More precisely, if ‘git
5229      check-ref-format –branch STRING’ exits with a non-zero status, then
5230      treat STRING as a regexp.
5231
5232      Assuming the chosen branch matches these conditions you would end
5233      up with with e.g.:
5234
5235           feature --upstream--> origin/master
5236
5237      instead of
5238
5239           feature --upstream--> master --upstream--> origin/master
5240
5241      Which you prefer is a matter of personal preference.  If you do
5242      prefer the former, then you should add branches such as ‘master’,
5243      ‘next’, and ‘maint’ to the value of this options.
5244
5245  -- User Option: magit-branch-adjust-remote-upstream-alist
5246
5247      The value of this option is an alist of branches to be used as the
5248      upstream when branching a remote branch.
5249
5250      When creating a local branch from an ephemeral branch located on a
5251      remote, e.g.  a feature or hotfix branch, then that remote branch
5252      should usually not be used as the upstream branch, since the
5253      push-remote already allows accessing it and having both the
5254      upstream and the push-remote reference the same related branch
5255      would be wasteful.  Instead a branch like "maint" or "master"
5256      should be used as the upstream.
5257
5258      This option allows specifying the branch that should be used as the
5259      upstream when branching certain remote branches.  The value is an
5260      alist of the form ‘((UPSTREAM . RULE)...)’.  The first matching
5261      element is used, the following elements are ignored.
5262
5263      UPSTREAM is the branch to be used as the upstream for branches
5264      specified by RULE.  It can be a local or a remote branch.
5265
5266      RULE can either be a regular expression, matching branches whose
5267      upstream should be the one specified by UPSTREAM.  Or it can be a
5268      list of the only branches that should *not* use UPSTREAM; all other
5269      branches will.  Matching is done after stripping the remote part of
5270      the name of the branch that is being branched from.
5271
5272      If you use a finite set of non-ephemeral branches across all your
5273      repositories, then you might use something like:
5274
5275           (("origin/master" "master" "next" "maint"))
5276
5277      Or if the names of all your ephemeral branches contain a slash, at
5278      least in some repositories, then a good value could be:
5279
5280           (("origin/master" . "/"))
5281
5282      Of course you can also fine-tune:
5283
5284           (("origin/maint" . "\\`hotfix/")
5285            ("origin/master" . "\\`feature/"))
5286
5287  -- Command: magit-branch-orphan
5288
5289      This command creates and checks out a new orphan branch with
5290      contents from a given revision.
5291
5292  -- Command: magit-branch-or-checkout
5293
5294      This command is a hybrid between ‘magit-checkout’ and
5295      ‘magit-branch-and-checkout’ and is intended as a replacement for
5296      the former in ‘magit-branch-popup’.
5297
5298      It first asks the user for an existing branch or revision.  If the
5299      user input actually can be resolved as a branch or revision, then
5300      it checks that out, just like ‘magit-checkout’ would.
5301
5302      Otherwise it creates and checks out a new branch using the input as
5303      its name.  Before doing so it reads the starting-point for the new
5304      branch.  This is similar to what ‘magit-branch-and-checkout’ does.
5305
5306      To use this command instead of ‘magit-checkout’ add this to your
5307      init file:
5308
5309           (magit-remove-popup-key 'magit-branch-popup :action ?b)
5310           (magit-define-popup-action 'magit-branch-popup
5311             ?b "Checkout" 'magit-branch-or-checkout
5312             'magit-branch t)
5313
5314 
5315 File: magit.info,  Node: The Branch Config Popup,  Next: Auxiliary Branch Commands,  Prev: The Branch Popup,  Up: Branching
5316
5317 6.5.3 The Branch Config Popup
5318 -----------------------------
5319
5320  -- Command: magit-branch-config-popup
5321
5322      This prefix command shows the following branch-related Git
5323      variables in a popup buffer.  The values can be changed from that
5324      buffer.
5325
5326      This popup is a sub-popup of several popups that deal with
5327      branches, including ‘magit-branch-popup’, ‘magit-pull-popup’,
5328      ‘magit-fetch-popup’, ‘magit-pull-and-fetch-popup’, and
5329      ‘magit-push-popup’.  In all of these popups "C" is bound to this
5330      popup.
5331
5332    The following variables are used to configure a specific branch.  The
5333 values are being displayed for the current branch (if any).  To change
5334 the value for another branch invoke ‘magit-branch-config-popup’ with a
5335 prefix argument.
5336
5337  -- Variable: branch.NAME.merge
5338
5339      Together with ‘branch.NAME.remote’ this variable defines the
5340      upstream branch of the local branch named NAME.  The value of this
5341      variable is the full reference of the upstream _branch_.
5342
5343  -- Variable: branch.NAME.remote
5344
5345      Together with ‘branch.NAME.merge’ this variable defines the
5346      upstream branch of the local branch named NAME.  The value of this
5347      variable is the name of the upstream _remote_.
5348
5349  -- Variable: branch.NAME.rebase
5350
5351      This variable controls whether pulling into the branch named NAME
5352      is done by rebasing or by merging the fetched branch.
5353
5354         • When ‘true’ then pulling is done by rebasing.
5355
5356         • When ‘false’ then pulling is done by merging.
5357
5358         • When undefined then the value of ‘pull.rebase’ is used.  The
5359           default of that variable is ‘false’.
5360
5361  -- Variable: branch.NAME.pushRemote
5362
5363      This variable specifies the remote that the branch named NAME is
5364      usually pushed to.  The value has to be the name of an existing
5365      remote.
5366
5367      It is not possible to specify the name of _branch_ to push the
5368      local branch to.  The name of the remote branch is always the same
5369      as the name of the local branch.
5370
5371      If this variable is undefined but ‘remote.pushDefault’ is defined,
5372      then the value of the latter is used.  By default
5373      ‘remote.pushDefault’ is undefined.
5374
5375  -- Variable: branch.NAME.description
5376
5377      This variable can be used to describe the branch named NAME.  That
5378      description is used e.g.  when turning the branch into a series of
5379      patches.
5380
5381    The following variables specify defaults which are used if the above
5382 branch-specific variables are not set.
5383
5384  -- Variable: pull.rebase
5385
5386      This variable specifies whether pulling is done by rebasing or by
5387      merging.  It can be overwritten using ‘branch.NAME.rebase’.
5388
5389         • When ‘true’ then pulling is done by rebasing.
5390
5391         • When ‘false’ (the default) then pulling is done by merging.
5392
5393      Since it is never a good idea to merge the upstream branch into a
5394      feature or hotfix branch and most branches are such branches, you
5395      should consider setting this to ‘true’, and ‘branch.master.rebase’
5396      to ‘false’.
5397
5398  -- Variable: remote.pushDefault
5399
5400      This variable specifies what remote the local branches are usually
5401      pushed to.  This can be overwritten per branch using
5402      ‘branch.NAME.pushRemote’.
5403
5404    The following variables are used during the creation of a branch and
5405 control whether the various branch-specific variables are automatically
5406 set at this time.
5407
5408  -- Variable: branch.autoSetupMerge
5409
5410      This variable specifies under what circumstances creating a branch
5411      NAME should result in the variables ‘branch.NAME.merge’ and
5412      ‘branch.NAME.remote’ being set according to the starting point used
5413      to create the branch.  If the starting point isn’t a branch, then
5414      these variables are never set.
5415
5416         • When ‘always’ then the variables are set regardless of whether
5417           the starting point is a local or a remote branch.
5418
5419         • When ‘true’ (the default) then the variables are set when the
5420           starting point is a remote branch, but not when it is a local
5421           branch.
5422
5423         • When ‘false’ then the variables are never set.
5424
5425  -- Variable: branch.autoSetupRebase
5426
5427      This variable specifies whether creating a branch NAME should
5428      result in the variable ‘branch.NAME.rebase’ being set to ‘true’.
5429
5430         • When ‘always’ then the variable is set regardless of whether
5431           the starting point is a local or a remote branch.
5432
5433         • When ‘local’ then the variable are set when the starting point
5434           is a local branch, but not when it is a remote branch.
5435
5436         • When ‘remote’ then the variable are set when the starting
5437           point is a remote branch, but not when it is a local branch.
5438
5439         • When ‘never’ (the default) then the variable is never set.
5440
5441    Note that the respective commands always change the repository-local
5442 values.  If you want to change the global value, which is used when the
5443 local value is undefined, then you have to do so on the command line,
5444 e.g.:
5445
5446      git config --global remote.autoSetupMerge always
5447
5448    For more information about these variables you should also see
5449
5450    *note (gitman)git-config::.  Also see *note (gitman)git-branch::.  ,
5451 *note (gitman)git-checkout::.  and *note Pushing::.
5452
5453  -- User Option: magit-prefer-remote-upstream
5454
5455      This option controls whether commands that read a branch from the
5456      user and then set it as the upstream branch, offer a local or a
5457      remote branch as default completion candidate, when they have the
5458      choice.
5459
5460      This affects all commands that use ‘magit-read-upstream-branch’ or
5461      ‘magit-read-starting-point’, which includes all commands that
5462      change the upstream and many which create new branches.
5463
5464 
5465 File: magit.info,  Node: Auxiliary Branch Commands,  Prev: The Branch Config Popup,  Up: Branching
5466
5467 6.5.4 Auxiliary Branch Commands
5468 -------------------------------
5469
5470 These commands are not available from the branch popup by default.
5471
5472  -- Command: magit-branch-shelve
5473
5474      This command shelves a branch.  This is done by deleting the
5475      branch, and creating a new reference "refs/shelved/BRANCH-NAME"
5476      pointing at the same commit as the branch pointed at.  If the
5477      deleted branch had a reflog, then that is preserved as the reflog
5478      of the new reference.
5479
5480      This is useful if you want to move a branch out of sight, but are
5481      not ready to completely discard it yet.
5482
5483  -- Command: magit-branch-unshelve
5484
5485      This command unshelves a branch that was previously shelved using
5486      ‘magit-branch-shelve’.  This is done by deleting the reference
5487      "refs/shelved/BRANCH-NAME" and creating a branch "BRANCH-NAME"
5488      pointing at the same commit as the deleted reference pointed at.
5489      If the deleted reference had a reflog, then that is restored as the
5490      reflog of the branch.
5491
5492 
5493 File: magit.info,  Node: Merging,  Next: Resolving Conflicts,  Prev: Branching,  Up: Manipulating
5494
5495 6.6 Merging
5496 ===========
5497
5498 Also see *note (gitman)git-merge::.  For information on how to resolve
5499 merge conflicts see the next section.
5500
5501 ‘m’     (‘magit-merge-popup’)
5502
5503      This prefix command shows the following suffix commands along with
5504      the appropriate infix arguments in a popup buffer.
5505
5506    When no merge is in progress, then the popup buffer features the
5507 following commands.
5508
5509 ‘m m’     (‘magit-merge-plain’)
5510
5511      This command merges another branch or an arbitrary revision into
5512      the current branch.  The branch or revision to be merged is read in
5513      the minibuffer and defaults to the branch at point.
5514
5515      Unless there are conflicts or a prefix argument is used, then the
5516      resulting merge commit uses a generic commit message, and the user
5517      does not get a chance to inspect or change it before the commit is
5518      created.  With a prefix argument this does not actually create the
5519      merge commit, which makes it possible to inspect how conflicts were
5520      resolved and to adjust the commit message.
5521
5522 ‘m e’     (‘magit-merge-editmsg’)
5523
5524      This command merges another branch or an arbitrary revision into
5525      the current branch and opens a commit message buffer, so that the
5526      user can make adjustments.  The commit is not actually created
5527      until the user finishes with ‘C-c C-c’.
5528
5529 ‘m n’     (‘magit-merge-nocommit’)
5530
5531      This command merges another branch or an arbitrary revision into
5532      the current branch, but does not actually create the merge commit.
5533      The user can then further adjust the merge, even when automatic
5534      conflict resolution succeeded and/or adjust the commit message.
5535
5536 ‘m a’     (‘magit-merge-absorb’)
5537
5538      This command merges another local branch into the current branch
5539      and then removes the former.
5540
5541      Before the source branch is merged, it is first force pushed to its
5542      push-remote, provided the respective remote branch already exists.
5543      This ensures that the respective pull-request (if any) won’t get
5544      stuck on some obsolete version of the commits that are being
5545      merged.  Finally, if ‘magit-branch-pull-request’ was used to create
5546      the merged branch, then the respective remote branch is also
5547      removed.
5548
5549 ‘m i’     (‘magit-merge-into’)
5550
5551      This command merges the current branch into another local branch
5552      and then removes the former.  The latter becomes the new current
5553      branch.
5554
5555      Before the source branch is merged, it is first force pushed to its
5556      push-remote, provided the respective remote branch already exists.
5557      This ensures that the respective pull-request (if any) won’t get
5558      stuck on some obsolete version of the commits that are being
5559      merged.  Finally, if ‘magit-branch-pull-request’ was used to create
5560      the merged branch, then the respective remote branch is also
5561      removed.
5562
5563 ‘m s’     (‘magit-merge-squash’)
5564
5565      This command squashes the changes introduced by another branch or
5566      an arbitrary revision into the current branch.  This only applies
5567      the changes made by the squashed commits.  No information is
5568      preserved that would allow creating an actual merge commit.
5569      Instead of this command you should probably use a command from the
5570      apply popup.
5571
5572 ‘m p’     (‘magit-merge-preview’)
5573
5574      This command shows a preview of merging another branch or an
5575      arbitrary revision into the current branch.
5576
5577    When a merge is in progress, then the popup buffer features these
5578 commands instead.
5579
5580 ‘m m’     (‘magit-merge’)
5581
5582      After the user resolved conflicts, this command proceeds with the
5583      merge.  If some conflicts weren’t resolved, then this command
5584      fails.
5585
5586 ‘m a’     (‘magit-merge-abort’)
5587
5588      This command aborts the current merge operation.
5589
5590 
5591 File: magit.info,  Node: Resolving Conflicts,  Next: Rebasing,  Prev: Merging,  Up: Manipulating
5592
5593 6.7 Resolving Conflicts
5594 =======================
5595
5596 When merging branches (or otherwise combining or changing history)
5597 conflicts can occur.  If you edited two completely different parts of
5598 the same file in two branches and then merge one of these branches into
5599 the other, then Git can resolve that on its own, but if you edit the
5600 same area of a file, then a human is required to decide how the two
5601 versions, or "sides of the conflict", are to be combined into one.
5602
5603    Here we can only provide a brief introduction to the subject and
5604 point you toward some tools that can help.  If you are new to this, then
5605 please also consult Git’s own documentation as well as other resources.
5606
5607    If a file has conflicts and Git cannot resolve them by itself, then
5608 it puts both versions into the affected file along with special markers
5609 whose purpose is to denote the boundaries of the unresolved part of the
5610 file and between the different versions.  These boundary lines begin
5611 with the strings consisting of six times the same character, one of ‘<’,
5612 ‘|’, ‘=’ and ‘>’ and are followed by information about the source of the
5613 respective versions, e.g.:
5614
5615      <<<<<<< HEAD
5616      Take the blue pill.
5617      =======
5618      Take the red pill.
5619      >>>>>>> feature
5620
5621    In this case you have chosen to take the red pill on one branch and
5622 on another you picked the blue pill.  Now that you are merging these two
5623 diverging branches, Git cannot possibly know which pill you want to
5624 take.
5625
5626    To resolve that conflict you have to create a version of the affected
5627 area of the file by keeping only one of the sides, possibly by editing
5628 it in order to bring in the changes from the other side, remove the
5629 other versions as well as the markers, and then stage the result.  A
5630 possible resolution might be:
5631
5632      Take both pills.
5633
5634    Often it is useful to see not only the two sides of the conflict but
5635 also the "original" version from before the same area of the file was
5636 modified twice on different branches.  Instruct Git to insert that
5637 version as well by running this command once:
5638
5639      git config --global merge.conflictStyle diff3
5640
5641    The above conflict might then have looked like this:
5642
5643      <<<<<<< HEAD
5644      Take the blue pill.
5645      ||||||| merged common ancestors
5646      Take either the blue or the red pill, but not both.
5647      =======
5648      Take the red pill.
5649      >>>>>>> feature
5650
5651    If that were the case, then the above conflict resolution would not
5652 have been correct, which demonstrates why seeing the original version
5653 alongside the conflicting versions can be useful.
5654
5655    You can perform the conflict resolution completely by hand, but Emacs
5656 also provides some packages that help in the process: Smerge, Ediff
5657 (*note (ediff)Top::), and Emerge (*note (emacs)Emerge::).  Magit does
5658 not provide its own tools for conflict resolution, but it does make
5659 using Smerge and Ediff more convenient.  (Ediff supersedes Emerge, so
5660 you probably don’t want to use the latter anyway.)
5661
5662    In the Magit status buffer, files with unresolved conflicts are
5663 listed in the "Unstaged changes" and/or "Staged changes" sections.  They
5664 are prefixed with the word "unmerged", which in this context essentially
5665 is a synonym for "unresolved".
5666
5667    Pressing ‘RET’ while point is on such a file section shows a buffer
5668 visiting that file, turns on ‘smerge-mode’ in that buffer, and places
5669 point inside the first area with conflicts.  You should then resolve
5670 that conflict using regular edit commands and/or Smerge commands.
5671
5672    Unfortunately Smerge does not have a manual, but you can get a list
5673 of commands and binding ‘C-c ^ C-h’ and press ‘RET’ while point is on a
5674 command name to read its documentation.
5675
5676    Normally you would edit one version and then tell Smerge to keep only
5677 that version.  Use ‘C-c ^ m’ (‘smerge-keep-mine’) to keep the ‘HEAD’
5678 version or ‘C-c ^ o’ (‘smerge-keep-other’) to keep the version that
5679 follows "|||||||".  Then use ‘C-c ^ n’ to move to the next conflicting
5680 area in the same file.  Once you are done resolving conflicts, return to
5681 the Magit status buffer.  The file should now be shown as "modified", no
5682 longer as "unmerged", because Smerge automatically stages the file when
5683 you save the buffer after resolving the last conflict.
5684
5685    Alternatively you could use Ediff, which uses separate buffers for
5686 the different versions of the file.  To resolve conflicts in a file
5687 using Ediff press ‘e’ while point is on such a file in the status
5688 buffer.
5689
5690    Ediff can be used for other purposes as well.  For more information
5691 on how to enter Ediff from Magit, see *note Ediffing::.  Explaining how
5692 to use Ediff is beyond the scope of this manual, instead see *note
5693 (ediff)Top::.
5694
5695    If you are unsure whether you should Smerge or Ediff, then use the
5696 former.  It is much easier to understand and use, and except for truly
5697 complex conflicts, the latter is usually overkill.
5698
5699 
5700 File: magit.info,  Node: Rebasing,  Next: Cherry Picking,  Prev: Resolving Conflicts,  Up: Manipulating
5701
5702 6.8 Rebasing
5703 ============
5704
5705 Also see *note (gitman)git-rebase::.  For information on how to resolve
5706 conflicts that occur during rebases see the preceding section.
5707
5708 ‘r’     (‘magit-rebase-popup’)
5709
5710      This prefix command shows the following suffix commands along with
5711      the appropriate infix arguments in a popup buffer.
5712
5713    When no rebase is in progress, then the popup buffer features the
5714 following commands.
5715
5716    Using one of these commands _starts_ a rebase sequence.  Git might
5717 then stop somewhere along the way, either because you told it to do so,
5718 or because applying a commit failed due to a conflict.  When that
5719 happens, then the status buffer shows information about the rebase
5720 sequence which is in progress in a section similar to a log section.
5721 See *note Information About In-Progress Rebase::.
5722
5723 ‘r p’     (‘magit-rebase-onto-pushremote’)
5724
5725      Rebase the current branch onto ‘branch.<name>.pushRemote’.  If that
5726      variable is unset, then rebase onto ‘remote.pushDefault’.
5727
5728 ‘r u’     (‘magit-rebase-onto-upstream’)
5729
5730      Rebase the current branch onto its upstream branch.
5731
5732 ‘r e’     (‘magit-rebase-branch’)
5733
5734      Rebase the current branch onto a branch read in the minibuffer.
5735      All commits that are reachable from head but not from the selected
5736      branch TARGET are being rebased."
5737
5738 ‘r s’     (‘magit-rebase-subset’)
5739
5740      Start a non-interactive rebase sequence with commits from START to
5741      ‘HEAD’ onto NEWBASE.  START has to be selected from a list of
5742      recent commits.
5743
5744    By default Magit uses the ‘--autostash’ argument, which causes
5745 uncommitted changes to be stored in a stash before the rebase begins.
5746 These changes are restored after the rebase completes and if possible
5747 the stash is removed.  If the stash does not apply cleanly, then the
5748 stash is not removed.  In case something goes wrong when resolving the
5749 conflicts, this allows you to start over.
5750
5751    Even though one of the actions is dedicated to interactive rebases,
5752 the popup also features the infix argument ‘--interactive’.  This can be
5753 used to turn one of the other, non-interactive rebase variants into an
5754 interactive rebase.
5755
5756    For example if you want to clean up a feature branch and at the same
5757 time rebase it onto ‘master’, then you could use ‘r-iu’.  But we
5758 recommend that you instead do that in two steps.  First use ‘ri’ to
5759 cleanup the feature branch, and then in a second step ‘ru’ to rebase it
5760 onto ‘master’.  That way if things turn out to be more complicated than
5761 you thought and/or you make a mistake and have to start over, then you
5762 only have to redo half the work.
5763
5764    Explicitly enabling ‘--interactive’ won’t have an effect on the
5765 following commands as they always use that argument anyway, even if it
5766 is not enabled in the popup.
5767
5768 ‘r i’     (‘magit-rebase-interactive’)
5769
5770      Start an interactive rebase sequence.
5771
5772 ‘r f’     (‘magit-rebase-autosquash’)
5773
5774      Combine squash and fixup commits with their intended targets.
5775
5776 ‘r m’     (‘magit-rebase-edit-commit’)
5777
5778      Edit a single older commit using rebase.
5779
5780 ‘r w’     (‘magit-rebase-reword-commit’)
5781
5782      Reword a single older commit using rebase.
5783
5784 ‘r k’     (‘magit-rebase-remove-commit’)
5785
5786      Remove a single older commit using rebase.
5787
5788    When a rebase is in progress, then the popup buffer features these
5789 commands instead.
5790
5791 ‘r r’     (‘magit-rebase-continue’)
5792
5793      Restart the current rebasing operation.
5794
5795      In some cases this pops up a commit message buffer for you do edit.
5796      With a prefix argument the old message is reused as-is.
5797
5798 ‘r s’     (‘magit-rebase-skip’)
5799
5800      Skip the current commit and restart the current rebase operation.
5801
5802 ‘r e’     (‘magit-rebase-edit’)
5803
5804      Edit the todo list of the current rebase operation.
5805
5806 ‘r a’     (‘magit-rebase-abort’)
5807
5808      Abort the current rebase operation, restoring the original branch.
5809
5810 * Menu:
5811
5812 * Editing Rebase Sequences::
5813 * Information About In-Progress Rebase::
5814
5815 
5816 File: magit.info,  Node: Editing Rebase Sequences,  Next: Information About In-Progress Rebase,  Up: Rebasing
5817
5818 6.8.1 Editing Rebase Sequences
5819 ------------------------------
5820
5821 ‘C-c C-c’     (‘with-editor-finish’)
5822
5823      Finish the current editing session by returning with exit code 0.
5824      Git then uses the rebase instructions it finds in the file.
5825
5826 ‘C-c C-k’     (‘with-editor-cancel’)
5827
5828      Cancel the current editing session by returning with exit code 1.
5829      Git then forgoes starting the rebase sequence.
5830
5831 ‘RET’     (‘git-rebase-show-commit’)
5832
5833      Show the commit on the current line in another buffer and select
5834      that buffer.
5835
5836 ‘SPC’     (‘git-rebase-show-or-scroll-up’)
5837
5838      Show the commit on the current line in another buffer without
5839      selecting that buffer.  If the revision buffer is already visible
5840      in another window of the current frame, then instead scroll that
5841      window up.
5842
5843 ‘DEL’     (‘git-rebase-show-or-scroll-down’)
5844
5845      Show the commit on the current line in another buffer without
5846      selecting that buffer.  If the revision buffer is already visible
5847      in another window of the current frame, then instead scroll that
5848      window down.
5849
5850 ‘p’     (‘git-rebase-backward-line’)
5851
5852      Move to previous line.
5853
5854 ‘n’     (‘forward-line’)
5855
5856      Move to next line.
5857
5858 ‘M-p’     (‘git-rebase-move-line-up’)
5859
5860      Move the current commit (or command) up.
5861
5862 ‘M-n’     (‘git-rebase-move-line-down’)
5863
5864      Move the current commit (or command) down.
5865
5866 ‘r’     (‘git-rebase-reword’)
5867
5868      Edit message of commit on current line.
5869
5870 ‘e’     (‘git-rebase-edit’)
5871
5872      Stop at the commit on the current line.
5873
5874 ‘s’     (‘git-rebase-squash’)
5875
5876      Meld commit on current line into previous commit, and edit message.
5877
5878 ‘f’     (‘git-rebase-fixup’)
5879
5880      Meld commit on current line into previous commit, discarding the
5881      current commit’s message.
5882
5883 ‘k’     (‘git-rebase-kill-line’)
5884
5885      Kill the current action line.
5886
5887 ‘c’     (‘git-rebase-pick’)
5888
5889      Use commit on current line.
5890
5891 ‘x’     (‘git-rebase-exec’)
5892
5893      Insert a shell command to be run after the proceeding commit.
5894
5895      If there already is such a command on the current line, then edit
5896      that instead.  With a prefix argument insert a new command even
5897      when there already is one on the current line.  With empty input
5898      remove the command on the current line, if any.
5899
5900 ‘y’     (‘git-rebase-insert’)
5901
5902      Read an arbitrary commit and insert it below current line.
5903
5904 ‘C-x u’     (‘git-rebase-undo’)
5905
5906      Undo some previous changes.  Like ‘undo’ but works in read-only
5907      buffers.
5908
5909  -- User Option: git-rebase-auto-advance
5910
5911      Whether to move to next line after changing a line.
5912
5913  -- User Option: git-rebase-show-instructions
5914
5915      Whether to show usage instructions inside the rebase buffer.
5916
5917  -- User Option: git-rebase-confirm-cancel
5918
5919      Whether confirmation is required to cancel.
5920
5921 
5922 File: magit.info,  Node: Information About In-Progress Rebase,  Prev: Editing Rebase Sequences,  Up: Rebasing
5923
5924 6.8.2 Information About In-Progress Rebase
5925 ------------------------------------------
5926
5927 While a rebase sequence is in progress, the status buffer features a
5928 section that lists the commits that have already been applied as well as
5929 the commits that still have to be applied.
5930
5931    The commits are split in two halves.  When rebase stops at a commit,
5932 either because the user has to deal with a conflict or because s/he
5933 explicitly requested that rebase stops at that commit, then point is
5934 placed on the commit that separates the two groups, i.e.  on ‘HEAD’.
5935 The commits above it have not been applied yet, while the ‘HEAD’ and the
5936 commits below it have already been applied.  In between these two groups
5937 of applied and yet-to-be applied commits, there sometimes is a commit
5938 which has been dropped.
5939
5940    Each commit is prefixed with a word and these words are additionally
5941 shown in different colors to indicate the status of the commits.
5942
5943    The following colors are used:
5944
5945    • Yellow commits have not been applied yet.
5946
5947    • Gray commits have already been applied.
5948
5949    • The blue commit is the ‘HEAD’ commit.
5950
5951    • The green commit is the commit the rebase sequence stopped at.  If
5952      this is the same commit as ‘HEAD’ (e.g.  because you haven’t done
5953      anything yet after rebase stopped at the commit, then this commit
5954      is shown in blue, not green).  There can only be a green *and* a
5955      blue commit at the same time, if you create one or more new commits
5956      after rebase stops at a commit.
5957
5958    • Red commits have been dropped.  They are shown for reference only,
5959      e.g.  to make it easier to diff.
5960
5961    Of course these colors are subject to the color-theme in use.
5962
5963    The following words are used:
5964
5965    • Commits prefixed with ‘pick’, ‘reword’, ‘edit’, ‘squash’, and
5966      ‘fixup’ have not been applied yet.  These words have the same
5967      meaning here as they do in the buffer used to edit the rebase
5968      sequence.  See *note Editing Rebase Sequences::.
5969
5970    • Commits prefixed with ‘done’ and ‘onto’ have already been applied.
5971      It is possible for such a commit to be the ‘HEAD’, in which case it
5972      is blue.  Otherwise it is grey.
5973
5974         • The commit prefixed with ‘onto’ is the commit on top of which
5975           all the other commits are being re-applied.  This commit
5976           itself did not have to be re-applied, it is the commit rebase
5977           did rewind to before starting to re-apply other commits.
5978
5979         • Commits prefixed with ‘done’ have already been re-applied.
5980           This includes commits that have been re-applied but also new
5981           commits that you have created during the rebase.
5982
5983    • All other commits, those not prefixed with any of the above words,
5984      are in some way related to the commit at which rebase stopped.
5985
5986      To determine whether a commit is related to the stopped-at commit
5987      their hashes, trees and patch-ids (1) are being compared.  The
5988      commit message is not used for this purpose.
5989
5990      Generally speaking commits that are related to the stopped-at
5991      commit can have any of the used colors, though not all color/word
5992      combinations are possible.
5993
5994      Words used for stopped-at commits are:
5995
5996         • When a commit is prefixed with ‘void’, then that indicates
5997           that Magit knows for sure that all the changes in that commit
5998           have been applied using several new commits.  This commit is
5999           no longer reachable from ‘HEAD’, and it also isn’t one of the
6000           commits that will be applied when resuming the session.
6001
6002         • When a commit is prefixed with ‘join’, then that indicates
6003           that the rebase sequence stopped at that commit due to a
6004           conflict - you now have to join (merge) the changes with what
6005           has already been applied.  In a sense this is the commit
6006           rebase stopped at, but while its effect is already in the
6007           index and in the worktree (with conflict markers), the commit
6008           itself has not actually been applied yet (it isn’t the
6009           ‘HEAD’).  So it is shown in yellow, like the other commits
6010           that still have to be applied.
6011
6012         • When a commit is prefixed with ‘stop’ or a _blue_ or _green_
6013           ‘same’, then that indicates that rebase stopped at this
6014           commit, that it is still applied or has been applied again,
6015           and that at least its patch-id is unchanged.
6016
6017              • When a commit is prefixed with ‘stop’, then that
6018                indicates that rebase stopped at that commit because you
6019                requested that earlier, and its patch-id is unchanged.
6020                It might even still be the exact same commit.
6021
6022              • When a commit is prefixed with a _blue_ or _green_
6023                ‘same’, then that indicates that while its tree or hash
6024                changed, its patch-id did not.  If it is blue, then it is
6025                the ‘HEAD’ commit (as always for blue).  When it is
6026                green, then it no longer is ‘HEAD’ because other commit
6027                have been created since (but before continuing the
6028                rebase).
6029
6030         • When a commit is prefixed with ‘goal’, a _yellow_ ‘same,’ or
6031           ‘work’, then that indicates that rebase applied that commit
6032           but that you then reset ‘HEAD’ to an earlier commit (likely to
6033           split it up into multiple commits), and that there are some
6034           uncommitted changes remaining which likely (but not
6035           necessarily) originate from that commit.
6036
6037              • When a commit is prefixed with ‘goal’, then that
6038                indicates that it is still possible to create a new
6039                commit with the exact same tree (the "goal") without
6040                manually editing any files, by committing the index, or
6041                by staging all changes and then committing that.  This is
6042                the case when the original tree still exists in the index
6043                or worktree in untainted form.
6044
6045              • When a commit is prefixed with a yellow ‘same’, then that
6046                indicates that it is no longer possible to create a
6047                commit with the exact same tree, but that it is still
6048                possible to create a commit with the same patch-id.  This
6049                would be the case if you created a new commit with other
6050                changes, but the changes from the original commit still
6051                exist in the index or working tree in untainted form.
6052
6053              • When a commit is prefixed with ‘work’, then that
6054                indicates that you reset ‘HEAD’ to an earlier commit, and
6055                that there are some staged and/or unstaged changes
6056                (likely, but not necessarily) originating from that
6057                commit.  However it is no longer possible to create a new
6058                commit with the same tree or at least the same patch-id
6059                because you have already made other changes.
6060
6061         • When a commit is prefixed with ‘poof’ or ‘gone’, then that
6062           indicates that rebase applied that commit but that you then
6063           reset ‘HEAD’ to an earlier commit (likely to split it up into
6064           multiple commits), and that there are no uncommitted changes.
6065
6066              • When a commit is prefixed with ‘poof’, then that
6067                indicates that it is no longer reachable from ‘HEAD’, but
6068                that it has been replaced with one or more commits, which
6069                together have the exact same effect.
6070
6071              • When a commit is prefixed with ‘gone’, then that
6072                indicates that it is no longer reachable from ‘HEAD’ and
6073                that we also cannot determine whether its changes are
6074                still in effect in one or more new commits.  They might
6075                be, but if so, then there must also be other changes
6076                which makes it impossible to know for sure.
6077
6078    Do not worry if you do not fully understand the above.  That’s okay,
6079 you will acquire a good enough understanding through practice.
6080
6081    For other sequence operations such as cherry-picking, a similar
6082 section is displayed, but they lack some of the features described
6083 above, due to limitations in the git commands used to implement them.
6084 Most importantly these sequences only support "picking" a commit but not
6085 other actions such as "rewording", and they do not keep track of the
6086 commits which have already been applied.
6087
6088    ---------- Footnotes ----------
6089
6090    (1) The patch-id is a hash of the _changes_ introduced by a commit.
6091 It differs from the hash of the commit itself, which is a hash of the
6092 result of applying that change (i.e.  the resulting trees and blobs) as
6093 well as author and committer information, the commit message, and the
6094 hashes of the parents of the commit.  The patch-id hash on the other
6095 hand is created only from the added and removed lines, even line numbers
6096 and whitespace changes are ignored when calculating this hash.  The
6097 patch-ids of two commits can be used to answer the question "Do these
6098 commits make the same change?".
6099
6100 
6101 File: magit.info,  Node: Cherry Picking,  Next: Resetting,  Prev: Rebasing,  Up: Manipulating
6102
6103 6.9 Cherry Picking
6104 ==================
6105
6106 Also see *note (gitman)git-cherry-pick::.
6107
6108 ‘A’     (‘magit-cherry-pick-popup’)
6109
6110      This prefix command shows the following suffix commands along with
6111      the appropriate infix arguments in a popup buffer.
6112
6113    When no cherry-pick or revert is in progress, then the popup buffer
6114 features the following commands.
6115
6116 ‘A A’     (‘magit-cherry-copy’)
6117
6118      This command copies COMMITS from another branch onto the current
6119      branch.  If the region selects multiple commits, then those are
6120      copied, without prompting.  Otherwise the user is prompted for a
6121      commit or range, defaulting to the commit at point.
6122
6123 ‘A a’     (‘magit-cherry-apply’)
6124
6125      This command applies the changes in COMMITS from another branch
6126      onto the current branch.  If the region selects multiple commits,
6127      then those are used, without prompting.  Otherwise the user is
6128      prompted for a commit or range, defaulting to the commit at point.
6129
6130      This command also has a top-level binding, which can be invoked
6131      without using the popup by typing ‘a’ at the top-level.
6132
6133    The following commands not only apply some commits to some branch,
6134 but also remove them from some other branch.  The removal is performed
6135 using either ‘git-update-ref’ or if necessary ‘git-rebase’.  Both
6136 applying commits as well as removing them using ‘git-rebase’ can lead to
6137 conflicts.  If that happens, then these commands abort and you not only
6138 have to resolve the conflicts but also finish the process the same way
6139 you would have to if these commands didn’t exist at all.
6140
6141 ‘A h’     (‘magit-cherry-harvest’)
6142
6143      This command moves the selected COMMITS that must be located on
6144      another BRANCH onto the current branch instead, removing them from
6145      the former.  When this command succeeds, then the same branch is
6146      current as before.
6147
6148      Applying the commits on the current branch or removing them from
6149      the other branch can lead to conflicts.  When that happens, then
6150      this command stops and you have to resolve the conflicts and then
6151      finish the process manually.
6152
6153 ‘A d’     (‘magit-cherry-donate’)
6154
6155      This command moves the selected COMMITS from the current branch
6156      onto another existing BRANCH, removing them from the former.  When
6157      this command succeeds, then the same branch is current as before.
6158
6159      Applying the commits on the other branch or removing them from the
6160      current branch can lead to conflicts.  When that happens, then this
6161      command stops and you have to resolve the conflicts and then finish
6162      the process manually.
6163
6164 ‘A n’     (‘magit-cherry-spinout’)
6165
6166      This command moves the selected COMMITS from the current branch
6167      onto a new branch BRANCH, removing them from the former.  When this
6168      command succeeds, then the same branch is current as before.
6169
6170      Applying the commits on the other branch or removing them from the
6171      current branch can lead to conflicts.  When that happens, then this
6172      command stops and you have to resolve the conflicts and then finish
6173      the process manually.
6174
6175 ‘A s’     (‘magit-cherry-spinoff’)
6176
6177      This command moves the selected COMMITS from the current branch
6178      onto a new branch BRANCH, removing them from the former.  When this
6179      command succeeds, then the new branch is checked out.
6180
6181      Applying the commits on the other branch or removing them from the
6182      current branch can lead to conflicts.  When that happens, then this
6183      command stops and you have to resolve the conflicts and then finish
6184      the process manually.
6185
6186    When a cherry-pick or revert is in progress, then the popup buffer
6187 features these commands instead.
6188
6189 ‘A A’     (‘magit-sequence-continue’)
6190
6191      Resume the current cherry-pick or revert sequence.
6192
6193 ‘A s’     (‘magit-sequence-skip’)
6194
6195      Skip the stopped at commit during a cherry-pick or revert sequence.
6196
6197 ‘A a’     (‘magit-sequence-abort’)
6198
6199      Abort the current cherry-pick or revert sequence.  This discards
6200      all changes made since the sequence started.
6201
6202 * Menu:
6203
6204 * Reverting::
6205
6206 
6207 File: magit.info,  Node: Reverting,  Up: Cherry Picking
6208
6209 6.9.1 Reverting
6210 ---------------
6211
6212 ‘V’     (‘magit-revert-popup’)
6213
6214      This prefix command shows the following suffix commands along with
6215      the appropriate infix arguments in a popup buffer.
6216
6217    When no cherry-pick or revert is in progress, then the popup buffer
6218 features the following commands.
6219
6220 ‘V V’     (‘magit-revert-and-commit’)
6221
6222      Revert a commit by creating a new commit.  Prompt for a commit,
6223      defaulting to the commit at point.  If the region selects multiple
6224      commits, then revert all of them, without prompting.
6225
6226 ‘V v’     (‘magit-revert-no-commit’)
6227
6228      Revert a commit by applying it in reverse to the working tree.
6229      Prompt for a commit, defaulting to the commit at point.  If the
6230      region selects multiple commits, then revert all of them, without
6231      prompting.
6232
6233    When a cherry-pick or revert is in progress, then the popup buffer
6234 features these commands instead.
6235
6236 ‘V A’     (‘magit-sequence-continue’)
6237
6238      Resume the current cherry-pick or revert sequence.
6239
6240 ‘V s’     (‘magit-sequence-skip’)
6241
6242      Skip the stopped at commit during a cherry-pick or revert sequence.
6243
6244 ‘V a’     (‘magit-sequence-abort’)
6245
6246      Abort the current cherry-pick or revert sequence.  This discards
6247      all changes made since the sequence started.
6248
6249 
6250 File: magit.info,  Node: Resetting,  Next: Stashing,  Prev: Cherry Picking,  Up: Manipulating
6251
6252 6.10 Resetting
6253 ==============
6254
6255 Also see *note (gitman)git-reset::.
6256
6257 ‘x’     (‘magit-reset-quickly’)
6258
6259      Reset the ‘HEAD’ and index to some commit read from the user and
6260      defaulting to the commit at point, and possibly also reset the
6261      working tree.  With a prefix argument reset the working tree
6262      otherwise don’t.
6263
6264 ‘X m’     (‘magit-reset-mixed’)
6265
6266      Reset the ‘HEAD’ and index to some commit read from the user and
6267      defaulting to the commit at point.  The working tree is kept as-is.
6268
6269 ‘X s’     (‘magit-reset-soft’)
6270
6271      Reset the ‘HEAD’ to some commit read from the user and defaulting
6272      to the commit at point.  The index and the working tree are kept
6273      as-is.
6274
6275 ‘X h’     (‘magit-reset-hard’)
6276
6277      Reset the ‘HEAD’, index, and working tree to some commit read from
6278      the user and defaulting to the commit at point.
6279
6280 ‘X i’     (‘magit-reset-index’)
6281
6282      Reset the index to some commit read from the user and defaulting to
6283      the commit at point.  Keep the ‘HEAD’ and working tree as-is, so if
6284      the commit refers to the ‘HEAD’, then this effectively unstages all
6285      changes.
6286
6287 ‘X w’     (‘magit-reset-worktree’)
6288
6289      Reset the working tree to some commit read from the user and
6290      defaulting to the commit at point.  Keep the ‘HEAD’ and index
6291      as-is.
6292
6293 ‘X f’     (‘magit-file-checkout’)
6294
6295      Update file in the working tree and index to the contents from a
6296      revision.  Both the revision and file are read from the user.
6297
6298 
6299 File: magit.info,  Node: Stashing,  Prev: Resetting,  Up: Manipulating
6300
6301 6.11 Stashing
6302 =============
6303
6304 Also see *note (gitman)git-stash::.
6305
6306 ‘z’     (‘magit-stash-popup’)
6307
6308      This prefix command shows the following suffix commands along with
6309      the appropriate infix arguments in a popup buffer.
6310
6311 ‘z z’     (‘magit-stash-both’)
6312
6313      Create a stash of the index and working tree.  Untracked files are
6314      included according to popup arguments.  One prefix argument is
6315      equivalent to ‘--include-untracked’ while two prefix arguments are
6316      equivalent to ‘--all’.
6317
6318 ‘z i’     (‘magit-stash-index’)
6319
6320      Create a stash of the index only.  Unstaged and untracked changes
6321      are not stashed.
6322
6323 ‘z w’     (‘magit-stash-worktree’)
6324
6325      Create a stash of unstaged changes in the working tree.  Untracked
6326      files are included according to popup arguments.  One prefix
6327      argument is equivalent to ‘--include-untracked’ while two prefix
6328      arguments are equivalent to ‘--all’.
6329
6330 ‘z x’     (‘magit-stash-keep-index’)
6331
6332      Create a stash of the index and working tree, keeping index intact.
6333      Untracked files are included according to popup arguments.  One
6334      prefix argument is equivalent to ‘--include-untracked’ while two
6335      prefix arguments are equivalent to ‘--all’.
6336
6337 ‘z Z’     (‘magit-snapshot-both’)
6338
6339      Create a snapshot of the index and working tree.  Untracked files
6340      are included according to popup arguments.  One prefix argument is
6341      equivalent to ‘--include-untracked’ while two prefix arguments are
6342      equivalent to ‘--all’.
6343
6344 ‘z I’     (‘magit-snapshot-index’)
6345
6346      Create a snapshot of the index only.  Unstaged and untracked
6347      changes are not stashed.
6348
6349 ‘z W’     (‘magit-snapshot-worktree’)
6350
6351      Create a snapshot of unstaged changes in the working tree.
6352      Untracked files are included according to popup arguments.  One
6353      prefix argument is equivalent to ‘--include-untracked’ while two
6354      prefix arguments are equivalent to ‘--all’-.
6355
6356 ‘z a’     (‘magit-stash-apply’)
6357
6358      Apply a stash to the working tree.  Try to preserve the stash
6359      index.  If that fails because there are staged changes, apply
6360      without preserving the stash index.
6361
6362 ‘z p’     (‘magit-stash-pop’)
6363
6364      Apply a stash to the working tree and remove it from stash list.
6365      Try to preserve the stash index.  If that fails because there are
6366      staged changes, apply without preserving the stash index and forgo
6367      removing the stash.
6368
6369 ‘z k’     (‘magit-stash-drop’)
6370
6371      Remove a stash from the stash list.  When the region is active,
6372      offer to drop all contained stashes.
6373
6374 ‘z v’     (‘magit-stash-show’)
6375
6376      Show all diffs of a stash in a buffer.
6377
6378 ‘z b’     (‘magit-stash-branch’)
6379
6380      Create and checkout a new BRANCH from STASH.  The branch starts at
6381      the commit that was current when the stash was created.
6382
6383 ‘z B’     (‘magit-stash-branch-here’)
6384
6385      Create and checkout a new BRANCH using ‘magit-branch’ with the
6386      current branch or ‘HEAD’ as the starting-point.  Then apply STASH,
6387      dropping it if it applies cleanly.
6388
6389 ‘z f’     (‘magit-stash-format-patch’)
6390
6391      Create a patch from STASH.
6392
6393 ‘k’     (‘magit-stash-clear’)
6394
6395      Remove all stashes saved in REF’s reflog by deleting REF.
6396
6397 ‘z l’     (‘magit-stash-list’)
6398
6399      List all stashes in a buffer.
6400
6401  -- User Option: magit-stashes-margin
6402
6403      This option specifies whether the margin is initially shown in
6404      stashes buffers and how it is formatted.
6405
6406      The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
6407
6408         • If INIT is non-nil, then the margin is shown initially.
6409
6410         • STYLE controls how to format the committer date.  It can be
6411           one of ‘age’ (to show the age of the commit),
6412           ‘age-abbreviated’ (to abbreviate the time unit to a
6413           character), or a string (suitable for ‘format-time-string’) to
6414           show the actual date.
6415
6416         • WIDTH controls the width of the margin.  This exists for
6417           forward compatibility and currently the value should not be
6418           changed.
6419
6420         • AUTHOR controls whether the name of the author is also shown
6421           by default.
6422
6423         • AUTHOR-WIDTH has to be an integer.  When the name of the
6424           author is shown, then this specifies how much space is used to
6425           do so.
6426
6427 
6428 File: magit.info,  Node: Transferring,  Next: Miscellaneous,  Prev: Manipulating,  Up: Top
6429
6430 7 Transferring
6431 **************
6432
6433 * Menu:
6434
6435 * Remotes::
6436 * Fetching::
6437 * Pulling::
6438 * Pushing::
6439 * Creating and Sending Patches::
6440 * Applying Patches::
6441
6442 
6443 File: magit.info,  Node: Remotes,  Next: Fetching,  Up: Transferring
6444
6445 7.1 Remotes
6446 ===========
6447
6448 * Menu:
6449
6450 * The Remote Popup::
6451 * The Remote Config Popup::
6452
6453 
6454 File: magit.info,  Node: The Remote Popup,  Next: The Remote Config Popup,  Up: Remotes
6455
6456 7.1.1 The Remote Popup
6457 ----------------------
6458
6459 The popup ‘magit-remote-popup’ is used to add remotes and to make
6460 changes to existing remotes.  This popup only deals with remotes
6461 themselves, not with branches or the transfer of commits.  Those
6462 features are available from separate popups.
6463
6464    Also see *note (gitman)git-remote::.
6465
6466 ‘M’     (‘magit-remote-popup’)
6467
6468      This prefix command shows the following suffix commands along with
6469      the appropriate infix arguments in a popup buffer.
6470
6471  -- User Option: magit-remote-popup-show-variables
6472
6473      This option controls whether the ‘magit-remote-popup’ shows remote
6474      related Git variables.  When set to nil, no variables are displayed
6475      directly in this popup, and the sub-popup
6476      ‘magit-remote-config-popup’ has to be used instead to view and
6477      change remote related variables.
6478
6479 ‘M C’     (‘magit-remote-config-popup’)
6480
6481      This command shows remote related variables in a separate popup.
6482      By default this asks the user for which remote the variables should
6483      be shown.  When ‘magit-remote-popup-show-variables’ is ‘nil’, then
6484      it shows the variables for the upstream of the current branch or
6485      "origin" it that branch has no remote upstream.  To select another
6486      remote use a prefix argument.
6487
6488 ‘M a’     (‘magit-remote-add’)
6489
6490      This command add a remote and fetches it.  The remote name and url
6491      are read in the minibuffer.
6492
6493 ‘M r’     (‘magit-remote-rename’)
6494
6495      This command renames a remote.  Both the old and the new names are
6496      read in the minibuffer.
6497
6498 ‘M u’     (‘magit-remote-set-url’)
6499
6500      This command changes the url of a remote.  Both the remote and the
6501      new url are read in the minibuffer.
6502
6503 ‘M k’     (‘magit-remote-remove’)
6504
6505      This command deletes a remote, read in the minibuffer.
6506
6507 ‘M p’     (‘magit-remote-prune’)
6508
6509      This command removes stale remote-tracking branches for a remote
6510      read in the minibuffer.
6511
6512 ‘M P’     (‘magit-remote-prune-refspecs’)
6513
6514      This command removes stale refspecs for a remote read in the
6515      minibuffer.
6516
6517      A refspec is stale if there no longer exists at least one branch on
6518      the remote that would be fetched due to that refspec.  A stale
6519      refspec is problematic because its existence causes Git to refuse
6520      to fetch according to the remaining non-stale refspecs.
6521
6522      If only stale refspecs remain, then this command offers to either
6523      delete the remote or to replace the stale refspecs with the default
6524      refspec ("+refs/heads/*:refs/remotes/REMOTE/*").
6525
6526      This command also removes the remote-tracking branches that were
6527      created due to the now stale refspecs.  Other stale branches are
6528      not removed.
6529
6530  -- User Option: magit-remote-add-set-remote.pushDefault
6531
6532      This option controls whether the user is asked whether they want to
6533      set ‘remote.pushDefault’ after adding a remote.
6534
6535      If ‘ask’, then users is always ask.  If ‘ask-if-unset’, then the
6536      user is only if the variable isn’t set already.  If ‘nil’, then the
6537      user isn’t asked and the variable isn’t set.  If the value is a
6538      string, then the variable is set without the user being asked,
6539      provided that the name of the added remote is equal to that string
6540      and the variable isn’t already set.
6541
6542 
6543 File: magit.info,  Node: The Remote Config Popup,  Prev: The Remote Popup,  Up: Remotes
6544
6545 7.1.2 The Remote Config Popup
6546 -----------------------------
6547
6548  -- Command: magit-remote-config-popup
6549
6550      This prefix command shows the following remote-related Git
6551      variables in a popup buffer.  The values can be changed from that
6552      buffer.
6553
6554      This popup is a sub-popup of the ‘magit-remote-popup’ in which "C"
6555      is bound to this popup.
6556
6557    The following variables are used to configure a specific remote.  The
6558 values are being displayed for the upstream remote of the current
6559 branch.  To change the value for another remote invoke
6560 ‘magit-remote-config-popup’ with a prefix argument.
6561
6562  -- Variable: remote.NAME.url
6563
6564      This variable specifies the url of the remote named NAME.  It can
6565      have multiple values.
6566
6567  -- Variable: remote.NAME.fetch
6568
6569      The refspec used when fetching from the remote named NAME.  It can
6570      have multiple values.
6571
6572  -- Variable: remote.NAME.pushurl
6573
6574      This variable specifies the url used for fetching from the remote
6575      named NAME.  If it is not specified, then ‘remote.NAME.url’ is used
6576      instead.  It can have multiple values.
6577
6578  -- Variable: remote.NAME.push
6579
6580      The refspec used when pushing to the remote named NAME.  It can
6581      have multiple values.
6582
6583  -- Variable: remote.NAME.tagOpts
6584
6585      This variable specifies what tags are fetched by default.  If the
6586      value is ‘--no-tags’ then no tags are fetched.  If the value is
6587      ‘--tags’, then all tags are fetched.  If this variable has not
6588      value, then only tags are fetched that are reachable from fetched
6589      branches.
6590
6591 
6592 File: magit.info,  Node: Fetching,  Next: Pulling,  Prev: Remotes,  Up: Transferring
6593
6594 7.2 Fetching
6595 ============
6596
6597 For information about the differences between the _upstream_ and the
6598 _push-remote_, see *note Branching::.
6599
6600    Also see *note (gitman)git-fetch::.
6601
6602 ‘f’     (‘magit-fetch-popup’)
6603
6604      This prefix command shows the following suffix commands along with
6605      the appropriate infix arguments in a popup buffer.
6606
6607 ‘f p’     (‘magit-fetch-from-pushremote’)
6608
6609      Fetch from the push-remote of the current branch.
6610
6611 ‘f u’     (‘magit-fetch-from-upstream’)
6612
6613      Fetch from the upstream of the current branch.
6614
6615 ‘f e’     (‘magit-fetch-other’)
6616
6617      Fetch from another repository.
6618
6619 ‘f o’     (‘magit-fetch-branch’)
6620
6621      Fetch a branch from a remote, both of which are read from the
6622      minibuffer.
6623
6624 ‘f r’     (‘magit-fetch-refspec’)
6625
6626      Fetch from a remote using an explicit refspec, both of which are
6627      read from the minibuffer.
6628
6629 ‘f a’     (‘magit-fetch-all’)
6630
6631      Fetch from all remotes.
6632
6633 ‘f m’     (‘magit-submodule-fetch’)
6634
6635      Fetch all submodules.  With a prefix argument fetch all remotes of
6636      all submodules.
6637
6638    Instead of using one popup for fetching and another for pulling, you
6639 could also use ‘magit-pull-and-fetch-popup’.  See its doc-string for
6640 more information.
6641
6642 
6643 File: magit.info,  Node: Pulling,  Next: Pushing,  Prev: Fetching,  Up: Transferring
6644
6645 7.3 Pulling
6646 ===========
6647
6648 For information about the differences between the _upstream_ and the
6649 _push-remote_, see *note Branching::.
6650
6651    Also see *note (gitman)git-pull::.
6652
6653 ‘F’     (‘magit-pull-popup’)
6654
6655      This prefix command shows the following suffix commands in a popup
6656      buffer.
6657
6658 ‘F p’     (‘magit-pull-from-pushremote’)
6659
6660      Pull from the push-remote of the current branch.
6661
6662 ‘F u’     (‘magit-pull-from-upstream’)
6663
6664      Pull from the upstream of the current branch.
6665
6666 ‘F e’     (‘magit-pull-branch’)
6667
6668      Pull from a branch read in the minibuffer.
6669
6670    Instead of using one popup for fetching and another for pulling, you
6671 could also use ‘magit-pull-and-fetch-popup’.  See its doc-string for
6672 more information.
6673
6674 
6675 File: magit.info,  Node: Pushing,  Next: Creating and Sending Patches,  Prev: Pulling,  Up: Transferring
6676
6677 7.4 Pushing
6678 ===========
6679
6680 For information about the differences between the _upstream_ and the
6681 _push-remote_, see *note Branching::.
6682
6683    Also see *note (gitman)git-push::.
6684
6685 ‘P’     (‘magit-push-popup’)
6686
6687      This prefix command shows the following suffix commands along with
6688      the appropriate infix arguments in a popup buffer.
6689
6690 ‘P p’     (‘magit-push-current-to-pushremote’)
6691
6692      Push the current branch to ‘branch.<name>.pushRemote’ or if that is
6693      unset to ‘remote.pushDefault’.
6694
6695      When ‘magit-push-current-set-remote-if-missing’ is non-nil and the
6696      push-remote is not configured, then read the push-remote from the
6697      user, set it, and then push to it.  With a prefix argument the
6698      push-remote can be changed before pushed to it.
6699
6700 ‘P u’     (‘magit-push-current-to-upstream’)
6701
6702      Push the current branch to its upstream branch.
6703
6704      When ‘magit-push-current-set-remote-if-missing’ is non-nil and the
6705      push-remote is not configured, then read the upstream from the
6706      user, set it, and then push to it.  With a prefix argument the
6707      push-remote can be changed before pushed to it.
6708
6709 ‘P e’     (‘magit-push-current’)
6710
6711      Push the current branch to a branch read in the minibuffer.
6712
6713 ‘P o’     (‘magit-push-other’)
6714
6715      Push an arbitrary branch or commit somewhere.  Both the source and
6716      the target are read in the minibuffer.
6717
6718 ‘P r’     (‘magit-push-refspecs’)
6719
6720      Push one or multiple refspecs to a remote, both of which are read
6721      in the minibuffer.
6722
6723      To use multiple refspecs, separate them with commas.  Completion is
6724      only available for the part before the colon, or when no colon is
6725      used.
6726
6727 ‘P m’     (‘magit-push-matching’)
6728
6729      Push all matching branches to another repository.  If multiple
6730      remotes exit, then read one from the user.  If just one exists, use
6731      that without requiring confirmation.
6732
6733 ‘P t’     (‘magit-push-tags’)
6734
6735      Push all tags to another repository.  If only one remote exists,
6736      then push to that.  Otherwise prompt for a remote, offering the
6737      remote configured for the current branch as default.
6738
6739 ‘P T’     (‘magit-push-tag’)
6740
6741      Push a tag to another repository.
6742
6743    Two more push commands exist, which by default are not available from
6744 the push popup.  See their doc-strings for instructions on how to add
6745 them to the popup.
6746
6747  -- Command: magit-push-implicitly args
6748
6749      Push somewhere without using an explicit refspec.
6750
6751      This command simply runs ‘git push -v [ARGS]’.  ARGS are the
6752      arguments specified in the popup buffer.  No explicit refspec
6753      arguments are used.  Instead the behavior depends on at least these
6754      Git variables: ‘push.default’, ‘remote.pushDefault’,
6755      ‘branch.<branch>.pushRemote’, ‘branch.<branch>.remote’,
6756      ‘branch.<branch>.merge’, and ‘remote.<remote>.push’.
6757
6758  -- Command: magit-push-to-remote remote args
6759
6760      Push to the remote REMOTE without using an explicit refspec.  The
6761      remote is read in the minibuffer.
6762
6763      This command simply runs ‘git push -v [ARGS] REMOTE’.  ARGS are the
6764      arguments specified in the popup buffer.  No refspec arguments are
6765      used.  Instead the behavior depends on at least these Git
6766      variables: ‘push.default’, ‘remote.pushDefault’,
6767      ‘branch.<branch>.pushRemote’, ‘branch.<branch>.remote’,
6768      ‘branch.<branch>.merge’, and ‘remote.<remote>.push’.
6769
6770  -- User Option: magit-push-current-set-remote-if-missing
6771
6772      This option controls whether missing remotes are configured before
6773      pushing.
6774
6775      When ‘nil’, then the command ‘magit-push-current-to-pushremote’ and
6776      ‘magit-push-current-to-upstream’ do not appear in the push popup if
6777      the push-remote resp.  upstream is not configured.  If the user
6778      invokes one of these commands anyway, then it raises an error.
6779
6780      When ‘non-nil’, then these commands always appear in the push
6781      popup.  But if the required configuration is missing, then they do
6782      appear in a way that indicates that this is the case.  If the user
6783      invokes one of them, then it asks for the necessary configuration,
6784      stores the configuration, and then uses it to push a first time.
6785
6786      This option also affects whether the argument ‘--set-upstream’ is
6787      available in the popup.  If the value is ‘non-nil’, then that
6788      argument is redundant.  But note that changing the value of this
6789      option does not take affect immediately, the argument will only be
6790      added or removed after restarting Emacs.
6791
6792 
6793 File: magit.info,  Node: Creating and Sending Patches,  Next: Applying Patches,  Prev: Pushing,  Up: Transferring
6794
6795 7.5 Creating and Sending Patches
6796 ================================
6797
6798 ‘W’     (‘magit-patch-popup’)
6799
6800      This prefix command shows the following suffix commands along with
6801      the appropriate infix arguments in a popup buffer.
6802
6803 ‘W p’     (‘magit-format-patch’)
6804
6805      Create patches for a set commits.  If the region marks commits,
6806      then create patches for those.  Otherwise prompt for a range or a
6807      single commit, defaulting to the commit at point.
6808
6809 ‘W r’     (‘magit-request-pull’)
6810
6811      Request that upstream pulls from your public repository.
6812
6813    It is also possible to save a plain patch file by using ‘C-x C-w’
6814 inside a ‘magit-diff-mode’ or ‘magit-revision-mode’ buffer.
6815
6816 
6817 File: magit.info,  Node: Applying Patches,  Prev: Creating and Sending Patches,  Up: Transferring
6818
6819 7.6 Applying Patches
6820 ====================
6821
6822 Also see *note (gitman)git-am::.  and *note (gitman)git-apply::.
6823
6824 ‘w’     (‘magit-am-popup’)
6825
6826      This prefix command shows the following suffix commands along with
6827      the appropriate infix arguments in a popup buffer.
6828
6829 ‘w w’     (‘magit-am-apply-patches’)
6830
6831      Apply one or more patches.  If the region marks files, then apply
6832      those patches.  Otherwise read a file name in the minibuffer
6833      defaulting to the file at point.
6834
6835 ‘w m’     (‘magit-am-apply-maildir’)
6836
6837      Apply the patches from a maildir.
6838
6839    When an "am" operation is in progress, then the popup buffer features
6840 these commands instead.
6841
6842 ‘w w’     (‘magit-am-continue’)
6843
6844      Resume the current patch applying sequence.
6845
6846 ‘w s’     (‘magit-am-skip’)
6847
6848      Skip the stopped at patch during a patch applying sequence.
6849
6850 ‘w a’     (‘magit-am-abort’)
6851
6852      Abort the current patch applying sequence.  This discards all
6853      changes made since the sequence started.
6854
6855    In addition to the commands listed at the top, the "am" popup also
6856 has a binding for the related "patch" popup.
6857
6858 ‘w a’     (‘magit-patch-apply-popup’)
6859
6860      This prefix command shows the following suffix commands along with
6861      the appropriate infix arguments in a popup buffer.
6862
6863 ‘w a a’     (‘magit-patch-apply’)
6864
6865      This command applies a simple patch file, which may not contain any
6866      Git metadata in addition to the actual diff.
6867
6868 
6869 File: magit.info,  Node: Miscellaneous,  Next: Customizing,  Prev: Transferring,  Up: Top
6870
6871 8 Miscellaneous
6872 ***************
6873
6874 * Menu:
6875
6876 * Tagging::
6877 * Notes::
6878 * Submodules::
6879 * Subtree::
6880 * Worktree::
6881 * Common Commands::
6882 * Wip Modes::
6883 * Minor Mode for Buffers Visiting Files::
6884 * Minor Mode for Buffers Visiting Blobs::
6885
6886 
6887 File: magit.info,  Node: Tagging,  Next: Notes,  Up: Miscellaneous
6888
6889 8.1 Tagging
6890 ===========
6891
6892 Also see *note (gitman)git-tag::.
6893
6894 ‘t’     (‘magit-tag-popup’)
6895
6896      This prefix command shows the following suffix commands along with
6897      the appropriate infix arguments in a popup buffer.
6898
6899 ‘t t’     (‘magit-tag-create’)
6900
6901      Create a new tag with the given NAME at REV.  With a prefix
6902      argument annotate the tag.
6903
6904 ‘t k’     (‘magit-tag-delete’)
6905
6906      Delete one or more tags.  If the region marks multiple tags (and
6907      nothing else), then offer to delete those.  Otherwise, prompt for a
6908      single tag to be deleted, defaulting to the tag at point.
6909
6910 ‘t p’     (‘magit-tag-prune’)
6911
6912      Offer to delete tags missing locally from REMOTE, and vice versa.
6913
6914  -- Command: magit-tag-release
6915
6916      Create an opinionated release tag.
6917
6918      Assume version tags that match "\\‘v?[0-9]\*\\’".  Prompt for the
6919      name of the new tag using the highest existing tag as initial input
6920      and call "git tag –annotate –sign -m MSG" TAG, regardless of
6921      whether these arguments are enabled in the popup.  Given a TAG
6922      "v1.2.3" and a repository "/path/to/foo-bar", the MESSAGE would be
6923      "Foo-Bar 1.2.3".
6924
6925      Because it is so opinionated, this command is not available from
6926      the tag popup by default.
6927
6928 
6929 File: magit.info,  Node: Notes,  Next: Submodules,  Prev: Tagging,  Up: Miscellaneous
6930
6931 8.2 Notes
6932 =========
6933
6934 Also see *note (gitman)git-notes::.
6935
6936 ‘T’     (‘magit-notes-popup’)
6937
6938      This prefix command shows the following suffix commands along with
6939      the appropriate infix arguments in a popup buffer.
6940
6941 ‘T T’     (‘magit-notes-edit’)
6942
6943      Edit the note attached to a commit, defaulting to the commit at
6944      point.
6945
6946      By default use the value of Git variable ‘core.notesRef’ or
6947      "refs/notes/commits" if that is undefined.
6948
6949 ‘T r’     (‘magit-notes-remove’)
6950
6951      Remove the note attached to a commit, defaulting to the commit at
6952      point.
6953
6954      By default use the value of Git variable ‘core.notesRef’ or
6955      "refs/notes/commits" if that is undefined.
6956
6957 ‘T p’     (‘magit-notes-prune’)
6958
6959      Remove notes about unreachable commits.
6960
6961    It is possible to merge one note ref into another.  That may result
6962 in conflicts which have to resolved in the temporary worktree
6963 ".git/NOTES_MERGE_WORKTREE".
6964
6965 ‘T m’     (‘magit-notes-merge’)
6966
6967      Merge the notes of a ref read from the user into the current notes
6968      ref.  The current notes ref is the value of Git variable
6969      ‘core.notesRef’ or "refs/notes/commits" if that is undefined.
6970
6971    When a notes merge is in progress then the popup features the
6972 following suffix commands, instead of those listed above.
6973
6974 ‘T c’     (‘magit-notes-merge-commit’)
6975
6976      Commit the current notes ref merge, after manually resolving
6977      conflicts.
6978
6979 ‘T a’     (‘magit-notes-merge-abort’)
6980
6981      Abort the current notes ref merge.
6982
6983    The following variables control what notes reference ‘magit-notes-*’,
6984 ‘git notes’ and ‘git show’ act on and display.  Both the local and
6985 global values are displayed and can be modified.
6986
6987  -- Variable: core.notesRef
6988
6989      This variable specifies the notes ref that is displayed by default
6990      and which commands act on by default.
6991
6992  -- Variable: notes.displayRef
6993
6994      This variable specifies additional notes ref to be displayed in
6995      addition to the ref specified by ‘core.notesRef’.  It can have
6996      multiple values and may end with ‘*’ to display all refs in the
6997      ‘refs/notes/’ namespace (or ‘**’ if some names contain slashes).
6998
6999 
7000 File: magit.info,  Node: Submodules,  Next: Subtree,  Prev: Notes,  Up: Miscellaneous
7001
7002 8.3 Submodules
7003 ==============
7004
7005 Also see *note (gitman)git-submodule::.
7006
7007 * Menu:
7008
7009 * Listing Submodules::
7010 * Submodule Popup::
7011
7012 
7013 File: magit.info,  Node: Listing Submodules,  Next: Submodule Popup,  Up: Submodules
7014
7015 8.3.1 Listing Submodules
7016 ------------------------
7017
7018 The command ‘magit-list-submodules’ displays a list of the current
7019 repository’s submodules in a separate buffer.  It’s also possible to
7020 display information about submodules directly in the status buffer of
7021 the super-repository by adding ‘magit-insert-submodules’ to the hook
7022 ‘magit-status-sections-hook’ as described in *note Status Module
7023 Sections::.
7024
7025  -- Command: magit-list-submodules
7026
7027      This command displays a list of the current repository’s submodules
7028      in a separate buffer.
7029
7030      It can be invoked by pressing ‘RET’ on the section titled
7031      "Modules".
7032
7033  -- User Option: magit-submodule-list-columns
7034
7035      This option controls what columns are displayed by the command
7036      ‘magit-list-submodules’ and how they are displayed.
7037
7038      Each element has the form ‘(HEADER WIDTH FORMAT PROPS)’.
7039
7040      HEADER is the string displayed in the header.  WIDTH is the width
7041      of the column.  FORMAT is a function that is called with one
7042      argument, the repository identification (usually its basename), and
7043      with ‘default-directory’ bound to the toplevel of its working tree.
7044      It has to return a string to be inserted or nil.  PROPS is an alist
7045      that supports the keys ‘:right-align’ and ‘:pad-right’.
7046
7047  -- Function: magit-insert-submodules
7048
7049      Insert sections for all submodules.  For each section insert the
7050      path, the branch, and the output of ‘git describe --tags’, or,
7051      failing that, the abbreviated HEAD commit hash.
7052
7053      Press ‘RET’ on such a submodule section to show its own status
7054      buffer.  Press ‘RET’ on the "Modules" section to display a list of
7055      submodules in a separate buffer.  This shows additional information
7056      not displayed in the super-repository’s status buffer.
7057
7058 
7059 File: magit.info,  Node: Submodule Popup,  Prev: Listing Submodules,  Up: Submodules
7060
7061 8.3.2 Submodule Popup
7062 ---------------------
7063
7064 ‘o’     (‘magit-submodule-popup’)
7065
7066      This prefix command shows the following suffix commands along with
7067      the appropriate infix arguments in a popup buffer.
7068
7069    Some of the below commands default to act on the modules that are
7070 selected using the region.  For brevity their description talk about
7071 "the selected modules", but if no modules are selected, then they act on
7072 the current module instead, or if point isn’t on a module, then the read
7073 a single module to act on.  With a prefix argument these commands ignore
7074 the selection and the current module and instead act on all suitable
7075 modules.
7076
7077 ‘o a’     (‘magit-submodule-add’)
7078
7079      This commands adds the repository at URL as a module.  Optional
7080      PATH is the path to the module relative to the root of the
7081      super-project.  If it is nil then the path is determined based on
7082      URL.
7083
7084 ‘o r’     (‘magit-submodule-register’)
7085
7086      This command registers the selected modules by copying their urls
7087      from ".gitmodules" to "$GIT_DIR/config".  These values can then be
7088      edited before running ‘magit-submodule-populate’.  If you don’t
7089      need to edit any urls, then use the latter directly.
7090
7091 ‘o p’     (‘magit-submodule-populate’)
7092
7093      This command creates the working directory or directories of the
7094      selected modules, checking out the recorded commits.
7095
7096 ‘o u’     (‘magit-submodule-update’)
7097
7098      This command updates the selected modules checking out the recorded
7099      commits.
7100
7101 ‘o s’     (‘magit-submodule-synchronize’)
7102
7103      This command synchronizes the urls of the selected modules, copying
7104      the values from ".gitmodules" to the ".git/config" of the
7105      super-project as well those of the modules.
7106
7107 ‘o d’     (‘magit-submodule-unpopulate’)
7108
7109      This command removes the working directory of the selected modules.
7110
7111 ‘o l’     (‘magit-list-submodules’)
7112
7113      This command displays a list of the current repository’s modules.
7114
7115 ‘o f’     (‘magit-fetch-modules’)
7116
7117      This command fetches all modules.
7118
7119      Option ‘magit-fetch-modules-jobs’ controls how many submodules are
7120      being fetched in parallel.  Also fetch the super-repository,
7121      because ‘git fetch’ does not support not doing that.  With a prefix
7122      argument fetch all remotes.
7123
7124 
7125 File: magit.info,  Node: Subtree,  Next: Worktree,  Prev: Submodules,  Up: Miscellaneous
7126
7127 8.4 Subtree
7128 ===========
7129
7130 Also see *note (gitman)git-subtree::.
7131
7132 ‘O’     (‘magit-tree-popup’)
7133
7134      This prefix command shows the following suffix commands along with
7135      the appropriate infix arguments in a popup buffer.
7136
7137    Most infix arguments only apply to some of the ‘git subtree’
7138 subcommands.  When an argument that does not apply to the invoked
7139 command is set, then it is silently ignored.
7140
7141    When the ‘--prefix’ argument is set in the popup buffer, then that is
7142 used.  Otherwise the prefix is read in the minibuffer.
7143
7144 ‘O a’     (‘magit-subtree-add’)
7145
7146      Add COMMIT from REPOSITORY as a new subtree at PREFIX.
7147
7148 ‘O c’     (‘magit-subtree-add-commit’)
7149
7150      Add COMMIT as a new subtree at PREFIX.
7151
7152 ‘O m’     (‘magit-subtree-merge’)
7153
7154      Merge COMMIT into the PREFIX subtree.
7155
7156 ‘O f’     (‘magit-subtree-pull’)
7157
7158      Pull COMMIT from REPOSITORY into the PREFIX subtree.
7159
7160 ‘O p’     (‘magit-subtree-push’)
7161
7162      Extract the history of the subtree PREFIX and push it to REF on
7163      REPOSITORY.
7164
7165 ‘O s’     (‘magit-subtree-split’)
7166
7167      Extract the history of the subtree PREFIX.
7168
7169 
7170 File: magit.info,  Node: Worktree,  Next: Common Commands,  Prev: Subtree,  Up: Miscellaneous
7171
7172 8.5 Worktree
7173 ============
7174
7175 Also see *note (gitman)git-worktree::.
7176
7177 ‘%’     (‘magit-worktree-popup’)
7178
7179      This prefix command shows the following suffix commands in a popup
7180      buffer.
7181
7182 ‘% b’     (‘magit-worktree-checkout’)
7183
7184      Checkout BRANCH in a new worktree at PATH.
7185
7186 ‘% c’     (‘magit-worktree-branch’)
7187
7188      Create a new BRANCH and check it out in a new worktree at PATH.
7189
7190 ‘% p’     (‘magit-worktree-checkout-pull-request’)
7191
7192      Create, configure and checkout a new worktree from a pull-request.
7193
7194      This is like ‘magit-checkout-pull-request’ (which see) except that
7195      it also creates a new worktree.
7196
7197 ‘% k’     (‘magit-worktree-delete’)
7198
7199      Delete a worktree, defaulting to the worktree at point.  The
7200      primary worktree cannot be deleted.
7201
7202 ‘% g’     (‘magit-worktree-status’)
7203
7204      Show the status for the worktree at point.
7205
7206      If there is no worktree at point, then read one in the minibuffer.
7207      If the worktree at point is the one whose status is already being
7208      displayed in the current buffer, then show it in Dired instead.
7209
7210 
7211 File: magit.info,  Node: Common Commands,  Next: Wip Modes,  Prev: Worktree,  Up: Miscellaneous
7212
7213 8.6 Common Commands
7214 ===================
7215
7216 These are some of the commands that can be used in all buffers whose
7217 major-modes derive from ‘magit-mode’.  There are other common commands
7218 beside the ones below, but these didn’t fit well anywhere else.
7219
7220 ‘M-w’     (‘magit-copy-section-value’)
7221
7222      This command saves the value of the current section to the
7223      ‘kill-ring’, and, provided that the current section is a commit,
7224      branch, or tag section, it also pushes the (referenced) revision to
7225      the ‘magit-revision-stack’.
7226
7227      When the current section is a branch or a tag, and a prefix
7228      argument is used, then it saves the revision at its tip to the
7229      ‘kill-ring’ instead of the reference name.
7230
7231 ‘C-w’     (‘magit-copy-buffer-revision’)
7232
7233      This command saves the revision being displayed in the current
7234      buffer to the ‘kill-ring’ and also pushes it to the
7235      ‘magit-revision-stack’.  It is mainly intended for use in
7236      ‘magit-revision-mode’ buffers, the only buffers where it is always
7237      unambiguous exactly which revision should be saved.
7238
7239      Most other Magit buffers usually show more than one revision, in
7240      some way or another, so this command has to select one of them, and
7241      that choice might not always be the one you think would have been
7242      the best pick.
7243
7244    Outside of Magit ‘M-w’ and ‘C-w’ are usually bound to
7245 ‘kill-ring-save’ and ‘kill-region’, and these commands would also be
7246 useful in Magit buffers.  Therefore when the region is active, then both
7247 of these commands behave like ‘kill-ring-save’ instead of as described
7248 above.
7249
7250 
7251 File: magit.info,  Node: Wip Modes,  Next: Minor Mode for Buffers Visiting Files,  Prev: Common Commands,  Up: Miscellaneous
7252
7253 8.7 Wip Modes
7254 =============
7255
7256 Git keeps *committed* changes around long enough for users to recover
7257 changes they have accidentally deleted.  It does so by not garbage
7258 collecting any committed but no longer referenced objects for a certain
7259 period of time, by default 30 days.
7260
7261    But Git does *not* keep track of *uncommitted* changes in the working
7262 tree and not even the index (the staging area).  Because Magit makes it
7263 so convenient to modify uncommitted changes, it also makes it easy to
7264 shoot yourself in the foot in the process.
7265
7266    For that reason Magit provides a global mode that saves *tracked*
7267 files to work-in-progress references after or before certain actions.
7268 (At present untracked files are never saved and for technical reasons
7269 nothing is saved before the first commit has been created).
7270
7271    Two separate work-in-progress references are used to track the state
7272 of the index and of the working tree: ‘refs/wip/index/<branchref>’ and
7273 ‘refs/wip/wtree/<branchref>’, where ‘<branchref>’ is the full ref of the
7274 current branch, e.g.  ‘refs/heads/master’.  When the ‘HEAD’ is detached
7275 then ‘HEAD’ is used in place of ‘<branchref>’.
7276
7277    Checking out another branch (or detaching ‘HEAD’) causes the use of
7278 different wip refs for subsequent changes.
7279
7280  -- User Option: magit-wip-mode
7281
7282      When this mode is enabled, then uncommitted changes are committed
7283      to dedicated work-in-progress refs whenever appropriate (i.e.  when
7284      dataloss would be a possibility otherwise).
7285
7286      Setting this variable directly does not take effect; either use the
7287      Custom interface to do so or call the respective mode function.
7288
7289      For historic reasons this mode is implemented on top of four other
7290      ‘magit-wip-*’ modes, which can also be used individually, if you
7291      want finer control over when the wip refs are updated; but that is
7292      discouraged.  See *note Legacy Wip Modes::.
7293
7294    To view the log for a branch and its wip refs use the commands
7295 ‘magit-wip-log’ and ‘magit-wip-log-current’.  You should use ‘--graph’
7296 when using these commands.
7297
7298  -- Command: magit-wip-log
7299
7300      This command shows the log for a branch and its wip refs.  With a
7301      negative prefix argument only the worktree wip ref is shown.
7302
7303      The absolute numeric value of the prefix argument controls how many
7304      "branches" of each wip ref are shown.  This is only relevant if the
7305      value of ‘magit-wip-merge-branch’ is ‘nil’.
7306
7307  -- Command: magit-wip-log-current
7308
7309      This command shows the log for the current branch and its wip refs.
7310      With a negative prefix argument only the worktree wip ref is shown.
7311
7312      The absolute numeric value of the prefix argument controls how many
7313      "branches" of each wip ref are shown.  This is only relevant if the
7314      value of ‘magit-wip-merge-branch’ is ‘nil’.
7315
7316 ‘X w’     (‘magit-reset-worktree’)
7317
7318      This command resets the working tree to some commit read from the
7319      user and defaulting to the commit at point, while keeping the
7320      ‘HEAD’ and index as-is.
7321
7322      This can be used to restore files to the state committed to a wip
7323      ref.  Note that this will discard any unstaged changes that might
7324      have existed before invoking this command (but of course only after
7325      committing that to the working tree wip ref).
7326
7327    Note that even if you enable ‘magit-wip-mode’ this won’t give you
7328 perfect protection.  The most likely scenario for losing changes despite
7329 the use of ‘magit-wip-mode’ is making a change outside Emacs and then
7330 destroying it also outside Emacs.  In some such a scenario, Magit, being
7331 an Emacs package, didn’t get the opportunity to keep you from shooting
7332 yourself in the foot.
7333
7334    When you are unsure whether Magit did commit a change to the wip
7335 refs, then you can explicitly request that all changes to all tracked
7336 files are being committed.
7337
7338 ‘M-x magit-wip-commit’     (‘magit-wip-commit’)
7339
7340      This command commits all changes to all tracked files to the index
7341      and working tree work-in-progress refs.  Like the modes described
7342      above, it does not commit untracked files, but it does check all
7343      tracked files for changes.  Use this command when you suspect that
7344      the modes might have overlooked a change made outside Emacs/Magit.
7345
7346  -- User Option: magit-wip-namespace
7347
7348      The namespace used for work-in-progress refs.  It has to end with a
7349      slash.  The wip refs are named ‘<namespace>index/<branchref>’ and
7350      ‘<namespace>wtree/<branchref>’.  When snapshots are created while
7351      the ‘HEAD’ is detached then ‘HEAD’ is used in place of
7352      ‘<branchref>’.
7353
7354  -- User Option: magit-wip-mode-lighter
7355
7356      Mode-line lighter for ‘magit-wip--mode’.
7357
7358 * Menu:
7359
7360 * Wip Graph::
7361 * Legacy Wip Modes::
7362
7363 
7364 File: magit.info,  Node: Wip Graph,  Next: Legacy Wip Modes,  Up: Wip Modes
7365
7366 8.7.1 Wip Graph
7367 ---------------
7368
7369  -- User Option: magit-wip-merge-branch
7370
7371      This option controls whether the current branch is merged into the
7372      wip refs after a new commit was created on the branch.
7373
7374      If non-nil and the current branch has new commits, then it is
7375      merged into the wip ref before creating a new wip commit.  This
7376      makes it easier to inspect wip history and the wip commits are
7377      never garbage collected.
7378
7379      If nil and the current branch has new commits, then the wip ref is
7380      reset to the tip of the branch before creating a new wip commit.
7381      With this setting wip commits are eventually garbage collected.
7382
7383    When ‘magit-wip-merge-branch’ is ‘t’, then the history looks like
7384 this:
7385
7386        *--*--*--*--*--*       refs/wip/index/refs/heads/master
7387       /     /     /
7388      A-----B-----C            refs/heads/master
7389
7390    When ‘magit-wip-merge-branch’ is ‘nil’, then creating a commit on the
7391 real branch and then making a change causes the wip refs to be recreated
7392 to fork from the new commit.  But the old commits on the wip refs are
7393 not lost.  They are still available from the reflog.  To make it easier
7394 to see when the fork point of a wip ref was changed, an additional
7395 commit with the message "restart autosaving" is created on it (‘xxO’
7396 commits below are such boundary commits).
7397
7398    Starting with
7399
7400            BI0---BI1    refs/wip/index/refs/heads/master
7401           /
7402      A---B              refs/heads/master
7403           \
7404            BW0---BW1    refs/wip/wtree/refs/heads/master
7405
7406    and committing the staged changes and editing and saving a file would
7407 result in
7408
7409            BI0---BI1        refs/wip/index/refs/heads/master
7410           /
7411      A---B---C              refs/heads/master
7412           \   \
7413            \   CW0---CW1    refs/wip/wtree/refs/heads/master
7414             \
7415              BW0---BW1      refs/wip/wtree/refs/heads/master@{2}
7416
7417    The fork-point of the index wip ref is not changed until some change
7418 is being staged.  Likewise just checking out a branch or creating a
7419 commit does not change the fork-point of the working tree wip ref.  The
7420 fork-points are not adjusted until there actually is a change that
7421 should be committed to the respective wip ref.
7422
7423 
7424 File: magit.info,  Node: Legacy Wip Modes,  Prev: Wip Graph,  Up: Wip Modes
7425
7426 8.7.2 Legacy Wip Modes
7427 ----------------------
7428
7429 It is recommended that you use the mode ‘magit-wip-mode’ (which see) and
7430 ignore the existence of the following modes, which are preserved for
7431 historic reasons.
7432
7433    Setting the following variables directly does not take effect; either
7434 use the Custom interface to do so or call the respective mode functions.
7435
7436  -- User Option: magit-wip-after-save-mode
7437
7438      When this mode is enabled, then saving a buffer that visits a file
7439      tracked in a Git repository causes its current state to be
7440      committed to the working tree wip ref for the current branch.
7441
7442  -- User Option: magit-wip-after-apply-mode
7443
7444      When this mode is enabled, then applying (i.e.  staging, unstaging,
7445      discarding, reversing, and regularly applying) a change to a file
7446      tracked in a Git repository causes its current state to be
7447      committed to the index and/or working tree wip refs for the current
7448      branch.
7449
7450    If you only ever edit files using Emacs and only ever interact with
7451 Git using Magit, then the above two modes should be enough to protect
7452 each and every change from accidental loss.  In practice nobody does
7453 that.  Two additional modes exists that do commit to the wip refs before
7454 making changes that could cause the loss of earlier changes.
7455
7456  -- User Option: magit-wip-before-change-mode
7457
7458      When this mode is enabled, then certain commands commit the
7459      existing changes to the files they are about to make changes to.
7460
7461  -- User Option: magit-wip-initial-backup-mode
7462
7463      When this mode is enabled, then the current version of a file is
7464      committed to the worktree wip ref before the buffer visiting that
7465      file is saved for the first time since the buffer was created.
7466
7467      This backs up the same version of the file that ‘backup-buffer’
7468      would save.  While ‘backup-buffer’ uses a backup file, this mode
7469      uses the same worktree wip ref as used by the other Magit Wip
7470      modes.  Like ‘backup-buffer’, it only does this once; unless you
7471      kill the buffer and visit the file again only one backup will be
7472      created per Emacs session.
7473
7474      This mode ignores the variables that affect ‘backup-buffer’ and can
7475      be used along-side that function, which is recommended because it
7476      only backs up files that are tracked in a Git repository.
7477
7478  -- User Option: magit-wip-after-save-local-mode-lighter
7479
7480      Mode-line lighter for ‘magit-wip-after-save-local-mode’.
7481
7482  -- User Option: magit-wip-after-apply-mode-lighter
7483
7484      Mode-line lighter for ‘magit-wip-after-apply-mode’.
7485
7486  -- User Option: magit-wip-before-change-mode-lighter
7487
7488      Mode-line lighter for ‘magit-wip-before-change-mode’.
7489
7490  -- User Option: magit-wip-initial-backup-mode-lighter
7491
7492      Mode-line lighter for ‘magit-wip-initial-backup-mode’.
7493
7494 
7495 File: magit.info,  Node: Minor Mode for Buffers Visiting Files,  Next: Minor Mode for Buffers Visiting Blobs,  Prev: Wip Modes,  Up: Miscellaneous
7496
7497 8.8 Minor Mode for Buffers Visiting Files
7498 =========================================
7499
7500 The ‘magit-file-mode’ enables certain Magit features in file-visiting
7501 buffers belonging to a Git repository.  It should be enabled globally
7502 using ‘global-magit-file-mode’.  Currently this mode only establishes a
7503 few key bindings, but this might be extended in the future.
7504
7505  -- User Option: magit-file-mode
7506
7507      Whether to establish certain Magit key bindings in all
7508      file-visiting buffers belonging to a Git repository.  This
7509      establishes the bindings suggested in *note Getting Started:: (but
7510      only for file-visiting buffers), and additionally binds ‘C-c M-g’
7511      to ‘magit-file-popup’.
7512
7513 ‘C-c M-g’     (‘magit-file-popup’)
7514
7515      This prefix command shows a popup buffer featuring suffix commands
7516      that operate on the file being visited in the current buffer.
7517
7518 ‘C-c M-g s’     (‘magit-stage-file’)
7519
7520      Stage all changes to the file being visited in the current buffer.
7521
7522 ‘C-c M-g u’     (‘magit-unstage-file’)
7523
7524      Unstage all changes to the file being visited in the current
7525      buffer.
7526
7527 ‘C-c M-g c’     (‘magit-commit-popup’)
7528
7529      This prefix command shows suffix commands along with the
7530      appropriate infix arguments in a popup buffer.  See *note
7531      Initiating a Commit::.
7532
7533 ‘C-c M-g D’     (‘magit-diff-buffer-file-popup’)
7534
7535      This prefix command shows the same suffix commands and infix
7536      arguments in a popup buffer as ‘magit-diff-popup’.  But this
7537      variant has to be called from a file-visiting buffer and the
7538      visited file is automatically used in the popup to limit the diff
7539      to that file.
7540
7541 ‘C-c M-g d’     (‘magit-diff-buffer-file’)
7542
7543      This command shows the diff for the file of blob that the current
7544      buffer visits.
7545
7546  -- User Option: magit-diff-buffer-file-locked
7547
7548      This option controls whether ‘magit-diff-buffer-file’ uses a
7549      dedicated buffer.  See *note Modes and Buffers::.
7550
7551 ‘C-c M-g L’     (‘magit-log-buffer-file-popup’)
7552
7553      This prefix command shows the same suffix commands and infix
7554      arguments in a popup buffer as ‘magit-log-popup’.  But this variant
7555      has to be called from a file-visiting buffer and the visited file
7556      is automatically used in the popup to limit the log to that file.
7557
7558 ‘C-c M-g l’     (‘magit-log-buffer-file’)
7559
7560      This command shows the log for the file of blob that the current
7561      buffer visits.  Renames are followed when a prefix argument is used
7562      or when ‘--follow’ is part of ‘magit-log-arguments’.  When the
7563      region is active, the log is restricted to the selected line range.
7564
7565 ‘C-c M-g t’     (‘magit-log-trace-definition’)
7566
7567      This command shows the log for the definition at point.
7568
7569  -- User Option: magit-log-buffer-file-locked
7570
7571      This option controls whether ‘magit-log-buffer-file’ uses a
7572      dedicated buffer.  See *note Modes and Buffers::.
7573
7574 ‘C-c M-g B’     (‘magit-blame-popup’)
7575
7576      This prefix command shows all blaming suffix command along with the
7577      appropriate infix arguments in a popup buffer.  See *note
7578      Blaming::.
7579
7580 ‘C-c M-g b’     (‘magit-blame-addition’)
7581
7582      This command shows for each line the revision in which it was
7583      added.
7584
7585 ‘C-c M-g r’     (‘magit-blame-removal’)
7586
7587      This command shows for each line the revision in which it was
7588      removed.  This command is only available in blob-visiting buffers.
7589
7590 ‘C-c M-g f’     (‘magit-blame-reverse’)
7591
7592      This command shows for each line the last revision in which it
7593      still exists.  This command is only available in blob-visiting
7594      buffers.
7595
7596 ‘C-c M-g e’     (‘magit-edit-line-commit’)
7597
7598      This command makes the commit editable that added the current line.
7599
7600      With a prefix argument it makes the commit editable that removes
7601      the line, if any.  The commit is determined using ‘git blame’ and
7602      made editable using ‘git rebase --interactive’ if it is reachable
7603      from ‘HEAD’, or by checking out the commit (or a branch that points
7604      at it) otherwise.
7605
7606 ‘C-c M-g p’     (‘magit-blob-previous’)
7607
7608      Visit the previous blob which modified the current file.
7609
7610    There are a few additional commands that operate on a single file but
7611 are not available from the file popup by default:
7612
7613  -- Command: magit-file-rename
7614
7615      This command renames a file read from the user.
7616
7617  -- Command: magit-file-delete
7618
7619      This command deletes a file read from the user.
7620
7621  -- Command: magit-file-untrack
7622
7623      This command untracks a file read from the user.
7624
7625  -- Command: magit-file-checkout
7626
7627      This command updates a file in the working tree and index to the
7628      contents from a revision.  Both the revision and file are read from
7629      the user.
7630
7631    You could add them to the popup like so:
7632
7633      (magit-define-popup-action 'magit-file-popup
7634        ?R "Rename file" 'magit-file-rename)
7635      (magit-define-popup-action 'magit-file-popup
7636        ?K "Delete file" 'magit-file-delete)
7637      (magit-define-popup-action 'magit-file-popup
7638        ?U "Untrack file" 'magit-file-untrack)
7639      (magit-define-popup-action 'magit-file-popup
7640        ?C "Checkout file" 'magit-file-checkout)
7641
7642 
7643 File: magit.info,  Node: Minor Mode for Buffers Visiting Blobs,  Prev: Minor Mode for Buffers Visiting Files,  Up: Miscellaneous
7644
7645 8.9 Minor Mode for Buffers Visiting Blobs
7646 =========================================
7647
7648 The ‘magit-blob-mode’ enables certain Magit features in blob-visiting
7649 buffers.  Such buffers can be created using ‘magit-find-file’ and some
7650 of the commands mentioned below, which also take care of turning on this
7651 minor mode.  Currently this mode only establishes a few key bindings,
7652 but this might be extended.
7653
7654 ‘p’     (‘magit-blob-previous’)
7655
7656      Visit the previous blob which modified the current file.
7657
7658 ‘n’     (‘magit-blob-next’)
7659
7660      Visit the next blob which modified the current file.
7661
7662 ‘q’     (‘magit-kill-this-buffer’)
7663
7664      Kill the current buffer.
7665
7666 
7667 File: magit.info,  Node: Customizing,  Next: Plumbing,  Prev: Miscellaneous,  Up: Top
7668
7669 9 Customizing
7670 *************
7671
7672 Both Git and Emacs are highly customizable.  Magit is both a Git
7673 porcelain as well as an Emacs package, so it makes sense to customize it
7674 using both Git variables as well as Emacs options.  However this
7675 flexibility doesn’t come without problems, including but not limited to
7676 the following.
7677
7678    • Some Git variables automatically have an effect in Magit without
7679      requiring any explicit support.  Sometimes that is desirable - in
7680      other cases, it breaks Magit.
7681
7682      When a certain Git setting breaks Magit but you want to keep using
7683      that setting on the command line, then that can be accomplished by
7684      overriding the value for Magit only by appending something like
7685      ‘("-c" "some.variable=compatible-value")’ to
7686      ‘magit-git-global-arguments’.
7687
7688    • Certain settings like ‘fetch.prune=true’ are respected by Magit
7689      commands (because they simply call the respective Git command) but
7690      their value is not reflected in the respective popup buffers.  In
7691      this case the ‘--prune’ argument in ‘magit-fetch-popup’ might be
7692      active or inactive depending on the value of
7693      ‘magit-fetch-arguments’ only, but that doesn’t keep the Git
7694      variable from being honored by the suffix commands anyway.  So
7695      pruning might happen despite the ‘--prune’ arguments being
7696      displayed in a way that seems to indicate that no pruning will
7697      happen.
7698
7699    I intend to address these and similar issues in a future release.
7700
7701 * Menu:
7702
7703 * Per-Repository Configuration::
7704 * Essential Settings::
7705
7706 
7707 File: magit.info,  Node: Per-Repository Configuration,  Next: Essential Settings,  Up: Customizing
7708
7709 9.1 Per-Repository Configuration
7710 ================================
7711
7712 Magit can be configured on a per-repository level using both Git
7713 variables as well as Emacs options.
7714
7715    To set a Git variable for one repository only, simply set it in
7716 ‘/path/to/repo/.git/config’ instead of ‘$HOME/.gitconfig’ or
7717 ‘/etc/gitconfig’.  See *note (gitman)git-config::.
7718
7719    Similarly, Emacs options can be set for one repository only by
7720 editing ‘/path/to/repo/.dir-locals.el’.  See *note (emacs)Directory
7721 Variables::.  For example to disable automatic refreshes of
7722 file-visiting buffers in just one huge repository use this:
7723
7724    • ‘/path/to/huge/repo/.dir-locals.el’
7725
7726           ((nil . ((magit-refresh-buffers . nil))))
7727
7728    If you want to apply the same settings to several, but not all,
7729 repositories then keeping the repository-local config files in sync
7730 would quickly become annoying.  To avoid that you can create config
7731 files for certain classes of repositories (e.g.  "huge repositories")
7732 and then include those files in the per-repository config files.  For
7733 example:
7734
7735    • ‘/path/to/huge/repo/.git/config’
7736
7737           [include]
7738                   path = /path/to/huge-gitconfig
7739
7740    • ‘/path/to/huge-gitconfig’
7741
7742           [status]
7743                   showUntrackedFiles = no
7744
7745    • ‘$HOME/.emacs.d/init.el’
7746
7747           (dir-locals-set-class-variables 'huge-git-repository
7748              '((nil . ((magit-refresh-buffers . nil)))))
7749
7750           (dir-locals-set-directory-class
7751              "/path/to/huge/repo/" 'huge-git-repository)
7752
7753 
7754 File: magit.info,  Node: Essential Settings,  Prev: Per-Repository Configuration,  Up: Customizing
7755
7756 9.2 Essential Settings
7757 ======================
7758
7759 The next two sections list and discuss several variables that many users
7760 might want to customize, for safety and/or performance reasons.
7761
7762 * Menu:
7763
7764 * Safety::
7765 * Performance::
7766
7767 
7768 File: magit.info,  Node: Safety,  Next: Performance,  Up: Essential Settings
7769
7770 9.2.1 Safety
7771 ------------
7772
7773 This section discusses various variables that you might want to change
7774 (or *not* change) for safety reasons.
7775
7776    Git keeps *committed* changes around long enough for users to recover
7777 changes they have accidentally been deleted.  It does not do the same
7778 for *uncommitted* changes in the working tree and not even the index
7779 (the staging area).  Because Magit makes it so easy to modify
7780 uncommitted changes, it also makes it easy to shoot yourself in the foot
7781 in the process.  For that reason Magit provides three global modes that
7782 save *tracked* files to work-in-progress references after or before
7783 certain actions.  See *note Wip Modes::.
7784
7785    These modes are not enabled by default because of performance
7786 concerns.  Instead a lot of potentially destructive commands require
7787 confirmation every time they are used.  In many cases this can be
7788 disabled by adding a symbol to ‘magit-no-confirm’ (see *note Completion
7789 and Confirmation::).  If you enable the various wip modes then you
7790 should add ‘safe-with-wip’ to this list.
7791
7792    Similarly it isn’t necessary to require confirmation before moving a
7793 file to the system trash - if you trashed a file by mistake then you can
7794 recover it from the there.  Option ‘magit-delete-by-moving-to-trash’
7795 controls whether the system trash is used, which is the case by default.
7796 Nevertheless, ‘trash’ isn’t a member of ‘magit-no-confirm’ - you might
7797 want to change that.
7798
7799    By default buffers visiting files are automatically reverted when the
7800 visited file changes on disk.  This isn’t as risky as it might seem, but
7801 to make an informed decision you should see *note Risk of Reverting
7802 Automatically::.
7803
7804 
7805 File: magit.info,  Node: Performance,  Prev: Safety,  Up: Essential Settings
7806
7807 9.2.2 Performance
7808 -----------------
7809
7810 After Magit has run ‘git’ for side-effects, it also refreshes the
7811 current Magit buffer and the respective status buffer.  This is
7812 necessary because otherwise outdated information might be displayed
7813 without the user noticing.  Magit buffers are updated by recreating
7814 their content from scratch, which makes updating simpler and less
7815 error-prone, but also more costly.  Keeping it simple and just
7816 re-creating everything from scratch is an old design decision and
7817 departing from that will require major refactoring.
7818
7819    I plan to do that in time for the next major release.  I also intend
7820 to create logs and diffs asynchronously, which should also help a lot
7821 but also requires major refactoring.
7822
7823    Meanwhile you can tell Magit to only automatically refresh the
7824 current Magit buffer, but not the status buffer.  If you do that, then
7825 the status buffer is only refreshed automatically if it is the current
7826 buffer.
7827
7828      (setq magit-refresh-status-buffer nil)
7829
7830    You should also check whether any third-party packages have added
7831 anything to ‘magit-refresh-buffer-hook’, ‘magit-status-refresh-hook’,
7832 ‘magit-pre-refresh-hook’, and ‘magit-post-refresh-hook’.  If so, then
7833 check whether those additions impact performance significantly.  Setting
7834 ‘magit-refresh-verbose’ and then inspecting the output in the
7835 ‘*Messages*’ buffer, should help doing so.
7836
7837    Magit also reverts buffers for visited files located inside the
7838 current repository when the visited file changes on disk.  That is
7839 implemented on top of ‘auto-revert-mode’ from the built-in library
7840 ‘autorevert’.  To figure out whether that impacts performance, check
7841 whether performance is significantly worse, when many buffers exist
7842 and/or when some buffers visit files using TRAMP.  If so, then this
7843 should help.
7844
7845      (setq auto-revert-buffer-list-filter
7846            'magit-auto-revert-repository-buffers-p)
7847
7848    For alternative approaches see *note Automatic Reverting of
7849 File-Visiting Buffers::.
7850
7851    If you have enabled any features that are disabled by default, then
7852 you should check whether they impact performance significantly.  It’s
7853 likely that they were not enabled by default because it is known that
7854 they reduce performance at least in large repositories.
7855
7856    If performance is only slow inside certain unusually large
7857 repositories, then you might want to disable certain features on a
7858 per-repository or per-repository-class basis only.  See *note
7859 Per-Repository Configuration::.
7860
7861 * Menu:
7862
7863 * Microsoft Windows Performance::
7864 * MacOS Performance::
7865
7866 Log Performance
7867 ...............
7868
7869 When showing logs, Magit limits the number of commits initially shown in
7870 the hope that this avoids unnecessary work.  When using ‘--graph’ is
7871 used, then this unfortunately does not have the desired effect for large
7872 histories.  Junio, Git’s maintainer, said on the git mailing list
7873 (<http://www.spinics.net/lists/git/msg232230.html>): "‘--graph’ wants to
7874 compute the whole history and the max-count only affects the output
7875 phase after ‘--graph’ does its computation".
7876
7877    In other words, it’s not that Git is slow at outputting the
7878 differences, or that Magit is slow at parsing the output - the problem
7879 is that Git first goes outside and has a smoke.
7880
7881    We actually work around this issue by limiting the number of commits
7882 not only by using ‘-<N>’ but by also using a range.  But unfortunately
7883 that’s not always possible.
7884
7885    In repositories with more than a few thousand commits ‘--graph’
7886 should never be a member of ‘magit-log-section-arguments’.  That
7887 variable is used in the status buffer which is refreshed every time you
7888 run any Magit command.
7889
7890    Using ‘--color --graph’ is even slower.  Magit uses code that is part
7891 of Emacs to turn control characters into faces.  That code is pretty
7892 slow and this is quite noticeable when showing a log with many branches
7893 and merges.  For that reason ‘--color’ is not enabled by default
7894 anymore.  Consider leaving it at that.
7895
7896 Diff Performance
7897 ................
7898
7899 If diffs are slow, then consider turning off some optional diff features
7900 by setting all or some of the following variables to ‘nil’:
7901 ‘magit-diff-highlight-indentation’, ‘magit-diff-highlight-trailing’,
7902 ‘magit-diff-paint-whitespace’, ‘magit-diff-highlight-hunk-body’, and
7903 ‘magit-diff-refine-hunk’.
7904
7905    When showing a commit instead of some arbitrary diff, then some
7906 additional information is displayed.  Calculating this information can
7907 be quite expensive given certain circumstances.  If looking at a commit
7908 using ‘magit-revision-mode’ takes considerably more time than looking at
7909 the same commit in ‘magit-diff-mode’, then consider setting
7910 ‘magit-revision-insert-related-refs’ to ‘nil’.
7911
7912 Refs Buffer Performance
7913 .......................
7914
7915 When refreshing the "references buffer" is slow, then that’s usually
7916 because several hundred refs are being displayed.  The best way to
7917 address that is to display fewer refs, obviously.
7918
7919    If you are not, or only mildly, interested in seeing the list of
7920 tags, then start by not displaying them:
7921
7922      (remove-hook 'magit-refs-sections-hook 'magit-insert-tags)
7923
7924    Then you should also make sure that the listed remote branches
7925 actually all exist.  You can do so by pruning branches which no longer
7926 exist using ‘f-pa’.
7927
7928 Committing Performance
7929 ......................
7930
7931 When you initiate a commit, then Magit by default automatically shows a
7932 diff of the changes you are about to commit.  For large commits this can
7933 take a long time, which is especially distracting when you are
7934 committing large amounts of generated data which you don’t actually
7935 intend to inspect before committing.  This behavior can be turned off
7936 using:
7937
7938      (remove-hook 'server-switch-hook 'magit-commit-diff)
7939
7940    Then you can type ‘C-c C-d’ to show the diff when you actually want
7941 to see it, but only then.  Alternatively you can leave the hook alone
7942 and just type ‘C-g’ in those cases when it takes too long to generate
7943 the diff.  If you do that, then you will end up with a broken diff
7944 buffer, but doing it this way has the advantage that you usually get to
7945 see the diff, which is useful because it increases the odds that you
7946 spot potential issues.
7947
7948 The Built-In VC Package
7949 .......................
7950
7951 Emacs comes with a version control interface called "VC", see *note
7952 (emacs)Version Control::.  It is enabled be default, and if you don’t
7953 use it in addition to Magit, then you should disable it to keep it from
7954 performing unnecessary work:
7955
7956      (setq vc-handled-backends nil)
7957
7958    You can also disable its use for Git but keep using it when using
7959 another version control system:
7960
7961      (setq vc-handled-backends (delq 'Git vc-handled-backends))
7962