Track generated *.texi again

The ecosystem isn't read; maybe in a few more years.

1 files changed, 11450 insertions, 0 deletions

diff --git a/docs/magit.texi b/docs/magit.texi
new file mode 100644
index 0000000..02f9e38
--- /dev/null
+++ b/docs/magit.texi
@@ -0,0 +1,11450 @@
+\input texinfo    @c -*- texinfo -*-
+@c %**start of header
+@setfilename magit.info
+@settitle Magit User Manual
+@documentencoding UTF-8
+@documentlanguage en
+@c %**end of header
+
+@copying
+@quotation
+Copyright (C) 2015-2024 Jonas Bernoulli <emacs.magit@@jonas.bernoulli.dev>
+
+You can redistribute this document and/or modify it under the terms
+of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This document is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
+General Public License for more details.
+
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Magit: (magit).       Using Git from Emacs with Magit.
+@end direntry
+
+@finalout
+@titlepage
+@title Magit User Manual
+@subtitle for version 4.0.0
+@author Jonas Bernoulli
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Magit User Manual
+
+Magit is an interface to the version control system Git, implemented
+as an Emacs package.  Magit aspires to be a complete Git porcelain.
+While we cannot (yet) claim that Magit wraps and improves upon each
+and every Git command, it is complete enough to allow even experienced
+Git users to perform almost all of their daily version control tasks
+directly from within Emacs.  While many fine Git clients exist, only
+Magit and Git itself deserve to be called porcelains.
+
+@noindent
+This manual is for Magit version 4.0.0.
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction::
+* Installation::
+* Getting Started::
+* Interface Concepts::
+* Inspecting::
+* Manipulating::
+* Transferring::
+* Miscellaneous::
+* Customizing::
+* Plumbing::
+* FAQ::
+* Debugging Tools::
+* Keystroke Index::
+* Function and Command Index::
+* Variable Index::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Installation
+
+* Installing from Melpa::
+* Installing from the Git Repository::
+* Post-Installation Tasks::
+
+Interface Concepts
+
+* Modes and Buffers::
+* Sections::
+* Transient Commands::
+* Transient Arguments and Buffer Variables::
+* Completion, Confirmation and the Selection: Completion Confirmation and the Selection. 
+* Mouse Support::
+* Running Git::
+
+Modes and Buffers
+
+* Switching Buffers::
+* Naming Buffers::
+* Quitting Windows::
+* Automatic Refreshing of Magit Buffers::
+* Automatic Saving of File-Visiting Buffers::
+* Automatic Reverting of File-Visiting Buffers::
+
+
+Sections
+
+* Section Movement::
+* Section Visibility::
+* Section Hooks::
+* Section Types and Values::
+* Section Options::
+
+
+Completion, Confirmation and the Selection
+
+* Action Confirmation::
+* Completion and Confirmation::
+* The Selection::
+* The hunk-internal region::
+* Support for Completion Frameworks::
+* Additional Completion Options::
+
+
+Running Git
+
+* Viewing Git Output::
+* Git Process Status::
+* Running Git Manually::
+* Git Executable::
+* Global Git Arguments::
+
+
+Inspecting
+
+* Status Buffer::
+* Repository List::
+* Logging::
+* Diffing::
+* Ediffing::
+* References Buffer::
+* Bisecting::
+* Visiting Files and Blobs::
+* Blaming::
+
+Status Buffer
+
+* Status Sections::
+* Status Header Sections::
+* Status Module Sections::
+* Status Options::
+
+
+Logging
+
+* Refreshing Logs::
+* Log Buffer::
+* Log Margin::
+* Select from Log::
+* Reflog::
+* Cherries::
+
+
+Diffing
+
+* Refreshing Diffs::
+* Commands Available in Diffs::
+* Diff Options::
+* Revision Buffer::
+
+
+References Buffer
+
+* References Sections::
+
+
+Visiting Files and Blobs
+
+* General-Purpose Visit Commands::
+* Visiting Files and Blobs from a Diff::
+
+
+Manipulating
+
+* Creating Repository::
+* Cloning Repository::
+* Staging and Unstaging::
+* Applying::
+* Committing::
+* Branching::
+* Merging::
+* Resolving Conflicts::
+* Rebasing::
+* Cherry Picking::
+* Resetting::
+* Stashing::
+
+Staging and Unstaging
+
+* Staging from File-Visiting Buffers::
+
+
+Committing
+
+* Initiating a Commit::
+* Editing Commit Messages::
+
+
+Branching
+
+* The Two Remotes::
+* Branch Commands::
+* Branch Git Variables::
+* Auxiliary Branch Commands::
+
+
+Rebasing
+
+* Editing Rebase Sequences::
+* Information About In-Progress Rebase::
+
+
+Cherry Picking
+
+* Reverting::
+
+
+Transferring
+
+* Remotes::
+* Fetching::
+* Pulling::
+* Pushing::
+* Plain Patches::
+* Maildir Patches::
+
+Remotes
+
+* Remote Commands::
+* Remote Git Variables::
+
+
+Miscellaneous
+
+* Tagging::
+* Notes::
+* Submodules::
+* Subtree::
+* Worktree::
+* Sparse checkouts::
+* Bundle::
+* Common Commands::
+* Wip Modes::
+* Commands for Buffers Visiting Files::
+* Minor Mode for Buffers Visiting Blobs::
+
+Submodules
+
+* Listing Submodules::
+* Submodule Transient::
+
+
+Wip Modes
+
+* Wip Graph::
+* Legacy Wip Modes::
+
+
+Customizing
+
+* Per-Repository Configuration::
+* Essential Settings::
+
+Essential Settings
+
+* Safety::
+* Performance::
+* Global Bindings::
+
+
+Plumbing
+
+* Calling Git::
+* Section Plumbing::
+* Refreshing Buffers::
+* Conventions::
+
+Calling Git
+
+* Getting a Value from Git::
+* Calling Git for Effect::
+
+
+Section Plumbing
+
+* Creating Sections::
+* Section Selection::
+* Matching Sections::
+
+
+Conventions
+
+* Theming Faces::
+
+
+FAQ
+
+* FAQ - How to @dots{}?::
+* FAQ - Issues and Errors::
+
+FAQ - How to @dots{}?
+
+* How to pronounce Magit?::
+* How to show git's output?::
+* How to install the gitman info manual?::
+* How to show diffs for gpg-encrypted files?::
+* How does branching and pushing work?::
+* Should I disable VC@?::
+
+
+FAQ - Issues and Errors
+
+* Magit is slow::
+* I changed several thousand files at once and now Magit is unusable::
+* I am having problems committing::
+* I am using MS Windows and cannot push with Magit::
+* I am using macOS and SOMETHING works in shell, but not in Magit: I am using macOS and SOMETHING works in shell but not in Magit. 
+* Expanding a file to show the diff causes it to disappear::
+* Point is wrong in the @code{COMMIT_EDITMSG} buffer::
+* The mode-line information isn't always up-to-date::
+* A branch and tag sharing the same name breaks SOMETHING::
+* My Git hooks work on the command-line but not inside Magit::
+* @code{git-commit-mode} isn't used when committing from the command-line::
+* Point ends up inside invisible text when jumping to a file-visiting buffer::
+* I am no longer able to save popup defaults::
+
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+Magit is an interface to the version control system Git, implemented
+as an Emacs package.  Magit aspires to be a complete Git porcelain.
+While we cannot (yet) claim that Magit wraps and improves upon each
+and every Git command, it is complete enough to allow even experienced
+Git users to perform almost all of their daily version control tasks
+directly from within Emacs.  While many fine Git clients exist, only
+Magit and Git itself deserve to be called porcelains.
+
+Staging and otherwise applying changes is one of the most important
+features in a Git porcelain and here Magit outshines anything else,
+including Git itself.  Git's own staging interface (@code{git add --patch})
+is so cumbersome that many users only use it in exceptional cases.
+In Magit staging a hunk or even just part of a hunk is as trivial as
+staging all changes made to a file.
+
+The most visible part of Magit's interface is the status buffer, which
+displays information about the current repository.  Its content is
+created by running several Git commands and making their output
+actionable.  Among other things, it displays information about the
+current branch, lists unpulled and unpushed changes and contains
+sections displaying the staged and unstaged changes.  That might sound
+noisy, but, since sections are collapsible, it's not.
+
+To stage or unstage a change one places the cursor on the change and
+then types @code{s} or @code{u}.  The change can be a file or a hunk, or when the
+region is active (i.e., when there is a selection) several files or
+hunks, or even just part of a hunk.  The change or changes that these
+commands - and many others - would act on are highlighted.
+
+Magit also implements several other "apply variants" in addition to
+staging and unstaging.  One can discard or reverse a change, or
+apply it to the working tree.  Git's own porcelain only supports this
+for staging and unstaging and you would have to do something like @code{git
+diff ... | ??? | git apply ...} to discard, revert, or apply a single
+hunk on the command line.  In fact that's exactly what Magit does
+internally (which is what lead to the term "apply variants").
+
+Magit isn't just for Git experts, but it does assume some prior
+experience with Git as well as Emacs.  That being said, many users
+have reported that using Magit was what finally taught them what Git
+is capable of and how to use it to its fullest.  Other users
+wished they had switched to Emacs sooner so that they would have
+gotten their hands on Magit earlier.
+
+While one has to know the basic features of Emacs to be able to make
+full use of Magit, acquiring just enough Emacs skills doesn't take
+long and is worth it, even for users who prefer other editors.  Vim
+users are advised to give @uref{https://github.com/emacs-evil/evil, Evil}, the "Extensible VI Layer for Emacs",
+and @uref{https://github.com/syl20bnr/spacemacs, Spacemacs}, an "Emacs starter-kit focused on Evil" a try.
+
+Magit provides a consistent and efficient Git porcelain.  After a
+short learning period, you will be able to perform most of your daily
+version control tasks faster than you would on the command line.  You
+will likely also start using features that seemed too daunting in the
+past.
+
+Magit fully embraces Git.  It exposes many advanced features using a
+simple but flexible interface instead of only wrapping the trivial
+ones like many GUI clients do.  Of course Magit supports logging,
+cloning, pushing, and other commands that usually don't fail in
+spectacular ways; but it also supports tasks that often cannot be
+completed in a single step.  Magit fully supports tasks such as
+merging, rebasing, cherry-picking, reverting, and blaming by not only
+providing a command to initiate these tasks but also by displaying
+context sensitive information along the way and providing commands
+that are useful for resolving conflicts and resuming the sequence
+after doing so.
+
+Magit wraps and in many cases improves upon at least the following Git
+porcelain commands: @code{add}, @code{am}, @code{bisect}, @code{blame}, @code{branch}, @code{checkout}, @code{cherry},
+@code{cherry-pick}, @code{clean}, @code{clone}, @code{commit}, @code{config}, @code{describe}, @code{diff}, @code{fetch},
+@code{format-patch}, @code{init}, @code{log}, @code{merge}, @code{merge-tree}, @code{mv}, @code{notes}, @code{pull}, @code{rebase},
+@code{reflog}, @code{remote}, @code{request-pull}, @code{reset}, @code{revert}, @code{rm}, @code{show}, @code{stash},
+@code{submodule}, @code{subtree}, @code{tag}, and @code{worktree.}  Many more Magit porcelain
+commands are implemented on top of Git plumbing commands.
+
+@node Installation
+@chapter Installation
+
+Magit can be installed using Emacs' package manager or manually from
+its development repository.
+
+@menu
+* Installing from Melpa::
+* Installing from the Git Repository::
+* Post-Installation Tasks::
+@end menu
+
+@node Installing from Melpa
+@section Installing from Melpa
+
+Magit is available from Melpa and Melpa-Stable.  If you haven't used
+Emacs' package manager before, then it is high time you familiarize
+yourself with it by reading the documentation in the Emacs manual, see
+@ref{Packages,,,emacs,}.  Then add one of the archives to
+@code{package-archives}:
+
+@itemize
+@item
+To use Melpa:
+@end itemize
+
+@lisp
+(require 'package)
+(add-to-list 'package-archives
+             '("melpa" . "https://melpa.org/packages/") t)
+@end lisp
+
+@itemize
+@item
+To use Melpa-Stable:
+@end itemize
+
+@lisp
+(require 'package)
+(add-to-list 'package-archives
+             '("melpa-stable" . "https://stable.melpa.org/packages/") t)
+@end lisp
+
+Once you have added your preferred archive, you need to update the
+local package list using:
+
+@example
+M-x package-refresh-contents RET
+@end example
+
+Once you have done that, you can install Magit and its dependencies
+using:
+
+@example
+M-x package-install RET magit RET
+@end example
+
+Now see @ref{Post-Installation Tasks}.
+
+@node Installing from the Git Repository
+@section Installing from the Git Repository
+
+Magit depends on the @code{compat}, @code{dash}, @code{transient} and @code{with-editor} libraries
+which are available from Melpa and Melpa-Stable.  Install them using
+@code{M-x package-install RET <package> RET}.  Of course you may also install
+them manually from their repository.
+
+Then clone the Magit repository:
+
+@example
+$ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit
+$ cd ~/.emacs.d/site-lisp/magit
+@end example
+
+Then compile the libraries and generate the info manuals:
+
+@example
+$ make
+@end example
+
+If you haven't installed @code{compat}, @code{dash}, @code{transient} and @code{with-editor} from
+Melpa or at @code{/path/to/magit/../<package>}, then you have to tell @code{make}
+where to find them.  To do so create the file @code{/path/to/magit/config.mk}
+with the following content before running @code{make}:
+
+@example
+LOAD_PATH  = -L ~/.emacs.d/site-lisp/magit/lisp
+LOAD_PATH += -L ~/.emacs.d/site-lisp/dash
+LOAD_PATH += -L ~/.emacs.d/site-lisp/transient/lisp
+LOAD_PATH += -L ~/.emacs.d/site-lisp/with-editor/lisp
+LOAD_PATH += -L ~/.emacs.d/site-lisp/compat
+@end example
+
+Finally add this to your init file:
+
+@lisp
+(add-to-list 'load-path "~/.emacs.d/site-lisp/magit/lisp")
+(require 'magit)
+
+(with-eval-after-load 'info
+  (info-initialize)
+  (add-to-list 'Info-directory-list
+               "~/.emacs.d/site-lisp/magit/Documentation/"))
+@end lisp
+
+Of course if you installed the dependencies manually as well, then
+you have to tell Emacs about them too, by prefixing the above with:
+
+@lisp
+(add-to-list 'load-path "~/.emacs.d/site-lisp/dash")
+(add-to-list 'load-path "~/.emacs.d/site-lisp/transient/lisp")
+(add-to-list 'load-path "~/.emacs.d/site-lisp/with-editor")
+@end lisp
+
+Note that you have to add the @code{lisp} subdirectory to the @code{load-path}, not
+the top-level of the repository, and that elements of @code{load-path} should
+not end with a slash, while those of @code{Info-directory-list} should.
+
+Instead of requiring the feature @code{magit}, you could load just the
+autoload definitions, by loading the file @code{magit-autoloads.el}.
+
+@lisp
+(load "/path/to/magit/lisp/magit-autoloads")
+@end lisp
+
+Instead of running Magit directly from the repository by adding that
+to the @code{load-path}, you might want to instead install it in some other
+directory using @code{sudo make install} and setting @code{load-path} accordingly.
+
+To update Magit use:
+
+@example
+$ git pull
+$ make
+@end example
+
+At times it might be necessary to run @code{make clean all} instead.
+
+To view all available targets use @code{make help}.
+
+Now see @ref{Post-Installation Tasks}.
+
+@node Post-Installation Tasks
+@section Post-Installation Tasks
+
+After installing Magit you should verify that you are indeed using the
+Magit, Git, and Emacs releases you think you are using.  It's best to
+restart Emacs before doing so, to make sure you are not using an
+outdated value for @code{load-path}.
+
+@example
+M-x magit-version RET
+@end example
+
+should display something like
+
+@example
+Magit 2.8.0, Git 2.10.2, Emacs 25.1.1, gnu/linux
+@end example
+
+Then you might also want to read about options that many users likely
+want to customize.  See @ref{Essential Settings}.
+
+To be able to follow cross references to Git manpages found in this
+manual, you might also have to manually install the @code{gitman} info manual,
+or advice @code{Info-follow-nearest-node} to instead open the actual manpage.
+See @ref{How to install the gitman info manual?}.
+
+If you are completely new to Magit then see @ref{Getting Started}.
+
+If you run into problems, then please see the @ref{FAQ}.  Also see the
+@ref{Debugging Tools}.
+
+And last but not least please consider making a donation, to ensure
+that I can keep working on Magit.  See @uref{https://magit.vc/donations}.
+for various donation options.
+
+@node Getting Started
+@chapter Getting Started
+
+This short tutorial describes the most essential features that many
+Magitians use on a daily basis.  It only scratches the surface but
+should be enough to get you started.
+
+IMPORTANT: It is safest if you clone some repository just for this
+tutorial.  Alternatively you can use an existing local repository, but
+if you do that, then you should commit all uncommitted changes before
+proceeding.
+
+Type @code{C-x g} to display information about the current Git repository in
+a dedicated buffer, called the status buffer.
+
+Most Magit commands are commonly invoked from the status buffer.  It
+can be considered the primary interface for interacting with Git using
+Magit.  Many other Magit buffers may exist at a given time, but they
+are often created from this buffer.
+
+Depending on what state your repository is in, this buffer may contain
+sections titled "Staged changes", "Unstaged changes", "Unmerged into
+origin/master", "Unpushed to origin/master", and many others.
+
+Since we are starting from a safe state, which you can easily return
+to (by doing a @code{git reset --hard PRE-MAGIT-STATE}), there currently are
+no staged or unstaged changes.  Edit some files and save the changes.
+Then go back to the status buffer, while at the same time refreshing
+it, by typing @code{C-x g}.  (When the status buffer, or any Magit buffer for
+that matter, is the current buffer, then you can also use just @code{g} to
+refresh it).
+
+Move between sections using @code{p} and @code{n}.  Note that the bodies of some
+sections are hidden.  Type @code{TAB} to expand or collapse the section at
+point.  You can also use @code{C-tab} to cycle the visibility of the current
+section and its children.  Move to a file section inside the section
+named "Unstaged changes" and type @code{s} to stage the changes you have made
+to that file.  That file now appears under "Staged changes".
+
+Magit can stage and unstage individual hunks, not just complete files.
+Move to the file you have just staged, expand it using @code{TAB}, move to
+one of the hunks using @code{n}, and unstage just that by typing @code{u}.  Note how
+the staging (@code{s}) and unstaging (@code{u}) commands operate on the change at
+point.  Many other commands behave the same way.
+
+You can also un-/stage just part of a hunk.  Inside the body of a hunk
+section (move there using @code{C-n}), set the mark using @code{C-SPC} and move down
+until some added and/or removed lines fall inside the region but not
+all of them.  Again type @code{s} to stage.
+
+It is also possible to un-/stage multiple files at once.  Move to a
+file section, type @code{C-SPC}, move to the next file using @code{n}, and then @code{s} to
+stage both files.  Note that both the mark and point have to be on the
+headings of sibling sections for this to work.  If the region looks
+like it does in other buffers, then it doesn't select Magit sections
+that can be acted on as a unit.
+
+And then of course you want to commit your changes.  Type @code{c}.  This
+shows the available commit commands and arguments in a buffer at the
+bottom of the frame.  Each command and argument is prefixed with the
+key that invokes/sets it.  Do not worry about this for now.  We want
+to create a "normal" commit, which is done by typing @code{c} again.
+
+Now two new buffers appear.  One is for writing the commit message,
+the other shows a diff with the changes that you are about to
+commit.  Write a message and then type @code{C-c C-c} to actually create
+the commit.
+
+You probably don't want to push the commit you just created because
+you just committed some random changes, but if that is not the case
+you could push it by typing @code{P} to show all the available push commands
+and arguments and then @code{p} to push to a branch with the same name as the
+local branch onto the remote configured as the push-remote.  (If the
+push-remote is not configured yet, then you would first be prompted
+for the remote to push to.)
+
+So far we have mentioned the commit and push menu commands.
+These are probably among the menus you will be using the most, but
+many others exist.  To show a menu that lists all other menus (as well
+as the various apply commands and some other essential commands), type
+@code{h}.  Try a few.  (Such menus are also called "transient prefix
+commands" or just "transients".)
+
+The key bindings in that menu correspond to the bindings in Magit
+buffers, including but not limited to the status buffer.  So you could
+type @code{h d} to bring up the diff menu, but once you remember that "d"
+stands for "diff", you would usually do so by just typing @code{d}.
+
+This "prefix of prefixes" is useful even once you have memorized all
+the bindings, as it can provide easy access to Magit commands from
+non-Magit buffers.  So, by default, it is globally bound to @code{C-x M-g}.
+
+A similar menu featuring (for the most part) commands that act on just
+the file being visited in the current buffer, is globally bound to @code{C-c
+M-g}.  That binding can also be used in buffers, which do not visit a
+file, but then only a subset of the commands is available.
+
+The global key bindings mentioned in the previous two paragraphs are
+quite inconvenient.  We recommend using @code{C-c g} and @code{C-c f} instead, but
+cannot use those key sequences by default because they are strictly
+reserved for bindings added by the user.  See @ref{Global Bindings}, if you
+want to explicitly opt-in to the recommended key bindings.
+
+Magit also provides context menus and other mouse commands, see @ref{Mouse Support}.
+
+It is not necessary that you do so now, but if you stick with Magit,
+then it is highly recommended that you read the next section too.
+
+@node Interface Concepts
+@chapter Interface Concepts
+
+@menu
+* Modes and Buffers::
+* Sections::
+* Transient Commands::
+* Transient Arguments and Buffer Variables::
+* Completion, Confirmation and the Selection: Completion Confirmation and the Selection. 
+* Mouse Support::
+* Running Git::
+@end menu
+
+@node Modes and Buffers
+@section Modes and Buffers
+
+Magit provides several major-modes.  For each of these modes there
+usually exists only one buffer per repository.  Separate modes and
+thus buffers exist for commits, diffs, logs, and some other things.
+
+Besides these special purpose buffers, there also exists an overview
+buffer, called the @strong{status buffer}.  It's usually from this buffer that
+the user invokes Git commands, or creates or visits other buffers.
+
+In this manual we often speak about "Magit buffers".  By that we mean
+buffers whose major-modes derive from @code{magit-mode}.
+
+@table @asis
+@item @kbd{M-x magit-toggle-buffer-lock}
+@findex magit-toggle-buffer-lock
+This command locks the current buffer to its value or if the buffer
+is already locked, then it unlocks it.
+
+Locking a buffer to its value prevents it from being reused to
+display another value.  The name of a locked buffer contains its
+value, which allows telling it apart from other locked buffers and
+the unlocked buffer.
+
+Not all Magit buffers can be locked to their values; for example, it
+wouldn't make sense to lock a status buffer.
+
+There can only be a single unlocked buffer using a certain
+major-mode per repository.  So when a buffer is being unlocked and
+another unlocked buffer already exists for that mode and repository,
+then the former buffer is instead deleted and the latter is
+displayed in its place.
+@end table
+
+@menu
+* Switching Buffers::
+* Naming Buffers::
+* Quitting Windows::
+* Automatic Refreshing of Magit Buffers::
+* Automatic Saving of File-Visiting Buffers::
+* Automatic Reverting of File-Visiting Buffers::
+@end menu
+
+@node Switching Buffers
+@subsection Switching Buffers
+
+@defun magit-display-buffer buffer &optional display-function
+This function is a wrapper around @code{display-buffer} and is used to
+display any Magit buffer.  It displays BUFFER in some window and,
+unlike @code{display-buffer}, also selects that window, provided
+@code{magit-display-buffer-noselect} is @code{nil}.  It also runs the hooks
+mentioned below.
+
+If optional DISPLAY-FUNCTION is non-nil, then that is used to
+display the buffer.  Usually that is @code{nil} and the function specified
+by @code{magit-display-buffer-function} is used.
+@end defun
+
+@defvar magit-display-buffer-noselect
+When this is non-nil, then @code{magit-display-buffer} only displays the
+buffer but forgoes also selecting the window.  This variable should
+not be set globally, it is only intended to be let-bound, by code
+that automatically updates "the other window".  This is used for
+example when the revision buffer is updated when you move inside the
+log buffer.
+@end defvar
+
+@defopt magit-display-buffer-function
+The function specified here is called by @code{magit-display-buffer} with
+one argument, a buffer, to actually display that buffer.  This
+function should call @code{display-buffer} with that buffer as first and a
+list of display actions as second argument.
+
+Magit provides several functions, listed below, that are suitable
+values for this option.  If you want to use different rules, then a
+good way of doing that is to start with a copy of one of these
+functions and then adjust it to your needs.
+
+Instead of using a wrapper around @code{display-buffer}, that function
+itself can be used here, in which case the display actions have to
+be specified by adding them to @code{display-buffer-alist} instead.
+
+To learn about display actions, see @ref{Choosing Window,,,elisp,}.
+@end defopt
+
+@defun magit-display-buffer-traditional buffer
+This function is the current default value of the option
+@code{magit-display-buffer-function}.  Before that option and this function
+were added, the behavior was hard-coded in many places all over the
+code base but now all the rules are contained in this one function
+(except for the "noselect" special case mentioned above).
+@end defun
+
+@defun magit-display-buffer-same-window-except-diff-v1
+This function displays most buffers in the currently selected
+window.  If a buffer's mode derives from @code{magit-diff-mode} or
+@code{magit-process-mode}, it is displayed in another window.
+@end defun
+
+@defun magit-display-buffer-fullframe-status-v1
+This function fills the entire frame when displaying a status
+buffer.  Otherwise, it behaves like
+@code{magit-display-buffer-traditional}.
+@end defun
+
+@defun magit-display-buffer-fullframe-status-topleft-v1
+This function fills the entire frame when displaying a status
+buffer.  It behaves like @code{magit-display-buffer-fullframe-status-v1}
+except that it displays buffers that derive from @code{magit-diff-mode}
+or @code{magit-process-mode} to the top or left of the current buffer
+rather than to the bottom or right.  As a result, Magit buffers tend
+to pop up on the same side as they would if
+@code{magit-display-buffer-traditional} were in use.
+@end defun
+
+@defun magit-display-buffer-fullcolumn-most-v1
+This function displays most buffers so that they fill the entire
+height of the frame.  However, the buffer is displayed in another
+window if (1) the buffer's mode derives from @code{magit-process-mode},
+or (2) the buffer's mode derives from @code{magit-diff-mode}, provided
+that the mode of the current buffer derives from @code{magit-log-mode} or
+@code{magit-cherry-mode}.
+@end defun
+
+@defopt magit-pre-display-buffer-hook
+This hook is run by @code{magit-display-buffer} before displaying the
+buffer.
+@end defopt
+
+@defun magit-save-window-configuration
+This function saves the current window configuration.  Later when
+the buffer is buried, it may be restored by
+@code{magit-restore-window-configuration}.
+@end defun
+
+@defopt magit-post-display-buffer-hook
+This hook is run by @code{magit-display-buffer} after displaying the
+buffer.
+@end defopt
+
+@defun magit-maybe-set-dedicated
+This function remembers if a new window had to be created to display
+the buffer, or whether an existing window was reused.  This
+information is later used by @code{magit-mode-quit-window}, to determine
+whether the window should be deleted when its last Magit buffer is
+buried.
+@end defun
+
+@node Naming Buffers
+@subsection Naming Buffers
+
+@defopt magit-generate-buffer-name-function
+The function used to generate the names of Magit buffers.
+
+Such a function should take the options @code{magit-uniquify-buffer-names}
+as well as @code{magit-buffer-name-format} into account.  If it doesn't,
+then should be clearly stated in the doc-string.  And if it supports
+%-sequences beyond those mentioned in the doc-string of the option
+@code{magit-buffer-name-format}, then its own doc-string should describe
+the additions.
+@end defopt
+
+@defun magit-generate-buffer-name-default-function mode
+This function returns a buffer name suitable for a buffer whose
+major-mode is MODE and which shows information about the repository
+in which @code{default-directory} is located.
+
+This function uses @code{magit-buffer-name-format} and supporting all of
+the %-sequences mentioned the documentation of that option.  It also
+respects the option @code{magit-uniquify-buffer-names}.
+@end defun
+
+@defopt magit-buffer-name-format
+The format string used to name Magit buffers.
+
+At least the following %-sequences are supported:
+
+@itemize
+@item
+@code{%m}
+
+The name of the major-mode, but with the @code{-mode} suffix removed.
+
+@item
+@code{%M}
+
+Like @code{%m} but abbreviate @code{magit-status-mode} as @code{magit}.
+
+@item
+@code{%v}
+
+The value the buffer is locked to, in parentheses, or an empty
+string if the buffer is not locked to a value.
+
+@item
+@code{%V}
+
+Like @code{%v}, but the string is prefixed with a space, unless it is an
+empty string.
+
+@item
+@code{%t}
+
+The top-level directory of the working tree of the repository, or
+if @code{magit-uniquify-buffer-names} is non-nil an abbreviation of that.
+
+@item
+@code{%x}
+
+If @code{magit-uniquify-buffer-names} is nil "*", otherwise the empty
+string.  Due to limitations of the @code{uniquify} package, buffer names
+must end with the path.
+@end itemize
+
+The value should always contain @code{%m} or @code{%M}, @code{%v} or @code{%V}, and @code{%t}.  If
+@code{magit-uniquify-buffer-names} is non-nil, then the value must end with
+@code{%t} or @code{%t%x}.  See issue #2841.
+@end defopt
+
+@defopt magit-uniquify-buffer-names
+This option controls whether the names of Magit buffers are
+uniquified.  If the names are not being uniquified, then they
+contain the full path of the top-level of the working tree of the
+corresponding repository.  If they are being uniquified, then they
+end with the basename of the top-level, or if that would conflict
+with the name used for other buffers, then the names of all these
+buffers are adjusted until they no longer conflict.
+
+This is done using the @code{uniquify} package; customize its options to
+control how buffer names are uniquified.
+@end defopt
+
+@node Quitting Windows
+@subsection Quitting Windows
+
+@table @asis
+@item @kbd{q} (@code{magit-mode-bury-buffer})
+@kindex q
+@findex magit-mode-bury-buffer
+This command buries or kills the current Magit buffer.  The function
+specified by option @code{magit-bury-buffer-function} is used to bury the
+buffer when called without a prefix argument or to kill it when
+called with a single prefix argument.
+
+When called with two or more prefix arguments then it always kills
+all Magit buffers, associated with the current project, including
+the current buffer.
+@end table
+
+@defopt magit-bury-buffer-function
+The function used to actually bury or kill the current buffer.
+
+@code{magit-mode-bury-buffer} calls this function with one argument.  If
+the argument is non-nil, then the function has to kill the current
+buffer.  Otherwise it has to bury it alive.  The default value
+currently is @code{magit-mode-quit-window}.
+@end defopt
+
+@defun magit-restore-window-configuration kill-buffer
+Bury or kill the current buffer using @code{quit-window}, which is called
+with KILL-BUFFER as first and the selected window as second
+argument.
+
+Then restore the window configuration that existed right before the
+current buffer was displayed in the selected frame.  Unfortunately
+that also means that point gets adjusted in all the buffers, which
+are being displayed in the selected frame.
+@end defun
+
+@defun magit-mode-quit-window kill-buffer
+Bury or kill the current buffer using @code{quit-window}, which is called
+with KILL-BUFFER as first and the selected window as second
+argument.
+
+Then, if the window was originally created to display a Magit buffer
+and the buried buffer was the last remaining Magit buffer that was
+ever displayed in the window, then that is deleted.
+@end defun
+
+@node Automatic Refreshing of Magit Buffers
+@subsection Automatic Refreshing of Magit Buffers
+
+After running a command which may change the state of the current
+repository, the current Magit buffer and the corresponding status
+buffer are refreshed. The status buffer can be automatically refreshed
+whenever a buffer is saved to a file inside the respective repository
+by adding a hook, like so:
+
+@lisp
+(with-eval-after-load 'magit-mode
+  (add-hook 'after-save-hook 'magit-after-save-refresh-status t))
+@end lisp
+
+Automatically refreshing Magit buffers ensures that the displayed
+information is up-to-date most of the time but can lead to a
+noticeable delay in big repositories.  Other Magit buffers are not
+refreshed to keep the delay to a minimum and also because doing so can
+sometimes be undesirable.
+
+Buffers can also be refreshed explicitly, which is useful in buffers
+that weren't current during the last refresh and after changes were
+made to the repository outside of Magit.
+
+@table @asis
+@item @kbd{g} (@code{magit-refresh})
+@kindex g
+@findex magit-refresh
+This command refreshes the current buffer if its major mode derives
+from @code{magit-mode} as well as the corresponding status buffer.
+
+If the option @code{magit-revert-buffers} calls for it, then it also
+reverts all unmodified buffers that visit files being tracked in the
+current repository.
+
+@item @kbd{G} (@code{magit-refresh-all})
+@kindex G
+@findex magit-refresh-all
+This command refreshes all Magit buffers belonging to the current
+repository and also reverts all unmodified buffers that visit files
+being tracked in the current repository.
+
+The file-visiting buffers are always reverted, even if
+@code{magit-revert-buffers} is nil.
+@end table
+
+@defopt magit-refresh-buffer-hook
+This hook is run in each Magit buffer that was refreshed during the
+current refresh - normally the current buffer and the status buffer.
+@end defopt
+
+@defopt magit-refresh-status-buffer
+When this option is non-nil, then the status buffer is automatically
+refreshed after running git for side-effects, in addition to the
+current Magit buffer, which is always refreshed automatically.
+
+Only set this to nil after exhausting all other options to improve
+performance.
+@end defopt
+
+@defun magit-after-save-refresh-status
+This function is intended to be added to @code{after-save-hook}.  After
+doing that the corresponding status buffer is refreshed whenever a
+buffer is saved to a file inside a repository.
+
+Note that refreshing a Magit buffer is done by re-creating its
+contents from scratch, which can be slow in large repositories.  If
+you are not satisfied with Magit's performance, then you should
+obviously not add this function to that hook.
+@end defun
+
+@node Automatic Saving of File-Visiting Buffers
+@subsection Automatic Saving of File-Visiting Buffers
+
+File-visiting buffers are by default saved at certain points in time.
+This doesn't guarantee that Magit buffers are always up-to-date, but,
+provided one only edits files by editing them in Emacs and uses only
+Magit to interact with Git, one can be fairly confident.  When in
+doubt or after outside changes, type @code{g} (@code{magit-refresh}) to save and
+refresh explicitly.
+
+@defopt magit-save-repository-buffers
+This option controls whether file-visiting buffers are saved before
+certain events.
+
+If this is non-nil then all modified file-visiting buffers belonging
+to the current repository may be saved before running commands,
+before creating new Magit buffers, and before explicitly refreshing
+such buffers.  If this is @code{dontask} then this is done without user
+intervention.  If it is @code{t} then the user has to confirm each save.
+@end defopt
+
+@node Automatic Reverting of File-Visiting Buffers
+@subsection Automatic Reverting of File-Visiting Buffers
+
+By default Magit automatically reverts buffers that are visiting files
+that are being tracked in a Git repository, after they have changed on
+disk.  When using Magit one often changes files on disk by running
+Git, i.e., "outside Emacs", making this a rather important feature.
+
+For example, if you discard a change in the status buffer, then that
+is done by running @code{git apply --reverse ...}, and Emacs considers the
+file to have "changed on disk".  If Magit did not automatically revert
+the buffer, then you would have to type @code{M-x revert-buffer RET RET} in
+the visiting buffer before you could continue making changes.
+
+@defopt magit-auto-revert-mode
+When this mode is enabled, then buffers that visit tracked files
+are automatically reverted after the visited files change on disk.
+@end defopt
+
+@defopt global-auto-revert-mode
+When this mode is enabled, then any file-visiting buffer is
+automatically reverted after the visited file changes on disk.
+
+If you like buffers that visit tracked files to be automatically
+reverted, then you might also like any buffer to be reverted, not
+just those visiting tracked files.  If that is the case, then enable
+this mode @emph{instead of} @code{magit-auto-revert-mode}.
+@end defopt
+
+@defopt magit-auto-revert-immediately
+This option controls whether Magit reverts buffers immediately.
+
+If this is non-nil and either @code{global-auto-revert-mode} or
+@code{magit-auto-revert-mode} is enabled, then Magit immediately reverts
+buffers by explicitly calling @code{auto-revert-buffers} after running Git
+for side-effects.
+
+If @code{auto-revert-use-notify} is non-nil (and file notifications are
+actually supported), then @code{magit-auto-revert-immediately} does not
+have to be non-nil, because the reverts happen immediately anyway.
+
+If @code{magit-auto-revert-immediately} and @code{auto-revert-use-notify} are both
+@code{nil}, then reverts happen after @code{auto-revert-interval} seconds of user
+inactivity.  That is not desirable.
+@end defopt
+
+@defopt auto-revert-use-notify
+This option controls whether file notification functions should be
+used.  Note that this variable unfortunately defaults to @code{t} even on
+systems on which file notifications cannot be used.
+@end defopt
+
+@defopt magit-auto-revert-tracked-only
+This option controls whether @code{magit-auto-revert-mode} only reverts
+tracked files or all files that are located inside Git repositories,
+including untracked files and files located inside Git's control
+directory.
+@end defopt
+
+@defopt auto-revert-mode
+The global mode @code{magit-auto-revert-mode} works by turning on this
+local mode in the appropriate buffers (but @code{global-auto-revert-mode}
+is implemented differently).  You can also turn it on or off
+manually, which might be necessary if Magit does not notice that a
+previously untracked file now is being tracked or vice-versa.
+@end defopt
+
+@defopt auto-revert-stop-on-user-input
+This option controls whether the arrival of user input suspends the
+automatic reverts for @code{auto-revert-interval} seconds.
+@end defopt
+
+@defopt auto-revert-interval
+This option controls how many seconds Emacs waits for before
+resuming suspended reverts.
+@end defopt
+
+@defopt auto-revert-buffer-list-filter
+This option specifies an additional filter used by
+@code{auto-revert-buffers} to determine whether a buffer should be reverted
+or not.
+
+This option is provided by Magit, which also advises
+@code{auto-revert-buffers} to respect it.  Magit users who do not turn on
+the local mode @code{auto-revert-mode} themselves, are best served by
+setting the value to @code{magit-auto-revert-repository-buffer-p}.
+
+However the default is nil, so as not to disturb users who do use the
+local mode directly.  If you experience delays when running Magit
+commands, then you should consider using one of the predicates
+provided by Magit - especially if you also use Tramp.
+
+Users who do turn on @code{auto-revert-mode} in buffers in which Magit
+doesn't do that for them, should likely not use any filter.  Users
+who turn on @code{global-auto-revert-mode}, do not have to worry about this
+option, because it is disregarded if the global mode is enabled.
+@end defopt
+
+@defopt auto-revert-verbose
+This option controls whether Emacs reports when a buffer has been
+reverted.
+@end defopt
+
+The options with the @code{auto-revert-} prefix are located in the Custom
+group named @code{auto-revert}.  The other, Magit-specific, options are
+located in the @code{magit} group.
+
+@menu
+* Risk of Reverting Automatically::
+@end menu
+
+@node Risk of Reverting Automatically
+@unnumberedsubsubsec Risk of Reverting Automatically
+
+For the vast majority of users, automatically reverting file-visiting
+buffers after they have changed on disk is harmless.
+
+If a buffer is modified (i.e., it contains changes that haven't been
+saved yet), then Emacs will refuse to automatically revert it.  If
+you save a previously modified buffer, then that results in what is
+seen by Git as an uncommitted change.  Git will then refuse to carry
+out any commands that would cause these changes to be lost.  In other
+words, if there is anything that could be lost, then either Git or
+Emacs will refuse to discard the changes.
+
+However, if you use file-visiting buffers as a sort of ad hoc
+"staging area", then the automatic reverts could potentially cause
+data loss.  So far I have heard from only one user who uses such a
+workflow.
+
+An example: You visit some file in a buffer, edit it, and save the
+changes.  Then, outside of Emacs (or at least not using Magit or by
+saving the buffer) you change the file on disk again.  At this point
+the buffer is the only place where the intermediate version still
+exists.  You have saved the changes to disk, but that has since been
+overwritten.  Meanwhile Emacs considers the buffer to be unmodified
+(because you have not made any changes to it since you last saved it
+to the visited file) and therefore would not object to it being
+automatically reverted.  At this point an Auto-Revert mode would kick
+in.  It would check whether the buffer is modified and since that is
+not the case it would revert it.  The intermediate version would be
+lost.  (Actually you could still get it back using the @code{undo} command.)
+
+If your workflow depends on Emacs preserving the intermediate version
+in the buffer, then you have to disable all Auto-Revert modes.  But
+please consider that such a workflow would be dangerous even without
+using an Auto-Revert mode, and should therefore be avoided.  If Emacs
+crashes or if you quit Emacs by mistake, then you would also lose the
+buffer content.  There would be no autosave file still containing the
+intermediate version (because that was deleted when you saved the
+buffer) and you would not be asked whether you want to save the buffer
+(because it isn't modified).
+
+@node Sections
+@section Sections
+
+Magit buffers are organized into nested sections, which can be
+collapsed and expanded, similar to how sections are handled in Org
+mode.  Each section also has a type, and some sections also have a
+value.  For each section type there can also be a local keymap, shared
+by all sections of that type.
+
+Taking advantage of the section value and type, many commands operate on
+the current section, or when the region is active and selects sections
+of the same type, all of the selected sections.  Commands that only
+make sense for a particular section type (as opposed to just behaving
+differently depending on the type) are usually bound in section type
+keymaps.
+
+@menu
+* Section Movement::
+* Section Visibility::
+* Section Hooks::
+* Section Types and Values::
+* Section Options::
+@end menu
+
+@node Section Movement
+@subsection Section Movement
+
+To move within a section use the usual keys (@code{C-p}, @code{C-n}, @code{C-b}, @code{C-f} etc),
+whose global bindings are not shadowed.  To move to another section use
+the following commands.
+
+@table @asis
+@item @kbd{p} (@code{magit-section-backward})
+@kindex p
+@findex magit-section-backward
+When not at the beginning of a section, then move to the beginning
+of the current section.  At the beginning of a section, instead move
+to the beginning of the previous visible section.
+
+@item @kbd{n} (@code{magit-section-forward})
+@kindex n
+@findex magit-section-forward
+Move to the beginning of the next visible section.
+
+@item @kbd{M-p} (@code{magit-section-backward-siblings})
+@kindex M-p
+@findex magit-section-backward-siblings
+Move to the beginning of the previous sibling section.  If there is
+no previous sibling section, then move to the parent section
+instead.
+
+@item @kbd{M-n} (@code{magit-section-forward-siblings})
+@kindex M-n
+@findex magit-section-forward-siblings
+Move to the beginning of the next sibling section.  If there is no
+next sibling section, then move to the parent section instead.
+
+@item @kbd{^} (@code{magit-section-up})
+@kindex ^
+@findex magit-section-up
+Move to the beginning of the parent of the current section.
+@end table
+
+The above commands all call the hook @code{magit-section-movement-hook}.
+Any of the functions listed below can be used as members of this hook.
+
+You might want to remove some of the functions that Magit adds using
+@code{add-hook}.  In doing so you have to make sure you do not attempt to
+remove function that haven't even been added yet, for example:
+
+@lisp
+(with-eval-after-load 'magit-diff
+  (remove-hook 'magit-section-movement-hook
+               'magit-hunk-set-window-start))
+@end lisp
+
+@defvar magit-section-movement-hook
+This hook is run by all of the above movement commands, after
+arriving at the destination.
+@end defvar
+
+@defun magit-hunk-set-window-start
+This hook function ensures that the beginning of the current section
+is visible, provided it is a @code{hunk} section.  Otherwise, it does
+nothing.
+
+Loading @code{magit-diff} adds this function to the hook.
+@end defun
+
+@defun magit-section-set-window-start
+This hook function ensures that the beginning of the current section
+is visible, regardless of the section's type.  If you add this to
+@code{magit-section-movement-hook}, then you must remove the hunk-only
+variant in turn.
+@end defun
+
+@defun magit-log-maybe-show-more-commits
+This hook function only has an effect in log buffers, and @code{point} is
+on the "show more" section.  If that is the case, then it doubles
+the number of commits that are being shown.
+
+Loading @code{magit-log} adds this function to the hook.
+@end defun
+
+@defun magit-log-maybe-update-revision-buffer
+When moving inside a log buffer, then this function updates the
+revision buffer, provided it is already being displayed in another
+window of the same frame.
+
+Loading @code{magit-log} adds this function to the hook.
+@end defun
+
+@defun magit-log-maybe-update-blob-buffer
+When moving inside a log buffer and another window of the same frame
+displays a blob buffer, then this function instead displays the blob
+buffer for the commit at point in that window.
+@end defun
+
+@defun magit-status-maybe-update-revision-buffer
+When moving inside a status buffer, then this function updates the
+revision buffer, provided it is already being displayed in another
+window of the same frame.
+@end defun
+
+@defun magit-status-maybe-update-stash-buffer
+When moving inside a status buffer, then this function updates the
+stash buffer, provided it is already being displayed in another
+window of the same frame.
+@end defun
+
+@defun magit-status-maybe-update-blob-buffer
+When moving inside a status buffer and another window of the same
+frame displays a blob buffer, then this function instead displays
+the blob buffer for the commit at point in that window.
+@end defun
+
+@defun magit-stashes-maybe-update-stash-buffer
+When moving inside a buffer listing stashes, then this function
+updates the stash buffer, provided it is already being displayed
+in another window of the same frame.
+@end defun
+
+@defopt magit-update-other-window-delay
+Delay before automatically updating the other window.
+
+When moving around in certain buffers, then certain other buffers,
+which are being displayed in another window, may optionally be
+updated to display information about the section at point.
+
+When holding down a key to move by more than just one section, then
+that would update that buffer for each section on the way.  To
+prevent that, updating the revision buffer is delayed, and this
+option controls for how long.  For optimal experience you might have
+to adjust this delay and/or the keyboard repeat rate and delay of
+your graphical environment or operating system.
+@end defopt
+
+@node Section Visibility
+@subsection Section Visibility
+
+Magit provides many commands for changing the visibility of sections,
+but all you need to get started are the next two.
+
+@table @asis
+@item @kbd{@key{TAB}} (@code{magit-section-toggle})
+@kindex TAB
+@findex magit-section-toggle
+Toggle the visibility of the body of the current section.
+
+@item @kbd{C-c @key{TAB}} (@code{magit-section-cycle})
+@itemx @kbd{C-<tab>} (@code{magit-section-cycle})
+@kindex C-c TAB
+@kindex C-<tab>
+@findex magit-section-cycle
+Cycle the visibility of current section and its children.
+
+If this command is invoked using @code{C-<tab>} and that is globally bound
+to @code{tab-next}, then this command pivots to behave like that command,
+and you must instead use @code{C-c TAB} to cycle section visibility.
+
+If you would like to keep using @code{C-<tab>} to cycle section visibility
+but also want to use @code{tab-bar-mode}, then you have to prevent that mode
+from using this key and instead bind another key to @code{tab-next}.  Because
+@code{tab-bar-mode} does not use a mode map but instead manipulates the
+global map, this involves advising @code{tab-bar--define-keys}.
+
+@item @kbd{M-<tab>} (@code{magit-section-cycle-diffs})
+@kindex M-<tab>
+@findex magit-section-cycle-diffs
+Cycle the visibility of diff-related sections in the current buffer.
+
+@item @kbd{S-<tab>} (@code{magit-section-cycle-global})
+@kindex S-<tab>
+@findex magit-section-cycle-global
+Cycle the visibility of all sections in the current buffer.
+
+@item @kbd{1} (@code{magit-section-show-level-1})
+@itemx @kbd{2} (@code{magit-section-show-level-2})
+@itemx @kbd{3} (@code{magit-section-show-level-3})
+@itemx @kbd{4} (@code{magit-section-show-level-4})
+@kindex 1
+@kindex 2
+@kindex 3
+@kindex 4
+@findex magit-section-show-level-1
+@findex magit-section-show-level-2
+@findex magit-section-show-level-3
+@findex magit-section-show-level-4
+Show sections surrounding the current section up to level N@.
+
+@item @kbd{M-1} (@code{magit-section-show-level-1-all})
+@itemx @kbd{M-2} (@code{magit-section-show-level-2-all})
+@itemx @kbd{M-3} (@code{magit-section-show-level-3-all})
+@itemx @kbd{M-4} (@code{magit-section-show-level-4-all})
+@kindex M-1
+@kindex M-2
+@kindex M-3
+@kindex M-4
+@findex magit-section-show-level-1-all
+@findex magit-section-show-level-2-all
+@findex magit-section-show-level-3-all
+@findex magit-section-show-level-4-all
+Show all sections up to level N@.
+@end table
+
+Some functions, which are used to implement the above commands, are
+also exposed as commands themselves.  By default no keys are bound to
+these commands, as they are generally perceived to be much less
+useful.  But your mileage may vary.
+
+@deffn Command magit-section-show
+Show the body of the current section.
+@end deffn
+
+@deffn Command magit-section-hide
+Hide the body of the current section.
+@end deffn
+
+@deffn Command magit-section-show-headings
+Recursively show headings of children of the current section.  Only
+show the headings.  Previously shown text-only bodies are hidden.
+@end deffn
+
+@deffn Command magit-section-show-children
+Recursively show the bodies of children of the current section.
+With a prefix argument show children down to the level of the
+current section, and hide deeper children.
+@end deffn
+
+@deffn Command magit-section-hide-children
+Recursively hide the bodies of children of the current section.
+@end deffn
+
+@deffn Command magit-section-toggle-children
+Toggle visibility of bodies of children of the current section.
+@end deffn
+
+When a buffer is first created then some sections are shown expanded
+while others are not.  This is hard coded.  When a buffer is refreshed
+then the previous visibility is preserved.  The initial visibility of
+certain sections can also be overwritten using the hook
+@code{magit-section-set-visibility-hook}.
+
+@defopt magit-section-initial-visibility-alist
+This options can be used to override the initial visibility of
+sections.  In the future it will also be used to define the
+defaults, but currently a section's default is still hardcoded.
+
+The value is an alist.  Each element maps a section type or lineage
+to the initial visibility state for such sections.  The state has to
+be one of @code{show} or @code{hide}, or a function that returns one of these
+symbols.  A function is called with the section as the only argument.
+
+Use the command @code{magit-describe-section-briefly} to determine a
+section's lineage or type.  The vector in the output is the section
+lineage and the type is the first element of that vector.  Wildcards
+can be used, see @code{magit-section-match}.
+@end defopt
+
+@defopt magit-section-cache-visibility
+This option controls for which sections the previous visibility
+state should be restored if a section disappears and later appears
+again.  The value is a boolean or a list of section types.  If t,
+then the visibility of all sections is cached.  Otherwise this is
+only done for sections whose type matches one of the listed types.
+
+This requires that the function @code{magit-section-cached-visibility} is
+a member of @code{magit-section-set-visibility-hook}.
+@end defopt
+
+@defvar magit-section-set-visibility-hook
+This hook is run when first creating a buffer and also when
+refreshing an existing buffer, and is used to determine the
+visibility of the section currently being inserted.
+
+Each function is called with one argument, the section being
+inserted.  It should return @code{hide} or @code{show}, or to leave the visibility
+undefined @code{nil}.  If no function decides on the visibility and the
+buffer is being refreshed, then the visibility is preserved; or if
+the buffer is being created, then the hard coded default is used.
+
+Usually this should only be used to set the initial visibility but
+not during refreshes.  If @code{magit-insert-section--oldroot} is non-nil,
+then the buffer is being refreshed and these functions should
+immediately return @code{nil}.
+@end defvar
+
+@defopt magit-section-visibility-indicator
+This option controls whether and how to indicate that a section can
+be expanded/collapsed.
+
+If nil, then no visibility indicators are shown.  Otherwise the
+value has to have one of these two forms:
+
+@itemize
+@item
+@code{(EXPANDABLE-BITMAP . COLLAPSIBLE-BITMAP)}
+
+Both values have to be variables whose values are fringe
+bitmaps.  In this case every section that can be expanded
+or collapsed gets an indicator in the left fringe.
+
+To provide extra padding around the indicator, set
+@code{left-fringe-width} in @code{magit-mode-hook}, e.g.:
+
+@lisp
+(add-hook 'magit-mode-hook (lambda ()
+                             (setq left-fringe-width 20)))
+@end lisp
+
+@item
+@code{(STRING . BOOLEAN)}
+
+In this case STRING (usually an ellipsis) is shown at the end
+of the heading of every collapsed section.  Expanded sections
+get no indicator.  The cdr controls whether the appearance of
+these ellipsis take section highlighting into account.  Doing
+so might potentially have an impact on performance, while not
+doing so is kinda ugly.
+@end itemize
+@end defopt
+
+@node Section Hooks
+@subsection Section Hooks
+
+Which sections are inserted into certain buffers is controlled with
+hooks.  This includes the status and the refs buffers.  For other
+buffers, e.g., log and diff buffers, this is not possible.  The
+command @code{magit-describe-section} can be used to see which hook (if any)
+was responsible for inserting the section at point.
+
+For buffers whose sections can be customized by the user, a hook
+variable called @code{magit-TYPE-sections-hook} exists.  This hook should be
+changed using @code{magit-add-section-hook}.  Avoid using @code{add-hooks} or the
+Custom interface.
+
+The various available section hook variables are described later in
+this manual along with the appropriate "section inserter functions".
+
+@defun magit-add-section-hook hook function &optional at append local
+Add the function FUNCTION to the value of section hook HOOK@.
+
+Add FUNCTION at the beginning of the hook list unless optional
+APPEND is non-nil, in which case FUNCTION is added at the end.  If
+FUNCTION already is a member then move it to the new location.
+
+If optional AT is non-nil and a member of the hook list, then add
+FUNCTION next to that instead.  Add before or after AT, or replace
+AT with FUNCTION depending on APPEND@.  If APPEND is the symbol
+@code{replace}, then replace AT with FUNCTION@.  For any other non-nil value
+place FUNCTION right after AT@.  If nil, then place FUNCTION right
+before AT@.  If FUNCTION already is a member of the list but AT is
+not, then leave FUNCTION where ever it already is.
+
+If optional LOCAL is non-nil, then modify the hook's buffer-local
+value rather than its global value.  This makes the hook local by
+copying the default value.  That copy is then modified.
+
+HOOK should be a symbol.  If HOOK is void, it is first set to nil.
+HOOK's value must not be a single hook function.  FUNCTION should
+be a function that takes no arguments and inserts one or multiple
+sections at point, moving point forward.  FUNCTION may choose not
+to insert its section(s), when doing so would not make sense.  It
+should not be abused for other side-effects.
+@end defun
+
+To remove a function from a section hook, use @code{remove-hook}.
+
+@node Section Types and Values
+@subsection Section Types and Values
+
+Each section has a type, for example @code{hunk}, @code{file}, and @code{commit}.
+Instances of certain section types also have a value.  The value of a
+section of type @code{file}, for example, is a file name.
+
+Users usually do not have to worry about a section's type and value,
+but knowing them can be handy at times.
+
+@table @asis
+@item @kbd{H} (@code{magit-describe-section})
+@kindex H
+@findex magit-describe-section
+This command shows information about the section at point in a
+separate buffer.
+@end table
+
+@deffn Command magit-describe-section-briefly
+This command shows information about the section at point in the
+echo area, as @code{#<magit-section VALUE [TYPE PARENT-TYPE...]
+  BEGINNING-END>}.
+@end deffn
+
+Many commands behave differently depending on the type of the section
+at point and/or somehow consume the value of that section.  But that
+is only one of the reasons why the same key may do something different,
+depending on what section is current.
+
+Additionally for each section type a keymap @strong{might} be defined, named
+@code{magit-TYPE-section-map}.  That keymap is used as text property keymap
+of all text belonging to any section of the respective type.  If such
+a map does not exist for a certain type, then you can define it
+yourself, and it will automatically be used.
+
+@node Section Options
+@subsection Section Options
+
+This section describes options that have an effect on more than just a
+certain type of sections.  As you can see there are not many of those.
+
+@defopt magit-section-show-child-count
+Whether to append the number of children to section headings.  This
+only affects sections that could benefit from this information.
+@end defopt
+
+@node Transient Commands
+@section Transient Commands
+
+Many Magit commands are implemented as @strong{transient} commands.  First the
+user invokes a @strong{prefix} command, which causes its @strong{infix} arguments and
+@strong{suffix} commands to be displayed in the echo area.  The user then
+optionally sets some infix arguments and finally invokes one of the
+suffix commands.
+
+This is implemented in the library @code{transient}.  Earlier Magit releases
+used the package @code{magit-popup} and even earlier versions library
+@code{magit-key-mode}.
+
+Transient is documented in @ref{Top,,,transient,}.
+
+@table @asis
+@item @kbd{C-x M-g} (@code{magit-dispatch})
+@itemx @kbd{C-c g} (@code{magit-dispatch})
+@kindex C-x M-g
+@kindex C-c g
+@findex magit-dispatch
+This transient prefix command binds most of Magit's other prefix
+commands as suffix commands and displays them in a temporary buffer
+until one of them is invoked.  Invoking such a sub-prefix causes the
+suffixes of that command to be bound and displayed instead of those
+of @code{magit-dispatch}.
+
+This command is also, or especially, useful outside Magit buffers,
+so Magit by default binds it to @code{C-c M-g} in the global keymap.
+@code{C-c g} would be a better binding, but we cannot use that by default,
+because that key sequence is reserved for the user.  See @ref{Global Bindings} to learn more default and recommended key bindings.
+@end table
+
+@node Transient Arguments and Buffer Variables
+@section Transient Arguments and Buffer Variables
+
+The infix arguments of many of Magit's transient prefix commands cease
+to have an effect once the @code{git} command that is called with those
+arguments has returned.  Commands that create a commit are a good
+example for this.  If the user changes the arguments, then that only
+affects the next invocation of a suffix command.  If the same
+transient prefix command is later invoked again, then the arguments
+are initially reset to the default value.  This default value can be
+set for the current Emacs session or saved permanently, see
+@ref{Saving Values,,,transient,}.  It is also possible to cycle through
+previously used sets of arguments using @code{C-M-p} and @code{C-M-n}, see
+@ref{Using History,,,transient,}.
+
+However the infix arguments of many other transient commands continue
+to have an effect even after the @code{git} command that was called with
+those arguments has returned.  The most important commands like this
+are those that display a diff or log in a dedicated buffer.  Their
+arguments obviously continue to have an effect for as long as the
+respective diff or log is being displayed.  Furthermore the used
+arguments are stored in buffer-local variables for future reference.
+
+For commands in the second group it isn't always desirable to reset
+their arguments to the global value when the transient prefix command
+is invoked again.
+
+As mentioned above, it is possible to cycle through previously used
+sets of arguments while a transient popup is visible.  That means that
+we could always reset the infix arguments to the default because the
+set of arguments that is active in the existing buffer is only a few
+@code{C-M-p} away.  Magit can be configured to behave like that, but because I
+expect that most users would not find that very convenient, it is not
+the default.
+
+Also note that it is possible to change the diff and log arguments
+used in the current buffer (including the status buffer, which
+contains both diff and log sections) using the respective "refresh"
+transient prefix commands on @code{D} and @code{L}.  (@code{d} and @code{l} on the other hand are
+intended to change @strong{what} diff or log is being displayed.  It is
+possible to also change @strong{how} the diff or log is being displayed at the
+same time, but if you only want to do the latter, then you should use
+the refresh variants.)  Because these secondary diff and log transient
+prefixes are about @strong{changing} the arguments used in the current buffer,
+they @strong{always} start out with the set of arguments that are currently in
+effect in that buffer.
+
+Some commands are usually invoked directly even though they can also
+be invoked as the suffix of a transient prefix command.  Most
+prominently @code{magit-show-commit} is usually invoked by typing @code{RET} while
+point is on a commit in a log, but it can also be invoked from the
+@code{magit-diff} transient prefix.
+
+When such a command is invoked directly, then it is important to reuse
+the arguments as specified by the respective buffer-local values,
+instead of using the default arguments.  Imagine you press @code{RET} in a
+log to display the commit at point in a different buffer and then use
+@code{D} to change how the diff is displayed in that buffer.  And then you
+press @code{RET} on another commit to show that instead and the diff
+arguments are reset to the default.  Not cool; so Magit does not do
+that by default.
+
+@defopt magit-prefix-use-buffer-arguments
+This option controls whether the infix arguments initially shown in
+certain transient prefix commands are based on the arguments that
+are currently in effect in the buffer that their suffixes update.
+
+The @code{magit-diff} and @code{magit-log} transient prefix commands are affected
+by this option.
+@end defopt
+
+@defopt magit-direct-use-buffer-arguments
+This option controls whether certain commands, when invoked directly
+(i.e., not as the suffix of a transient prefix command), use the
+arguments that are currently active in the buffer that they are
+about to update.  The alternative is to use the default value for
+these arguments, which might change the arguments that are used in
+the buffer.
+@end defopt
+
+@noindent
+Valid values for both of the above options are:
+
+@itemize
+@item
+@code{always}: Always use the set of arguments that is currently active
+in the respective buffer, provided that buffer exists of course.
+@item
+@code{selected} or @code{t}: Use the set of arguments from the respective
+buffer, but only if it is displayed in a window of the current
+frame.  This is the default for both variables.
+@item
+@code{current}: Use the set of arguments from the respective buffer, but
+only if it is the current buffer.
+@item
+@code{never}: Never use the set of arguments from the respective buffer.
+@end itemize
+
+@noindent
+I am afraid it gets more complicated still:
+
+@itemize
+@item
+The global diff and log arguments are set for each supported mode
+individually.  The diff arguments for example have different values
+in @code{magit-diff-mode}, @code{magit-revision-mode}, @code{magit-merge-preview-mode}
+and @code{magit-status-mode} buffers.  Setting or saving the value for one
+mode does not change the value for other modes.  The history however
+is shared.
+
+@item
+When @code{magit-show-commit} is invoked directly from a log buffer, then
+the file filter is picked up from that buffer, not from the revision
+buffer or the mode's global diff arguments.
+
+@item
+Even though they are suffixes of the diff prefix @code{magit-show-commit}
+and @code{magit-stash-show} do not use the diff buffer used by the diff
+commands, instead they use the dedicated revision and stash buffers.
+
+At the time you invoke the diff prefix it is unknown to Magit which
+of the suffix commands you are going to invoke.  While not certain,
+more often than not users invoke one of the commands that use the
+diff buffer, so the initial infix arguments are those used in that
+buffer.  However if you invoke one of these commands directly, then
+Magit knows that it should use the arguments from the revision resp.
+stash buffer.
+
+@item
+The log prefix also features reflog commands, but these commands do
+not use the log arguments.
+
+@item
+If @code{magit-show-refs} is invoked from a @code{magit-refs-mode} buffer, then it
+acts as a refresh prefix and therefore unconditionally uses the
+buffer's arguments as initial arguments. If it is invoked elsewhere
+with a prefix argument, then it acts as regular prefix and therefore
+respects @code{magit-prefix-use-buffer-arguments}.  If it is invoked
+elsewhere without a prefix argument, then it acts as a direct
+command and therefore respects @code{magit-direct-use-buffer-arguments}.
+@end itemize
+
+@node Completion Confirmation and the Selection
+@section Completion, Confirmation and the Selection
+
+@menu
+* Action Confirmation::
+* Completion and Confirmation::
+* The Selection::
+* The hunk-internal region::
+* Support for Completion Frameworks::
+* Additional Completion Options::
+@end menu
+
+@node Action Confirmation
+@subsection Action Confirmation
+
+By default many actions that could potentially lead to data loss have
+to be confirmed.  This includes many very common actions, so this can
+quickly become annoying.  Many of these actions can be undone and if
+you have thought about how to undo certain mistakes, then it should
+be safe to disable confirmation for the respective actions.
+
+The option @code{magit-no-confirm} can be used to tell Magit to perform
+certain actions without the user having to confirm them.  Note that
+while this option can only be used to disable confirmation for a
+specific set of actions, the next section explains another way of
+telling Magit to ask fewer questions.
+
+@defopt magit-no-confirm
+The value of this option is a list of symbols, representing actions
+that do not have to be confirmed by the user before being carried
+out.
+
+By default many potentially dangerous commands ask the user for
+confirmation.  Each of the below symbols stands for an action which,
+when invoked unintentionally or without being fully aware of the
+consequences, could lead to tears.  In many cases there are several
+commands that perform variations of a certain action, so we don't
+use the command names but more generic symbols.
+
+@itemize
+@item
+Applying changes:
+
+@itemize
+@item
+@code{discard} Discarding one or more changes (i.e., hunks or the
+complete diff for a file) loses that change, obviously.
+
+@item
+@code{reverse} Reverting one or more changes can usually be undone by
+reverting the reversion.
+
+@item
+@code{stage-all-changes}, @code{unstage-all-changes} When there are both
+staged and unstaged changes, then un-/staging everything would
+destroy that distinction.  Of course that also applies when
+un-/staging a single change, but then less is lost and one does
+that so often that having to confirm every time would be
+unacceptable.
+@end itemize
+
+@item
+Files:
+
+@itemize
+@item
+@code{delete} When a file that isn't yet tracked by Git is deleted,
+then it is completely lost, not just the last changes.  Very
+dangerous.
+
+@item
+@code{trash} Instead of deleting a file it can also be move to the
+system trash.  Obviously much less dangerous than deleting it.
+
+Also see option @code{magit-delete-by-moving-to-trash}.
+
+@item
+@code{resurrect} A deleted file can easily be resurrected by "deleting"
+the deletion, which is done using the same command that was used
+to delete the same file in the first place.
+
+@item
+@code{untrack} Untracking a file can be undone by tracking it again.
+
+@item
+@code{rename} Renaming a file can easily be undone.
+@end itemize
+
+@item
+Sequences:
+
+@itemize
+@item
+@code{reset-bisect} Aborting (known to Git as "resetting") a bisect
+operation loses all information collected so far.
+
+@item
+@code{abort-cherry-pick} Aborting a cherry-pick throws away all
+conflict resolutions which have already been carried out by the
+user.
+
+@item
+@code{abort-revert} Aborting a revert throws away all conflict
+resolutions which have already been carried out by the user.
+
+@item
+@code{abort-rebase} Aborting a rebase throws away all already modified
+commits, but it's possible to restore those from the reflog.
+
+@item
+@code{abort-merge} Aborting a merge throws away all conflict
+resolutions which have already been carried out by the user.
+
+@item
+@code{merge-dirty} Merging with a dirty worktree can make it hard to go
+back to the state before the merge was initiated.
+@end itemize
+
+@item
+References:
+
+@itemize
+@item
+@code{delete-unmerged-branch} Once a branch has been deleted, it can
+only be restored using low-level recovery tools provided by Git.
+And even then the reflog is gone.  The user always has to
+confirm the deletion of a branch by accepting the default choice
+(or selecting another branch), but when a branch has not been
+merged yet, also make sure the user is aware of that.
+
+@item
+@code{delete-pr-remote} When deleting a branch that was created from a
+pull-request and if no other branches still exist on that
+remote, then @code{magit-branch-delete} offers to delete the remote
+as well.  This should be safe because it only happens if no
+other refs exist in the remotes namespace, and you can recreate
+the remote if necessary.
+
+@item
+@code{drop-stashes} Dropping a stash is dangerous because Git stores
+stashes in the reflog.  Once a stash is removed, there is no
+going back without using low-level recovery tools provided by
+Git.  When a single stash is dropped, then the user always has
+to confirm by accepting the default (or selecting another).
+This action only concerns the deletion of multiple stashes at
+once.
+@end itemize
+
+@item
+Publishing:
+
+@itemize
+@item
+@code{set-and-push} When pushing to the upstream or the push-remote
+and that isn't actually configured yet, then the user can first
+set the target.  If s/he confirms the default too quickly, then
+s/he might end up pushing to the wrong branch and if the remote
+repository is configured to disallow fixing such mistakes, then
+that can be quite embarrassing and annoying.
+@end itemize
+
+@item
+Edit published history:
+
+Without adding these symbols here, you will be warned before
+editing commits that have already been pushed to one of the
+branches listed in @code{magit-published-branches}.
+
+@itemize
+@item
+@code{amend-published} Affects most commands that amend to "HEAD".
+
+@item
+@code{rebase-published} Affects commands that perform interactive
+rebases.  This includes commands from the commit transient that
+modify a commit other than "HEAD", namely the various fixup and
+squash variants.
+
+@item
+@code{edit-published} Affects the commands @code{magit-edit-line-commit} and
+@code{magit-diff-edit-hunk-commit}.  These two commands make it quite
+easy to accidentally edit a published commit, so you should
+think twice before configuring them not to ask for confirmation.
+@end itemize
+
+To disable confirmation completely, add all three symbols here or
+set @code{magit-published-branches} to @code{nil}.
+
+@item
+Various:
+
+@itemize
+@item
+@code{stash-apply-3way} When a stash cannot be applied using @code{git stash
+      apply}, then Magit uses @code{git apply} instead, possibly using the
+@code{--3way} argument, which isn't always perfectly safe.  See also
+@code{magit-stash-apply}.
+
+@item
+@code{kill-process} There seldom is a reason to kill a process.
+@end itemize
+
+@item
+Global settings:
+
+Instead of adding all of the above symbols to the value of this
+option, you can also set it to the atom `t', which has the same
+effect as adding all of the above symbols.  Doing that most
+certainly is a bad idea, especially because other symbols might be
+added in the future.  So even if you don't want to be asked for
+confirmation for any of these actions, you are still better of
+adding all of the respective symbols individually.
+
+When @code{magit-wip-before-change-mode} is enabled, then the following
+actions can be undone fairly easily: @code{discard}, @code{reverse},
+@code{stage-all-changes}, and @code{unstage-all-changes}.  If and only if
+this mode is enabled, then @code{safe-with-wip} has the same effect as
+adding all of these symbols individually.
+@end itemize
+@end defopt
+
+@node Completion and Confirmation
+@subsection Completion and Confirmation
+
+Many Magit commands ask the user to select from a list of possible
+things to act on, while offering the most likely choice as the
+default.  For many of these commands the default is the thing at
+point, provided that it actually is a valid thing to act on.  For
+many commands that act on a branch, the current branch serves as
+the default if there is no branch at point.
+
+These commands combine asking for confirmation and asking for a target
+to act on into a single action.  The user can confirm the default
+target using @code{RET} or abort using @code{C-g}.  This is similar to a @code{y-or-n-p}
+prompt, but the keys to confirm or abort differ.
+
+At the same time the user is also given the opportunity to select
+another target, which is useful because for some commands and/or in
+some situations you might want to select the action before selecting
+the target by moving to it.
+
+However you might find that for some commands you always want to use
+the default target, if any, or even that you want the command to act
+on the default without requiring any confirmation at all.  The option
+@code{magit-dwim-selection} can be used to configure certain commands to that
+effect.
+
+Note that when the region is active then many commands act on the
+things that are selected using a mechanism based on the region, in
+many cases after asking for confirmation.  This region-based mechanism
+is called the "selection" and is described in detail in the next
+section.  When a selection exists that is valid for the invoked
+command, then that command never offers to act on something else, and
+whether it asks for confirmation is not controlled by this option.
+
+Also note that Magit asks for confirmation of certain actions that are
+not coupled with completion (or the selection).  Such dialogs are also
+not affected by this option and are described in the previous section.
+
+@defopt magit-dwim-selection
+@end defopt
+This option can be used to tell certain commands to use the thing
+at point instead of asking the user to select a candidate to act
+on, with or without confirmation.
+
+The value has the form @code{((COMMAND nil|PROMPT DEFAULT)...)}.
+
+@itemize
+@item
+COMMAND is the command that should not prompt for a choice.
+To have an effect, the command has to use the function
+@code{magit-completing-read} or a utility function which in turn uses
+that function.
+
+@item
+If the command uses @code{magit-completing-read} multiple times, then
+PROMPT can be used to only affect one of these uses.  PROMPT, if
+non-nil, is a regular expression that is used to match against
+the PROMPT argument passed to @code{magit-completing-read}.
+
+@item
+DEFAULT specifies how to use the default.  If it is @code{t}, then
+the DEFAULT argument passed to @code{magit-completing-read} is used
+without confirmation.  If it is @code{ask}, then the user is given
+a chance to abort.  DEFAULT can also be @code{nil}, in which case the
+entry has no effect.
+@end itemize
+
+@node The Selection
+@subsection The Selection
+
+If the region is active, then many Magit commands act on the things
+that are selected using a mechanism based on the region instead of one
+single thing.  When the region is not active, then these commands act
+on the thing at point or read a single thing to act on.  This is
+described in the previous section — this section only covers how
+multiple things are selected, how that is visualized, and how certain
+commands behave when that is the case.
+
+Magit's mechanism for selecting multiple things, or rather sections
+that represent these things, is based on the Emacs region, but the
+area that Magit considers to be selected is typically larger than the
+region and additional restrictions apply.
+
+Magit makes a distinction between a region that qualifies as forming a
+valid Magit selection and a region that does not.  If the region does
+not qualify, then it is displayed as it is in other Emacs buffers.  If
+the region does qualify as a Magit selection, then the selection is
+always visualized, while the region itself is only visualized if it
+begins and ends on the same line.
+
+For a region to qualify as a Magit selection, it must begin in the
+heading of one section and end in the heading of a sibling section.
+Note that if the end of the region is at the very beginning of section
+heading (i.e., at the very beginning of a line) then that section is
+considered to be @strong{inside} the selection.
+
+This is not consistent with how the region is normally treated in
+Emacs — if the region ends at the beginning of a line, then that line
+is outside the region.  Due to how Magit visualizes the selection, it
+should be obvious that this difference exists.
+
+Not every command acts on every valid selection.  Some commands do not
+even consider the location of point, others may act on the section at
+point but not support acting on the selection, and even commands that
+do support the selection of course only do so if it selects things
+that they can act on.
+
+This is the main reason why the selection must include the section at
+point.  Even if a selection exists, the invoked command may disregard
+it, in which case it may act on the current section only.  It is much
+safer to only act on the current section but not the other selected
+sections than it is to act on the current section @strong{instead} of the
+selected sections.  The latter would be much more surprising and if
+the current section always is part of the selection, then that cannot
+happen.
+
+@defvar magit-keep-region-overlay
+This variable controls whether the region is visualized as usual
+even when a valid Magit selection or a hunk-internal region exists.
+See the doc-string for more information.
+@end defvar
+
+@node The hunk-internal region
+@subsection The hunk-internal region
+
+Somewhat related to the Magit selection described in the previous
+section is the hunk-internal region.
+
+Like the selection, the hunk-internal region is based on the Emacs
+region but causes that region to not be visualized as it would in
+other Emacs buffers, and includes the line on which the region ends
+even if it ends at the very beginning of that line.
+
+Unlike the selection, which is based on a region that must begin in
+the heading of one section and ends in the section of a sibling
+section, the hunk-internal region must begin inside the @strong{body} of a
+hunk section and end in the body of the @strong{same} section.
+
+The hunk-internal region is honored by "apply" commands, which can,
+among other targets, act on a hunk.  If the hunk-internal region is
+active, then such commands act only on the marked part of the hunk
+instead of on the complete hunk.
+
+@node Support for Completion Frameworks
+@subsection Support for Completion Frameworks
+
+The built-in option @code{completing-read-function} specifies the low-level
+function used by @code{completing-read} to ask a user to select from a list
+of choices.  Its default value is @code{completing-read-default}.
+Alternative completion frameworks typically activate themselves by
+substituting their own implementation.
+
+Mostly for historic reasons Magit provides a similar option named
+@code{magit-completing-read-function}, which only controls the low-level
+function used by @code{magit-completing-read}.  This option also makes it
+possible to use a different completing mechanism for Magit than for
+the rest of Emacs, but doing that is not recommend.
+
+You most likely don't have to customize the magit-specific option to
+use an alternative completion framework.  For example, if you enable
+@code{ivy-mode}, then Magit will respect that, and if you enable @code{helm-mode},
+then you are done too.
+
+However if you want to use Ido, then @code{ido-mode} won't do the trick.  You
+will also have to install the @code{ido-completing-read+} package and use
+@code{magit-ido-completing-read} as @code{magit-completing-read-function}.
+
+@defopt magit-completing-read-function
+The value of this variable is the low-level function used to perform
+completion by code that uses @code{magit-completing-read} (as opposed to
+the built-in @code{completing-read}).
+
+The default value, @code{magit-builtin-completing-read}, is suitable for
+the standard completion mechanism, @code{ivy-mode}, and @code{helm-mode} at least.
+
+The built-in @code{completing-read} and @code{completing-read-default} are @strong{not}
+suitable to be used here.  @code{magit-builtin-completing-read} performs
+some additional work, and any function used in its place has to do
+the same.
+@end defopt
+
+@defun magit-builtin-completing-read prompt choices &optional predicate require-match initial-input hist def
+This function performs completion using the built-in @code{completing-read}
+and does some additional magit-specific work.
+@end defun
+
+@defun magit-ido-completing-read prompt choices &optional predicate require-match initial-input hist def
+This function performs completion using @code{ido-completing-read+} from the
+package by the same name (which you have to explicitly install) and
+does some additional magit-specific work.
+
+We have to use @code{ido-completing-read+} instead of the
+@code{ido-completing-read} that comes with Ido itself, because the latter,
+while intended as a drop-in replacement, cannot serve that purpose
+because it violates too many of the implicit conventions.
+@end defun
+
+@defun magit-completing-read prompt choices &optional predicate require-match initial-input hist def fallback
+This is the function that Magit commands use when they need the user
+to select a single thing to act on.  The arguments have the same
+meaning as for @code{completing-read}, except for FALLBACK, which is unique
+to this function and is described below.
+
+Instead of asking the user to choose from a list of possible
+candidates, this function may just return the default specified by
+DEF, with or without requiring user confirmation.  Whether that is
+the case depends on PROMPT, @code{this-command} and @code{magit-dwim-selection}.
+See the documentation of the latter for more information.
+
+If it does read a value in the minibuffer, then this function acts
+similar to @code{completing-read}, except for the following:
+
+@itemize
+@item
+COLLECTION must be a list of choices.  A function is not
+supported.
+
+@item
+If REQUIRE-MATCH is @code{nil} and the user exits without a choice, then
+@code{nil} is returned instead of an empty string.
+
+@item
+If REQUIRE-MATCH is non-nil and the users exits without a choice,
+an user-error is raised.
+
+@item
+FALLBACK specifies a secondary default that is only used if the
+primary default DEF is @code{nil}.  The secondary default is not subject
+to @code{magit-dwim-selection} — if DEF is @code{nil} but FALLBACK is not, then
+this function always asks the user to choose a candidate, just as
+if both defaults were @code{nil}.
+
+@item
+@code{format-prompt} is called on PROMPT and DEF (or FALLBACK if
+DEF is @code{nil}).  This appends ": " to the prompt and may also
+add the default to the prompt, using the format specified by
+@code{minibuffer-default-prompt-format} and depending on
+@code{magit-completing-read-default-prompt-predicate}.
+@end itemize
+@end defun
+
+@node Additional Completion Options
+@subsection Additional Completion Options
+
+@defopt magit-list-refs-sortby
+For many commands that read a ref or refs from the user, the value
+of this option can be used to control the order of the refs.  Valid
+values include any key accepted by the @code{--sort} flag of @code{git
+  for-each-ref}.  By default, refs are sorted alphabetically by their
+full name (e.g., "refs/heads/master").
+@end defopt
+
+@node Mouse Support
+@section Mouse Support
+
+Double clicking on a section heading toggles the visibility of its
+body, if any.  Likewise clicking in the left fringe toggles the
+visibility of the appropriate section.
+
+A context menu is provided but has to be enabled explicitly.  In Emacs
+28 and greater, enable the global mode @code{context-menu-mode}.  If you use an
+older Emacs release, set @code{magit-section-show-context-menu-for-emacs<28}.
+
+@node Running Git
+@section Running Git
+
+@menu
+* Viewing Git Output::
+* Git Process Status::
+* Running Git Manually::
+* Git Executable::
+* Global Git Arguments::
+@end menu
+
+@node Viewing Git Output
+@subsection Viewing Git Output
+
+Magit runs Git either for side-effects (e.g., when pushing) or to get
+some value (e.g., the name of the current branch).
+
+When Git is run for side-effects, the process output is logged in a
+per-repository log buffer, which can be consulted using the
+@code{magit-process} command when things don't go as expected.
+
+The output/errors for up to `magit-process-log-max' Git commands are
+retained.
+
+@table @asis
+@item @kbd{$} (@code{magit-process})
+@kindex $
+@findex magit-process
+This commands displays the process buffer for the current
+repository.
+@end table
+
+Inside that buffer, the usual key bindings for navigating and showing
+sections are available.  There is one additional command.
+
+@table @asis
+@item @kbd{k} (@code{magit-process-kill})
+@kindex k
+@findex magit-process-kill
+This command kills the process represented by the section at point.
+@end table
+
+@defvar magit-git-debug
+This option controls whether additional reporting of git errors is
+enabled.
+
+Magit basically calls git for one of these two reasons: for
+side-effects or to do something with its standard output.
+
+When git is run for side-effects then its output, including error
+messages, go into the process buffer which is shown when using @code{$}.
+
+When git's output is consumed in some way, then it would be too
+expensive to also insert it into this buffer, but when this
+option is non-nil and git returns with a non-zero exit status,
+then at least its standard error is inserted into this buffer.
+
+This is only intended for debugging purposes.  Do not enable this
+permanently, that would negatively affect performance.
+
+This is only intended for debugging purposes.  Do not enable this
+permanently, that would negatively affect performance.  Also note
+that just because git exits with a non-zero exit status and prints
+an error message that usually doesn't mean that it is an error as
+far as Magit is concerned, which is another reason we usually hide
+these error messages.  Whether some error message is relevant in
+the context of some unexpected behavior has to be judged on a case
+by case basis.
+
+The command @code{magit-toggle-git-debug} changes the value of this
+variable.
+@end defvar
+
+@defvar magit-process-extreme-logging
+This option controls whether @code{magit-process-file} logs to the
+@code{*Messages*} buffer.
+
+Only intended for temporary use when you try to figure out how
+Magit uses Git behind the scene.  Output that normally goes to
+the magit-process buffer continues to go there.  Not all output
+goes to either of these two buffers.
+@end defvar
+
+@node Git Process Status
+@subsection Git Process Status
+
+When a Git process is running for side-effects, Magit displays an
+indicator in the mode line, using the @code{magit-mode-line-process} face.
+
+If the Git process exits successfully, the process indicator is
+removed from the mode line immediately.
+
+In the case of a Git error, the process indicator is not removed, but
+is instead highlighted with the @code{magit-mode-line-process-error} face,
+and the error details from the process buffer are provided as a
+tooltip for mouse users.  This error indicator persists in the mode
+line until the next magit buffer refresh.
+
+If you do not wish process errors to be indicated in the mode line,
+customize the @code{magit-process-display-mode-line-error} user option.
+
+Process errors are additionally indicated at the top of the status
+buffer.
+
+@node Running Git Manually
+@subsection Running Git Manually
+
+While Magit provides many Emacs commands to interact with Git, it does
+not cover everything.  In those cases your existing Git knowledge will
+come in handy.  Magit provides some commands for running arbitrary Git
+commands by typing them into the minibuffer, instead of having to
+switch to a shell.
+
+@table @asis
+@item @kbd{!} (@code{magit-run})
+@kindex !
+@findex magit-run
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+@item @kbd{! !} (@code{magit-git-command-topdir})
+@kindex ! !
+@findex magit-git-command-topdir
+This command reads a command from the user and executes it in the
+top-level directory of the current working tree.
+
+The string "git " is used as initial input when prompting the user
+for the command.  It can be removed to run another command.
+
+@item @kbd{:} (@code{magit-git-command})
+@itemx @kbd{! p}
+@kindex :
+@kindex ! p
+@findex magit-git-command
+This command reads a command from the user and executes it in
+@code{default-directory}.  With a prefix argument the command is executed
+in the top-level directory of the current working tree instead.
+
+The string "git " is used as initial input when prompting the user
+for the command.  It can be removed to run another command.
+
+@item @kbd{! s} (@code{magit-shell-command-topdir})
+@kindex ! s
+@findex magit-shell-command-topdir
+This command reads a command from the user and executes it in the
+top-level directory of the current working tree.
+
+@item @kbd{! S} (@code{magit-shell-command})
+@kindex ! S
+@findex magit-shell-command
+This command reads a command from the user and executes it in
+@code{default-directory}.  With a prefix argument the command is executed
+in the top-level directory of the current working tree instead.
+@end table
+
+@defopt magit-shell-command-verbose-prompt
+Whether the prompt, used by the above commands when reading a
+shell command, shows the directory in which it will be run.
+@end defopt
+
+These suffix commands start external gui tools.
+
+@table @asis
+@item @kbd{! k} (@code{magit-run-gitk})
+@kindex ! k
+@findex magit-run-gitk
+This command runs @code{gitk} in the current repository.
+
+@item @kbd{! a} (@code{magit-run-gitk-all})
+@kindex ! a
+@findex magit-run-gitk-all
+This command runs @code{gitk --all} in the current repository.
+
+@item @kbd{! b} (@code{magit-run-gitk-branches})
+@kindex ! b
+@findex magit-run-gitk-branches
+This command runs @code{gitk --branches} in the current repository.
+
+@item @kbd{! g} (@code{magit-run-git-gui})
+@kindex ! g
+@findex magit-run-git-gui
+This command runs @code{git gui} in the current repository.
+
+@item @kbd{! m} (@code{magit-git-mergetool})
+@kindex ! m
+@findex magit-git-mergetool
+This command runs @samp{git mergetool --gui} in the current repository.
+
+With a prefix argument this acts as a transient prefix command,
+allowing the user to select the mergetool and change some settings.
+@end table
+
+@node Git Executable
+@subsection Git Executable
+
+When Magit calls Git, then it may do so using the absolute path to the
+@code{git} executable, or using just its name.
+
+When running @code{git} locally and the @code{system-type} is @code{windows-nt} (any
+Windows version) or @code{darwin} (macOS) then @code{magit-git-executable} is set
+to an absolute path when Magit is loaded.
+
+On Windows it is necessary to use an absolute path because Git comes
+with several wrapper scripts for the actual @code{git} binary, which are also
+placed on @code{$PATH}, and using one of these wrappers instead of the binary
+would degrade performance horribly.  For some macOS users using just
+the name of the executable also performs horribly, so we avoid doing
+that on that platform as well.  On other platforms, using just the
+name seems to work just fine.
+
+Using an absolute path when running @code{git} on a remote machine over
+Tramp, would be problematic to use an absolute path that is suitable
+on the local machine, so a separate option is used to control the name
+or path that is used on remote machines.
+
+@defopt magit-git-executable
+The @code{git} executable used by Magit on the local host.  This should be
+either the absolute path to the executable, or the string "git" to
+let Emacs find the executable itself, using the standard mechanism
+for doing such things.
+@end defopt
+
+@defopt magit-remote-git-executable
+The @code{git} executable used by Magit on remote machines over Tramp.
+Normally this should be just the string "git".  Consider customizing
+@code{tramp-remote-path} instead of this option.
+@end defopt
+
+If Emacs is unable to find the correct executable, then you can
+work around that by explicitly setting the value of one of these two
+options.  Doing that should be considered a kludge; it is better to
+make sure that the order in @code{exec-path} or @code{tramp-remote-path} is correct.
+
+Note that @code{exec-path} is set based on the value of the @code{PATH} environment
+variable that is in effect when Emacs is started.  If you set @code{PATH} in
+your shell's init files, then that only has an effect on Emacs if you
+start it from that shell (because the environment of a process is only
+passed to its child processes, not to arbitrary other processes).  If
+that is not how you start Emacs, then the @code{exec-path-from-shell} package
+can help; though honestly I consider that a kludge too.
+
+The command @code{magit-debug-git-executable} can be useful to find out where
+Emacs is searching for @code{git}.
+
+@table @asis
+@item @kbd{M-x magit-debug-git-executable}
+@findex magit-debug-git-executable
+This command displays a buffer with information about
+@code{magit-git-executable} and  @code{magit-remote-git-executable}.
+
+@item @kbd{M-x magit-version}
+@findex magit-version
+This command shows the currently used versions of Magit, Git, and
+Emacs in the echo area.  Non-interactively this just returns the
+Magit version.
+@end table
+
+@node Global Git Arguments
+@subsection Global Git Arguments
+
+@defopt magit-git-global-arguments
+The arguments set here are used every time the git executable is run
+as a subprocess.  They are placed right after the executable itself
+and before the git command - as in @code{git HERE... COMMAND REST}.  For
+valid arguments see 
+@ifinfo
+@ref{git,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git">git(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git(1) manpage.
+@end iftex
+
+Be careful what you add here, especially if you are using Tramp to
+connect to servers with ancient Git versions.  Never remove anything
+that is part of the default value, unless you really know what you
+are doing.  And think very hard before adding something; it will be
+used every time Magit runs Git for any purpose.
+@end defopt
+
+@node Inspecting
+@chapter Inspecting
+
+The functionality provided by Magit can be roughly divided into three
+groups: inspecting existing data, manipulating existing data or adding
+new data, and transferring data.  Of course that is a rather crude
+distinction that often falls short, but it's more useful than no
+distinction at all.  This section is concerned with inspecting data,
+the next two with manipulating and transferring it.  Then follows a
+section about miscellaneous functionality, which cannot easily be fit
+into this distinction.
+
+Of course other distinctions make sense too, e.g., Git's distinction
+between porcelain and plumbing commands, which for the most part is
+equivalent to Emacs' distinction between interactive commands and
+non-interactive functions.  All of the sections mentioned before are
+mainly concerned with the porcelain -- Magit's plumbing layer is
+described later.
+
+@menu
+* Status Buffer::
+* Repository List::
+* Logging::
+* Diffing::
+* Ediffing::
+* References Buffer::
+* Bisecting::
+* Visiting Files and Blobs::
+* Blaming::
+@end menu
+
+@node Status Buffer
+@section Status Buffer
+
+While other Magit buffers contain, e.g., one particular diff or one
+particular log, the status buffer contains the diffs for staged and
+unstaged changes, logs for unpushed and unpulled commits, lists of
+stashes and untracked files, and information related to the current
+branch.
+
+During certain incomplete operations -- for example when a merge
+resulted in a conflict -- additional information is displayed that
+helps proceeding with or aborting the operation.
+
+The command @code{magit-status} displays the status buffer belonging to the
+current repository in another window.  This command is used so often
+that it should be bound globally.  We recommend using @code{C-x g}:
+
+@lisp
+(global-set-key (kbd "C-x g") 'magit-status)
+@end lisp
+
+@table @asis
+@item @kbd{C-x g} (@code{magit-status})
+@kindex C-x g
+@findex magit-status
+When invoked from within an existing Git repository, then this
+command shows the status of that repository in a buffer.
+
+If the current directory isn't located within a Git repository, then
+this command prompts for an existing repository or an arbitrary
+directory, depending on the option @code{magit-repository-directories}, and
+the status for the selected repository is shown instead.
+
+@itemize
+@item
+If that option specifies any existing repositories, then the user
+is asked to select one of them.
+
+@item
+Otherwise the user is asked to select an arbitrary directory using
+regular file-name completion.  If the selected directory is the
+top-level directory of an existing working tree, then the status
+buffer for that is shown.
+
+@item
+Otherwise the user is offered to initialize the selected directory
+as a new repository.  After creating the repository its status
+buffer is shown.
+@end itemize
+
+These fallback behaviors can also be forced using one or more
+prefix arguments:
+
+@itemize
+@item
+With two prefix arguments (or more precisely a numeric prefix
+value of 16 or greater) an arbitrary directory is read, which is
+then acted on as described above.  The same could be accomplished
+using the command @code{magit-init}.
+
+@item
+With a single prefix argument an existing repository is read from
+the user, or if no repository can be found based on the value of
+@code{magit-repository-directories}, then the behavior is the same as with
+two prefix arguments.
+@end itemize
+@end table
+
+@defopt magit-repository-directories
+List of directories that are Git repositories or contain Git
+repositories.
+
+Each element has the form @code{(DIRECTORY . DEPTH)}.  DIRECTORY has to be
+a directory or a directory file-name, a string.  DEPTH, an integer,
+specifies the maximum depth to look for Git repositories.  If it is
+0, then only add DIRECTORY itself.
+
+This option controls which repositories are being listed by
+@code{magit-list-repositories}.  It also affects @code{magit-status} (which see)
+in potentially surprising ways (see above).
+@end defopt
+
+@deffn Command magit-status-quick
+This command is an alternative to @code{magit-status} that usually avoids
+refreshing the status buffer.
+
+If the status buffer of the current Git repository exists but isn't
+being displayed in the selected frame, then it is displayed without
+being refreshed.
+
+If the status buffer is being displayed in the selected frame,
+then this command refreshes it.
+
+Prefix arguments have the same meaning as for @code{magit-status},
+and additionally cause the buffer to be refresh.
+
+To use this command add this to your init file:
+
+@lisp
+(global-set-key (kbd "C-x g") 'magit-status-quick).
+@end lisp
+
+If you do that and then for once want to redisplay the buffer and
+also immediately refresh it, then type @code{C-x g} followed by @code{g}.
+
+A possible alternative command is @code{magit-display-repository-buffer}.
+It supports displaying any existing Magit buffer that belongs to the
+current repository; not just the status buffer.
+@end deffn
+
+@deffn Command ido-enter-magit-status
+From an Ido prompt used to open a file, instead drop into
+@code{magit-status}.  This is similar to @code{ido-magic-delete-char}, which,
+despite its name, usually causes a Dired buffer to be created.
+
+To make this command available, use something like:
+
+@lisp
+(add-hook 'ido-setup-hook
+          (lambda ()
+            (define-key ido-completion-map
+              (kbd \"C-x g\") 'ido-enter-magit-status)))
+@end lisp
+
+Starting with Emacs 25.1 the Ido keymaps are defined just once
+instead of every time Ido is invoked, so now you can modify it
+like pretty much every other keymap:
+
+@lisp
+(define-key ido-common-completion-map
+  (kbd \"C-x g\") 'ido-enter-magit-status)
+@end lisp
+@end deffn
+
+@menu
+* Status Sections::
+* Status Header Sections::
+* Status Module Sections::
+* Status Options::
+@end menu
+
+@node Status Sections
+@subsection Status Sections
+
+The contents of status buffers is controlled using the hook
+@code{magit-status-sections-hook}.  See @ref{Section Hooks} to learn about such
+hooks and how to customize them.
+
+@defopt magit-status-sections-hook
+Hook run to insert sections into a status buffer.
+@end defopt
+
+The first function on that hook by default is
+@code{magit-insert-status-headers}; it is described in the next section.
+By default the following functions are also members of that hook:
+
+@defun magit-insert-merge-log
+Insert section for the on-going merge.  Display the heads that are
+being merged.  If no merge is in progress, do nothing.
+@end defun
+
+@defun magit-insert-rebase-sequence
+Insert section for the on-going rebase sequence.
+If no such sequence is in progress, do nothing.
+@end defun
+
+@defun magit-insert-am-sequence
+Insert section for the on-going patch applying sequence.
+If no such sequence is in progress, do nothing.
+@end defun
+
+@defun magit-insert-sequencer-sequence
+Insert section for the on-going cherry-pick or revert sequence.
+If no such sequence is in progress, do nothing.
+@end defun
+
+@defun magit-insert-bisect-output
+While bisecting, insert section with output from @code{git bisect}.
+@end defun
+
+@defun magit-insert-bisect-rest
+While bisecting, insert section visualizing the bisect state.
+@end defun
+
+@defun magit-insert-bisect-log
+While bisecting, insert section logging bisect progress.
+@end defun
+
+@defun magit-insert-untracked-files
+Maybe insert a list or tree of untracked files.
+
+Do so depending on the value of @code{status.showUntrackedFiles}.  Note
+that even if the value is @code{all}, Magit still initially only shows
+directories.  But the directory sections can then be expanded using
+@code{TAB}.
+@end defun
+
+@defun magit-insert-unstaged-changes
+Insert section showing unstaged changes.
+@end defun
+
+@defun magit-insert-staged-changes
+Insert section showing staged changes.
+@end defun
+
+@defun magit-insert-stashes &optional ref heading
+Insert the @code{stashes} section showing reflog for "refs/stash".
+If optional REF is non-nil show reflog for that instead.
+If optional HEADING is non-nil use that as section heading
+instead of "Stashes:".
+@end defun
+
+@defun magit-insert-unpulled-from-upstream
+Insert section showing commits that haven't been pulled from the
+upstream branch yet.
+@end defun
+
+@defun magit-insert-unpulled-from-pushremote
+Insert section showing commits that haven't been pulled from the
+push-remote branch yet.
+@end defun
+
+@defun magit-insert-unpushed-to-upstream
+Insert section showing commits that haven't been pushed to the
+upstream yet.
+@end defun
+
+@defun magit-insert-unpushed-to-pushremote
+Insert section showing commits that haven't been pushed to the
+push-remote yet.
+@end defun
+
+The following functions can also be added to the above hook:
+
+@defun magit-insert-tracked-files
+Insert a tree of tracked files.
+@end defun
+
+@defun magit-insert-ignored-files
+Insert a tree of ignored files.
+Its possible to limit the logs in the current buffer to a certain
+directory using @code{D = f <DIRECTORY> RET g}.  If you do that, then that
+that also affects this command.
+
+The log filter can be used to limit to multiple files.  In that case
+this function only respects the first of the files and only if it is
+a directory.
+@end defun
+
+@defun magit-insert-skip-worktree-files
+Insert a tree of skip-worktree files.
+If the first element of @code{magit-buffer-diff-files} is a
+directory, then limit the list to files below that.  The value
+of that variable can be set using @code{D -- DIRECTORY RET g}.
+@end defun
+
+@defun magit-insert-assumed-unchanged-files
+Insert a tree of files that are assumed to be unchanged.
+If the first element of @code{magit-buffer-diff-files} is a
+directory, then limit the list to files below that.  The value
+of that variable can be set using @code{D -- DIRECTORY RET g}.
+@end defun
+
+@defun magit-insert-unpulled-or-recent-commits
+Insert section showing unpulled or recent commits.
+If an upstream is configured for the current branch and it is
+ahead of the current branch, then show the missing commits.
+Otherwise, show the last @code{magit-log-section-commit-count}
+commits.
+@end defun
+
+@defun magit-insert-recent-commits
+Insert section showing the last @code{magit-log-section-commit-count}
+commits.
+@end defun
+
+@defopt magit-log-section-commit-count
+How many recent commits @code{magit-insert-recent-commits} and
+@code{magit-insert-unpulled-or-recent-commits} (provided there are no
+unpulled commits) show.
+@end defopt
+
+@defun magit-insert-unpulled-cherries
+Insert section showing unpulled commits.
+Like @code{magit-insert-unpulled-commits} but prefix each commit
+that has not been applied yet (i.e., a commit with a patch-id
+not shared with any local commit) with "+", and all others
+with "-".
+@end defun
+
+@defun magit-insert-unpushed-cherries
+Insert section showing unpushed commits.
+Like @code{magit-insert-unpushed-commits} but prefix each commit
+which has not been applied to upstream yet (i.e., a commit with
+a patch-id not shared with any upstream commit) with "+" and
+all others with "-".
+@end defun
+
+See @ref{References Buffer} for some more section inserters, which could be
+used here.
+
+@node Status Header Sections
+@subsection Status Header Sections
+
+The contents of status buffers is controlled using the hook
+@code{magit-status-sections-hook} (see @ref{Status Sections}).
+
+By default @code{magit-insert-status-headers} is the first member of that
+hook variable.
+
+@defun magit-insert-status-headers
+Insert headers sections appropriate for @code{magit-status-mode} buffers.
+The sections are inserted by running the functions on the hook
+@code{magit-status-headers-hook}.
+@end defun
+
+@defopt magit-status-headers-hook
+Hook run to insert headers sections into the status buffer.
+
+This hook is run by @code{magit-insert-status-headers}, which in turn has
+to be a member of @code{magit-status-sections-hook} to be used at all.
+@end defopt
+
+By default the following functions are members of the above hook:
+
+@defun magit-insert-error-header
+Insert a header line showing the message about the Git error that
+just occurred.
+
+This function is only aware of the last error that occur when Git
+was run for side-effects.  If, for example, an error occurs while
+generating a diff, then that error won't be inserted.  Refreshing
+the status buffer causes this section to disappear again.
+@end defun
+
+@defun magit-insert-diff-filter-header
+Insert a header line showing the effective diff filters.
+@end defun
+
+@defun magit-insert-head-branch-header
+Insert a header line about the current branch or detached @code{HEAD}.
+@end defun
+
+@defun magit-insert-upstream-branch-header
+Insert a header line about the branch that is usually pulled into
+the current branch.
+@end defun
+
+@defun magit-insert-push-branch-header
+Insert a header line about the branch that the current branch is
+usually pushed to.
+@end defun
+
+@defun magit-insert-tags-header
+Insert a header line about the current and/or next tag, along with
+the number of commits between the tag and @code{HEAD}.
+@end defun
+
+The following functions can also be added to the above hook:
+
+@defun magit-insert-repo-header
+Insert a header line showing the path to the repository top-level.
+@end defun
+
+@defun magit-insert-remote-header
+Insert a header line about the remote of the current branch.
+
+If no remote is configured for the current branch, then fall back
+showing the "origin" remote, or if that does not exist the first
+remote in alphabetic order.
+@end defun
+
+@defun magit-insert-user-header
+Insert a header line about the current user.
+@end defun
+
+@node Status Module Sections
+@subsection Status Module Sections
+
+The contents of status buffers is controlled using the hook
+@code{magit-status-sections-hook} (see @ref{Status Sections}).
+
+By default @code{magit-insert-modules} is @emph{not} a member of that hook
+variable.
+
+@defun magit-insert-modules
+Insert submodule sections.
+
+Hook @code{magit-module-sections-hook} controls which module sections are
+inserted, and option @code{magit-module-sections-nested} controls whether
+they are wrapped in an additional section.
+@end defun
+
+@defopt magit-module-sections-hook
+Hook run by @code{magit-insert-modules}.
+@end defopt
+
+@defopt magit-module-sections-nested
+This option controls whether @code{magit-insert-modules} wraps inserted
+sections in an additional section.
+
+If this is non-nil, then only a single top-level section is inserted.
+If it is nil, then all sections listed in @code{magit-module-sections-hook}
+become top-level sections.
+@end defopt
+
+@defun magit-insert-modules-overview
+Insert sections for all submodules.  For each section insert the
+path, the branch, and the output of @code{git describe --tags},
+or, failing that, the abbreviated HEAD commit hash.
+
+Press @code{RET} on such a submodule section to show its own status buffer.
+Press @code{RET} on the "Modules" section to display a list of submodules
+in a separate buffer.  This shows additional information not
+displayed in the super-repository's status buffer.
+@end defun
+
+@defun magit-insert-modules-unpulled-from-upstream
+Insert sections for modules that haven't been pulled from the
+upstream yet.  These sections can be expanded to show the respective
+commits.
+@end defun
+
+@defun magit-insert-modules-unpulled-from-pushremote
+Insert sections for modules that haven't been pulled from the
+push-remote yet.  These sections can be expanded to show the
+respective commits.
+@end defun
+
+@defun magit-insert-modules-unpushed-to-upstream
+Insert sections for modules that haven't been pushed to the upstream
+yet.  These sections can be expanded to show the respective commits.
+@end defun
+
+@defun magit-insert-modules-unpushed-to-pushremote
+Insert sections for modules that haven't been pushed to the
+push-remote yet.  These sections can be expanded to show the
+respective commits.
+@end defun
+
+@node Status Options
+@subsection Status Options
+
+@defopt magit-status-margin
+This option specifies whether the margin is initially shown in
+Magit-Status mode buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+Also see the proceeding section for more options concerning status
+buffers.
+
+@node Repository List
+@section Repository List
+
+@deffn Command magit-list-repositories
+This command displays a list of repositories in a separate buffer.
+
+The option @code{magit-repository-directories} controls which repositories are
+displayed.
+@end deffn
+
+@defopt magit-repolist-columns
+This option controls what columns are displayed by the command
+@code{magit-list-repositories} and how they are displayed.
+
+Each element has the form @code{(HEADER WIDTH FORMAT PROPS)}.
+
+HEADER is the string displayed in the header.  WIDTH is the width
+of the column.  FORMAT is a function that is called with one
+argument, the repository identification (usually its basename),
+and with @code{default-directory} bound to the toplevel of its working
+tree.  It has to return a string to be inserted or nil.  PROPS is
+an alist that supports the keys @code{:right-align}, @code{:pad-right} and
+@code{:sort}.
+
+The @code{:sort} function has a weird interface described in the
+docstring of @code{tabulated-list--get-sort}.  Alternatively @code{<} and
+@code{magit-repolist-version<} can be used as those functions are
+automatically replaced with functions that satisfy the interface.
+Set @code{:sort} to @code{nil} to inhibit sorting; if unspecified, then the
+column is sortable using the default sorter.
+
+You may wish to display a range of numeric columns using just one
+character per column and without any padding between columns, in
+which case you should use an appropriate HEADER, set WIDTH to 1,
+and set @code{:pad-right} to 9. @code{+} is substituted for numbers higher than 9.
+@end defopt
+
+@noindent
+The following functions can be added to the above option:
+
+@defun magit-repolist-column-ident
+This function inserts the identification of the repository.  Usually
+this is just its basename.
+@end defun
+
+@defun magit-repolist-column-path
+This function inserts the absolute path of the repository.
+@end defun
+
+@defun magit-repolist-column-version
+This function inserts a description of the repository's @code{HEAD} revision.
+@end defun
+
+@defun magit-repolist-column-branch
+This function inserts the name of the current branch.
+@end defun
+
+@defun magit-repolist-column-upstream
+This function inserts the name of the upstream branch of the current
+branch.
+@end defun
+
+@defun magit-repolist-column-branches
+This function inserts the number of branches.
+@end defun
+
+@defun magit-repolist-column-stashes
+This function inserts the number of stashes.
+@end defun
+
+@defun magit-repolist-column-flag
+This function inserts a flag as specified by
+@code{magit-repolist-column-flag-alist}.
+
+By default this indicates whether there are uncommitted changes.
+
+@itemize
+@item
+@code{N} if there is at least one untracked file.
+@item
+@code{U} if there is at least one unstaged file.
+@item
+@code{S} if there is at least one staged file.
+@end itemize
+
+Only the first one of these that applies is shown.
+@end defun
+
+@defun magit-repolist-column-flags
+This functions insert all flags as specified by
+@code{magit-repolist-column-flag-alist}.
+
+This is an alternative to function @code{magit-repolist-column-flag},
+which only lists the first one found.
+@end defun
+
+@defun magit-repolist-column-unpulled-from-upstream
+This function inserts the number of upstream commits not in the
+current branch.
+@end defun
+
+@defun magit-repolist-column-unpulled-from-pushremote
+This function inserts the number of commits in the push branch but
+not the current branch.
+@end defun
+
+@defun magit-repolist-column-unpushed-to-upstream
+This function inserts the number of commits in the current branch
+but not its upstream.
+@end defun
+
+@defun magit-repolist-column-unpushed-to-pushremote
+This function inserts the number of commits in the current branch
+but not its push branch.
+@end defun
+
+@noindent
+The following commands are available in repolist buffers:
+
+@table @asis
+@item @kbd{@key{RET}} (@code{magit-repolist-status})
+@kindex RET
+@findex magit-repolist-status
+This command shows the status for the repository at point.
+
+@item @kbd{m} (@code{magit-repolist-mark})
+@kindex m
+@findex magit-repolist-mark
+This command marks the repository at point.
+
+@item @kbd{u} (@code{magit-repolist-unmark})
+@kindex u
+@findex magit-repolist-unmark
+This command unmarks the repository at point.
+
+@item @kbd{f} (@code{magit-repolist-fetch})
+@kindex f
+@findex magit-repolist-fetch
+This command fetches all marked repositories.  If no repositories
+are marked, then it offers to fetch all displayed repositories.
+
+@item @kbd{5} (@code{magit-repolist-find-file-other-frame})
+@kindex 5
+@findex magit-repolist-find-file-other-frame
+This command reads a relative file-name (without completion) and
+opens the respective file in each marked repository in a new frame.
+If no repositories are marked, then it offers to do this for all
+displayed repositories.
+@end table
+
+@node Logging
+@section Logging
+
+The status buffer contains logs for the unpushed and unpulled commits,
+but that obviously isn't enough.  The transient prefix command
+@code{magit-log}, on @code{l}, features several suffix commands, which show a
+specific log in a separate log buffer.
+
+Like other transient prefix commands, @code{magit-log} also features several
+infix arguments that can be changed before invoking one of the suffix
+commands.  However, in the case of the log transient, these arguments
+may be taken from those currently in use in the current repository's
+log buffer, depending on the value of @code{magit-prefix-use-buffer-arguments}
+(see @ref{Transient Arguments and Buffer Variables}).
+
+For information about the various arguments, see 
+@ifinfo
+@ref{git-log,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-log">git-log(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-log(1) manpage.
+@end iftex
+The switch @code{++order=VALUE} is converted to one of @code{--author-date-order},
+@code{--date-order}, or @code{--topo-order} before being passed to @code{git log}.
+
+The log transient also features several reflog commands.  See @ref{Reflog}.
+
+@table @asis
+@item @kbd{l} (@code{magit-log})
+@kindex l
+@findex magit-log
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{l l} (@code{magit-log-current})
+@kindex l l
+@findex magit-log-current
+Show log for the current branch.  When @code{HEAD} is detached or with a
+prefix argument, show log for one or more revs read from the
+minibuffer.
+
+@item @kbd{l h} (@code{magit-log-head})
+@kindex l h
+@findex magit-log-head
+Show log for @code{HEAD}.
+
+@item @kbd{l u} (@code{magit-log-related})
+@kindex l u
+@findex magit-log-related
+Show log for the current branch, its upstream and its push target.
+When the upstream is a local branch, then also show its own
+upstream.  When @code{HEAD} is detached, then show log for that, the
+previously checked out branch and its upstream and push-target.
+
+@item @kbd{l o} (@code{magit-log-other})
+@kindex l o
+@findex magit-log-other
+Show log for one or more revs read from the minibuffer.  The user
+can input any revision or revisions separated by a space, or even
+ranges, but only branches, tags, and a representation of the
+commit at point are available as completion candidates.
+
+@item @kbd{l L} (@code{magit-log-branches})
+@kindex l L
+@findex magit-log-branches
+Show log for all local branches and @code{HEAD}.
+
+@item @kbd{l b} (@code{magit-log-all-branches})
+@kindex l b
+@findex magit-log-all-branches
+Show log for all local and remote branches and @code{HEAD}.
+
+@item @kbd{l a} (@code{magit-log-all})
+@kindex l a
+@findex magit-log-all
+Show log for all references and @code{HEAD}.
+@end table
+
+Two additional commands that show the log for the file or blob that is
+being visited in the current buffer exists, see @ref{Commands for Buffers Visiting Files}.  The command @code{magit-cherry} also shows a log, see
+@ref{Cherries}.
+
+@menu
+* Refreshing Logs::
+* Log Buffer::
+* Log Margin::
+* Select from Log::
+* Reflog::
+* Cherries::
+@end menu
+
+@node Refreshing Logs
+@subsection Refreshing Logs
+
+The transient prefix command @code{magit-log-refresh}, on @code{L}, can be used to
+change the log arguments used in the current buffer, without changing
+which log is shown.  This works in dedicated log buffers, but also in
+the status buffer.
+
+@table @asis
+@item @kbd{L} (@code{magit-log-refresh})
+@kindex L
+@findex magit-log-refresh
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{L g} (@code{magit-log-refresh})
+@kindex L g
+@findex magit-log-refresh
+This suffix command sets the local log arguments for the current
+buffer.
+
+@item @kbd{L s} (@code{magit-log-set-default-arguments})
+@kindex L s
+@findex magit-log-set-default-arguments
+This suffix command sets the default log arguments for buffers of
+the same type as that of the current buffer.  Other existing buffers
+of the same type are not affected because their local values have
+already been initialized.
+
+@item @kbd{L w} (@code{magit-log-save-default-arguments})
+@kindex L w
+@findex magit-log-save-default-arguments
+This suffix command sets the default log arguments for buffers of
+the same type as that of the current buffer, and saves the value for
+future sessions.  Other existing buffers of the same type are not
+affected because their local values have already been initialized.
+
+@item @kbd{L L} (@code{magit-toggle-margin})
+@kindex L L
+@findex magit-toggle-margin
+Show or hide the margin.
+@end table
+
+@node Log Buffer
+@subsection Log Buffer
+
+@table @asis
+@item @kbd{L} (@code{magit-log-refresh})
+@kindex L
+@findex magit-log-refresh
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+See @ref{Refreshing Logs}.
+
+@item @kbd{q} (@code{magit-log-bury-buffer})
+@kindex q
+@findex magit-log-bury-buffer
+Bury the current buffer or the revision buffer in the same frame.
+Like @code{magit-mode-bury-buffer} (which see) but with a negative prefix
+argument instead bury the revision buffer, provided it is displayed
+in the current frame.
+
+@item @kbd{C-c C-b} (@code{magit-go-backward})
+@kindex C-c C-b
+@findex magit-go-backward
+Move backward in current buffer's history.
+
+@item @kbd{C-c C-f} (@code{magit-go-forward})
+@kindex C-c C-f
+@findex magit-go-forward
+Move forward in current buffer's history.
+
+@item @kbd{C-c C-n} (@code{magit-log-move-to-parent})
+@kindex C-c C-n
+@findex magit-log-move-to-parent
+Move to a parent of the current commit.  By default, this is the
+first parent, but a numeric prefix can be used to specify another
+parent.
+
+@item @kbd{j} (@code{magit-log-move-to-revision})
+@kindex j
+@findex magit-log-move-to-revision
+Read a revision and move to it in current log buffer.
+
+If the chosen reference or revision isn't being displayed in
+the current log buffer, then inform the user about that and do
+nothing else.
+
+If invoked outside any log buffer, then display the log buffer
+of the current repository first; creating it if necessary.
+
+@item @kbd{@key{SPC}} (@code{magit-diff-show-or-scroll-up})
+@kindex SPC
+@findex magit-diff-show-or-scroll-up
+Update the commit or diff buffer for the thing at point.
+
+Either show the commit or stash at point in the appropriate buffer,
+or if that buffer is already being displayed in the current frame
+and contains information about that commit or stash, then instead
+scroll the buffer up.  If there is no commit or stash at point, then
+prompt for a commit.
+
+@item @kbd{@key{DEL}} (@code{magit-diff-show-or-scroll-down})
+@kindex DEL
+@findex magit-diff-show-or-scroll-down
+Update the commit or diff buffer for the thing at point.
+
+Either show the commit or stash at point in the appropriate buffer,
+or if that buffer is already being displayed in the current frame
+and contains information about that commit or stash, then instead
+scroll the buffer down.  If there is no commit or stash at point,
+then prompt for a commit.
+
+@item @kbd{=} (@code{magit-log-toggle-commit-limit})
+@kindex =
+@findex magit-log-toggle-commit-limit
+Toggle the number of commits the current log buffer is limited to.
+If the number of commits is currently limited, then remove that
+limit.  Otherwise set it to 256.
+
+@item @kbd{+} (@code{magit-log-double-commit-limit})
+@kindex +
+@findex magit-log-double-commit-limit
+Double the number of commits the current log buffer is limited to.
+
+@item @kbd{-} (@code{magit-log-half-commit-limit})
+@kindex -
+@findex magit-log-half-commit-limit
+Half the number of commits the current log buffer is limited to.
+@end table
+
+@defopt magit-log-auto-more
+Insert more log entries automatically when moving past the last
+entry.  Only considered when moving past the last entry with
+@code{magit-goto-*-section} commands.
+@end defopt
+
+@defopt magit-log-show-refname-after-summary
+Whether to show the refnames after the commit summaries.  This is
+useful if you use really long branch names.
+@end defopt
+
+@defopt magit-log-show-color-graph-limit
+When showing more commits than specified by this option, then the
+@code{--color} argument, if specified, is silently dropped.  This is
+necessary because the @code{ansi-color} library, which is used to turn
+control sequences into faces, is just too slow.
+@end defopt
+
+@defopt magit-log-show-signatures-limit
+When showing more commits than specified by this option, then the
+@code{--show-signature} argument, if specified, is silently dropped.  This
+is necessary because checking the signature of a large number of
+commits is just too slow.
+@end defopt
+
+Magit displays references in logs a bit differently from how Git does
+it.
+
+Local branches are blue and remote branches are green.  Of course that
+depends on the used theme, as do the colors used for other types of
+references.  The current branch has a box around it, as do remote
+branches that are their respective remote's @code{HEAD} branch.
+
+If a local branch and its push-target point at the same commit, then
+their names are combined to preserve space and to make that
+relationship visible.  For example:
+
+@example
+origin/feature
+[green][blue-]
+
+instead of
+
+feature origin/feature
+[blue-] [green-------]
+@end example
+
+Also note that while the transient features the @code{--show-signature}
+argument, that won't actually be used when enabled, because Magit
+defaults to use just one line per commit.  Instead the commit
+colorized to indicate the validity of the signed commit object,
+using the faces named @code{magit-signature-*} (which see).
+
+For a description of @code{magit-log-margin} see @ref{Log Margin}.
+
+@node Log Margin
+@subsection Log Margin
+
+In buffers which show one or more logs, it is possible to show
+additional information about each commit in the margin.  The options
+used to configure the margin are named @code{magit-INFIX-margin}, where INFIX
+is the same as in the respective major-mode @code{magit-INFIX-mode}.  In
+regular log buffers that would be @code{magit-log-margin}.
+
+@defopt magit-log-margin
+This option specifies whether the margin is initially shown in
+Magit-Log mode buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+You can change the STYLE and AUTHOR-WIDTH of all @code{magit-INFIX-margin}
+options to the same values by customizing @code{magit-log-margin} @strong{before}
+@code{magit} is loaded.  If you do that, then the respective values for the
+other options will default to what you have set for that variable.
+Likewise if you set INIT in @code{magit-log-margin} to @code{nil}, then that is used
+in the default of all other options.  But setting it to @code{t}, i.e.
+re-enforcing the default for that option, does not carry to other
+options.
+
+@defopt magit-log-margin-show-committer-date
+This option specifies whether to show the committer date in the
+margin.  This option only controls whether the committer date is
+displayed instead of the author date.  Whether some date is
+displayed in the margin and whether the margin is displayed at all
+is controlled by other options.
+@end defopt
+
+@table @asis
+@item @kbd{L} (@code{magit-margin-settings})
+@kindex L
+@findex magit-margin-settings
+This transient prefix command binds the following suffix commands,
+each of which changes the appearance of the margin in some way.
+@end table
+
+In some buffers that support the margin, @code{L} is instead bound to
+@code{magit-log-refresh}, but that transient features the same commands, and
+then some other unrelated commands.
+
+@table @asis
+@item @kbd{L L} (@code{magit-toggle-margin})
+@kindex L L
+@findex magit-toggle-margin
+This command shows or hides the margin.
+
+@item @kbd{L l} (@code{magit-cycle-margin-style})
+@kindex L l
+@findex magit-cycle-margin-style
+This command cycles the style used for the margin.
+
+@item @kbd{L d} (@code{magit-toggle-margin-details})
+@kindex L d
+@findex magit-toggle-margin-details
+This command shows or hides details in the margin.
+@end table
+
+@node Select from Log
+@subsection Select from Log
+
+When the user has to select a recent commit that is reachable from
+@code{HEAD}, using regular completion would be inconvenient (because most
+humans cannot remember hashes or "HEAD~5", at least not without double
+checking).  Instead a log buffer is used to select the commit, which
+has the advantage that commits are presented in order and with the
+commit message.
+
+Such selection logs are used when selecting the beginning of a rebase
+and when selecting the commit to be squashed into.
+
+In addition to the key bindings available in all log buffers, the
+following additional key bindings are available in selection log
+buffers:
+
+@table @asis
+@item @kbd{C-c C-c} (@code{magit-log-select-pick})
+@kindex C-c C-c
+@findex magit-log-select-pick
+Select the commit at point and act on it.  Call
+@code{magit-log-select-pick-function} with the selected commit as
+argument.
+
+@item @kbd{C-c C-k} (@code{magit-log-select-quit})
+@kindex C-c C-k
+@findex magit-log-select-quit
+Abort selecting a commit, don't act on any commit.
+@end table
+
+@defopt magit-log-select-margin
+This option specifies whether the margin is initially shown in
+Magit-Log-Select mode buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+@node Reflog
+@subsection Reflog
+
+Also see 
+@ifinfo
+@ref{git-reflog,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-reflog">git-reflog(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-reflog(1) manpage.
+@end iftex
+
+These reflog commands are available from the log transient.  See
+@ref{Logging}.
+
+@table @asis
+@item @kbd{l r} (@code{magit-reflog-current})
+@kindex l r
+@findex magit-reflog-current
+Display the reflog of the current branch.
+
+@item @kbd{l O} (@code{magit-reflog-other})
+@kindex l O
+@findex magit-reflog-other
+Display the reflog of a branch or another ref.
+
+@item @kbd{l H} (@code{magit-reflog-head})
+@kindex l H
+@findex magit-reflog-head
+Display the @code{HEAD} reflog.
+@end table
+
+@defopt magit-reflog-margin
+This option specifies whether the margin is initially shown in
+Magit-Reflog mode buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+@node Cherries
+@subsection Cherries
+
+Cherries are commits that haven't been applied upstream (yet), and are
+usually visualized using a log.  Each commit is prefixed with @code{-} if it
+has an equivalent in the upstream and @code{+} if it does not, i.e., if it is
+a cherry.
+
+The command @code{magit-cherry} shows cherries for a single branch, but the
+references buffer (see @ref{References Buffer}) can show cherries for
+multiple "upstreams" at once.
+
+Also see 
+@ifinfo
+@ref{git-reflog,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-reflog">git-reflog(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-reflog(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{Y} (@code{magit-cherry})
+@kindex Y
+@findex magit-cherry
+Show commits that are in a certain branch but that have not been
+merged in the upstream branch.
+@end table
+
+@defopt magit-cherry-margin
+This option specifies whether the margin is initially shown in
+Magit-Cherry mode buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+@node Diffing
+@section Diffing
+
+The status buffer contains diffs for the staged and unstaged commits,
+but that obviously isn't enough.  The transient prefix command
+@code{magit-diff}, on @code{d}, features several suffix commands, which show a
+specific diff in a separate diff buffer.
+
+Like other transient prefix commands, @code{magit-diff} also features several
+infix arguments that can be changed before invoking one of the suffix
+commands.  However, in the case of the diff transient, these arguments may
+be taken from those currently in use in the current repository's diff
+buffer, depending on the value of @code{magit-prefix-use-buffer-arguments}
+(see @ref{Transient Arguments and Buffer Variables}).
+
+Also see 
+@ifinfo
+@ref{git-diff,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-diff">git-diff(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-diff(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{d} (@code{magit-diff})
+@kindex d
+@findex magit-diff
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{d d} (@code{magit-diff-dwim})
+@kindex d d
+@findex magit-diff-dwim
+Show changes for the thing at point.
+
+@item @kbd{d r} (@code{magit-diff-range})
+@kindex d r
+@findex magit-diff-range
+Show differences between two commits.
+
+RANGE should be a range (A..B or A@dots{}B) but can also be a single
+commit.  If one side of the range is omitted, then it defaults to
+@code{HEAD}.  If just a commit is given, then changes in the working tree
+relative to that commit are shown.
+
+If the region is active, use the revisions on the first and last
+line of the region.  With a prefix argument, instead of diffing the
+revisions, choose a revision to view changes along, starting at the
+common ancestor of both revisions (i.e., use a "@dots{}"  range).
+
+@item @kbd{d w} (@code{magit-diff-working-tree})
+@kindex d w
+@findex magit-diff-working-tree
+Show changes between the current working tree and the @code{HEAD} commit.
+With a prefix argument show changes between the working tree and a
+commit read from the minibuffer.
+
+@item @kbd{d s} (@code{magit-diff-staged})
+@kindex d s
+@findex magit-diff-staged
+Show changes between the index and the @code{HEAD} commit.  With a prefix
+argument show changes between the index and a commit read from the
+minibuffer.
+
+@item @kbd{d u} (@code{magit-diff-unstaged})
+@kindex d u
+@findex magit-diff-unstaged
+Show changes between the working tree and the index.
+
+@item @kbd{d p} (@code{magit-diff-paths})
+@kindex d p
+@findex magit-diff-paths
+Show changes between any two files on disk.
+@end table
+
+All of the above suffix commands update the repository's diff buffer.
+The diff transient also features two commands which show differences
+in another buffer:
+
+@table @asis
+@item @kbd{d c} (@code{magit-show-commit})
+@kindex d c
+@findex magit-show-commit
+Show the commit at point.  If there is no commit at point or with a
+prefix argument, prompt for a commit.
+
+@item @kbd{d t} (@code{magit-stash-show})
+@kindex d t
+@findex magit-stash-show
+Show all diffs of a stash in a buffer.
+@end table
+
+Two additional commands that show the diff for the file or blob that
+is being visited in the current buffer exists, see @ref{Commands for Buffers Visiting Files}.
+
+@menu
+* Refreshing Diffs::
+* Commands Available in Diffs::
+* Diff Options::
+* Revision Buffer::
+@end menu
+
+@node Refreshing Diffs
+@subsection Refreshing Diffs
+
+The transient prefix command @code{magit-diff-refresh}, on @code{D}, can be used to
+change the diff arguments used in the current buffer, without changing
+which diff is shown.  This works in dedicated diff buffers, but also
+in the status buffer.
+
+(There is one exception; diff arguments cannot be changed in buffers
+created by @code{magit-merge-preview} because the underlying Git command does
+not support these arguments.)
+
+@table @asis
+@item @kbd{D} (@code{magit-diff-refresh})
+@kindex D
+@findex magit-diff-refresh
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{D g} (@code{magit-diff-refresh})
+@kindex D g
+@findex magit-diff-refresh
+This suffix command sets the local diff arguments for the current
+buffer.
+
+@item @kbd{D s} (@code{magit-diff-set-default-arguments})
+@kindex D s
+@findex magit-diff-set-default-arguments
+This suffix command sets the default diff arguments for buffers of
+the same type as that of the current buffer.  Other existing buffers
+of the same type are not affected because their local values have
+already been initialized.
+
+@item @kbd{D w} (@code{magit-diff-save-default-arguments})
+@kindex D w
+@findex magit-diff-save-default-arguments
+This suffix command sets the default diff arguments for buffers of
+the same type as that of the current buffer, and saves the value for
+future sessions.  Other existing buffers of the same type are not
+affected because their local values have already been initialized.
+
+@item @kbd{D t} (@code{magit-diff-toggle-refine-hunk})
+@kindex D t
+@findex magit-diff-toggle-refine-hunk
+This command toggles hunk refinement on or off.
+
+@item @kbd{D r} (@code{magit-diff-switch-range-type})
+@kindex D r
+@findex magit-diff-switch-range-type
+This command converts the diff range type from "revA..revB" to
+"revB@dots{}revA", or vice versa.
+
+@item @kbd{D f} (@code{magit-diff-flip-revs})
+@kindex D f
+@findex magit-diff-flip-revs
+This command swaps revisions in the diff range from "revA..revB"
+to "revB..revA", or vice versa.
+
+@item @kbd{D F} (@code{magit-diff-toggle-file-filter})
+@kindex D F
+@findex magit-diff-toggle-file-filter
+This command toggles the file restriction of the diffs in the
+current buffer, allowing you to quickly switch between viewing all
+the changes in the commit and the restricted subset.  As a special
+case, when this command is called from a log buffer, it toggles the
+file restriction in the repository's revision buffer, which is
+useful when you display a revision from a log buffer that is
+restricted to a file or files.
+@end table
+
+In addition to the above transient, which allows changing any of the
+supported arguments, there also exist some commands that change only
+a particular argument.
+
+@table @asis
+@item @kbd{-} (@code{magit-diff-less-context})
+@kindex -
+@findex magit-diff-less-context
+This command decreases the context for diff hunks by COUNT lines.
+
+@item @kbd{+} (@code{magit-diff-more-context})
+@kindex +
+@findex magit-diff-more-context
+This command increases the context for diff hunks by COUNT lines.
+
+@item @kbd{0} (@code{magit-diff-default-context})
+@kindex 0
+@findex magit-diff-default-context
+This command resets the context for diff hunks to the default height.
+@end table
+
+The following commands quickly change what diff is being displayed
+without having to using one of the diff transient.
+
+@table @asis
+@item @kbd{C-c C-d} (@code{magit-diff-while-committing})
+@kindex C-c C-d
+@findex magit-diff-while-committing
+While committing, this command shows the changes that are about to
+be committed.  While amending, invoking the command again toggles
+between showing just the new changes or all the changes that will be
+committed.
+
+This binding is available in the diff buffer as well as the commit
+message buffer.
+
+@item @kbd{C-c C-b} (@code{magit-go-backward})
+@kindex C-c C-b
+@findex magit-go-backward
+This command moves backward in current buffer's history.
+
+@item @kbd{C-c C-f} (@code{magit-go-forward})
+@kindex C-c C-f
+@findex magit-go-forward
+This command moves forward in current buffer's history.
+@end table
+
+@node Commands Available in Diffs
+@subsection Commands Available in Diffs
+
+Some commands are only available if point is inside a diff.
+
+@code{magit-diff-visit-file} and related commands visit the appropriate
+version of the file that the diff at point is about.  Likewise
+@code{magit-diff-visit-worktree-file} and related commands visit the worktree
+version of the file that the diff at point is about.  See @ref{Visiting Files and Blobs from a Diff} for more information and the key bindings.
+
+@table @asis
+@item @kbd{C-c C-t} (@code{magit-diff-trace-definition})
+@kindex C-c C-t
+@findex magit-diff-trace-definition
+This command shows a log for the definition at point.
+@end table
+
+@defopt magit-log-trace-definition-function
+The function specified by this option is used by
+@code{magit-log-trace-definition} to determine the function at point.  For
+major-modes that have special needs, you could set the local value
+using the mode's hook.
+@end defopt
+
+@table @asis
+@item @kbd{C-c C-e} (@code{magit-diff-edit-hunk-commit})
+@kindex C-c C-e
+@findex magit-diff-edit-hunk-commit
+From a hunk, this command edits the respective commit and visits
+the file.
+
+First it visits the file being modified by the hunk at the correct
+location using @code{magit-diff-visit-file}.  This actually visits a blob.
+When point is on a diff header, not within an individual hunk, then
+this visits the blob the first hunk is about.
+
+Then it invokes @code{magit-edit-line-commit}, which uses an interactive
+rebase to make the commit editable, or if that is not possible
+because the commit is not reachable from @code{HEAD} by checking out that
+commit directly.  This also causes the actual worktree file to be
+visited.
+
+Neither the blob nor the file buffer are killed when finishing
+the rebase.  If that is undesirable, then it might be better to
+use @code{magit-rebase-edit-commit} instead of this command.
+
+@item @kbd{j} (@code{magit-jump-to-diffstat-or-diff})
+@kindex j
+@findex magit-jump-to-diffstat-or-diff
+This command jumps to the diffstat or diff.  When point is on a file
+inside the diffstat section, then jump to the respective diff
+section.  Otherwise, jump to the diffstat section or a child
+thereof.
+@end table
+
+The next two commands are not specific to Magit-Diff mode (or and
+Magit buffer for that matter), but it might be worth pointing out
+that they are available here too.
+
+@table @asis
+@item @kbd{@key{SPC}} (@code{scroll-up})
+@kindex SPC
+@findex scroll-up
+This command scrolls text upward.
+
+@item @kbd{@key{DEL}} (@code{scroll-down})
+@kindex DEL
+@findex scroll-down
+This command scrolls text downward.
+@end table
+
+@node Diff Options
+@subsection Diff Options
+
+@defopt magit-diff-refine-hunk
+Whether to show word-granularity differences within diff hunks.
+
+@itemize
+@item
+@code{nil} Never show fine differences.
+@item
+@code{t} Show fine differences for the current diff hunk only.
+@item
+@code{all} Show fine differences for all displayed diff hunks.
+@end itemize
+@end defopt
+
+@defopt magit-diff-refine-ignore-whitespace
+Whether to ignore whitespace changes in word-granularity
+differences.
+@end defopt
+
+@defopt magit-diff-adjust-tab-width
+Whether to adjust the width of tabs in diffs.
+
+Determining the correct width can be expensive if it requires
+opening large and/or many files, so the widths are cached in the
+variable @code{magit-diff--tab-width-cache}.  Set that to nil to invalidate
+the cache.
+
+@itemize
+@item
+@code{nil} Never adjust tab width.  Use `tab-width's value from the Magit
+buffer itself instead.
+
+@item
+@code{t} If the corresponding file-visiting buffer exits, then use
+@code{tab-width}'s value from that buffer.  Doing this is cheap, so this
+value is used even if a corresponding cache entry exists.
+
+@item
+@code{always} If there is no such buffer, then temporarily visit the file
+to determine the value.
+
+@item
+NUMBER Like @code{always}, but don't visit files larger than NUMBER
+bytes.
+@end itemize
+@end defopt
+
+@defopt magit-diff-paint-whitespace
+Specify where to highlight whitespace errors.
+
+See @code{magit-diff-highlight-trailing},
+@code{magit-diff-highlight-indentation}.  The symbol @code{t} means in all
+diffs, @code{status} means only in the status buffer, and nil means
+nowhere.
+
+@itemize
+@item
+@code{nil} Never highlight whitespace errors.
+@item
+@code{t} Highlight whitespace errors everywhere.
+@item
+@code{uncommitted} Only highlight whitespace errors in diffs showing
+uncommitted changes.  For backward compatibility @code{status} is treated
+as a synonym.
+@end itemize
+@end defopt
+
+@defopt magit-diff-paint-whitespace-lines
+Specify in what kind of lines to highlight whitespace errors.
+
+@itemize
+@item
+@code{t} Highlight only in added lines.
+@item
+@code{both} Highlight in added and removed lines.
+@item
+@code{all} Highlight in added, removed and context lines.
+@end itemize
+@end defopt
+
+@defopt magit-diff-highlight-trailing
+Whether to highlight whitespace at the end of a line in diffs.  Used
+only when @code{magit-diff-paint-whitespace} is non-nil.
+@end defopt
+
+@defopt magit-diff-highlight-indentation
+This option controls whether to highlight the indentation in case it
+used the "wrong" indentation style.  Indentation is only highlighted
+if @code{magit-diff-paint-whitespace} is also non-nil.
+
+The value is an alist of the form @code{((REGEXP . INDENT)...)}.  The path
+to the current repository is matched against each element in reverse
+order.  Therefore if a REGEXP matches, then earlier elements are not
+tried.
+
+If the used INDENT is @code{tabs}, highlight indentation with tabs.  If
+INDENT is an integer, highlight indentation with at least that many
+spaces.  Otherwise, highlight neither.
+@end defopt
+
+@defopt magit-diff-hide-trailing-cr-characters
+Whether to hide ^M characters at the end of a line in diffs.
+@end defopt
+
+@defopt magit-diff-highlight-hunk-region-functions
+This option specifies the functions used to highlight the
+hunk-internal region.
+
+@code{magit-diff-highlight-hunk-region-dim-outside} overlays the outside of
+the hunk internal selection with a face that causes the added and
+removed lines to have the same background color as context lines.
+This function should not be removed from the value of this option.
+
+@code{magit-diff-highlight-hunk-region-using-overlays} and
+@code{magit-diff-highlight-hunk-region-using-underline} emphasize the
+region by placing delimiting horizontal lines before and after it.
+Both of these functions have glitches which cannot be fixed due to
+limitations of Emacs' display engine.  For more information see
+@uref{https://github.com/magit/magit/issues/2758} ff.
+
+Instead of, or in addition to, using delimiting horizontal lines,
+to emphasize the boundaries, you may wish to emphasize the text
+itself, using @code{magit-diff-highlight-hunk-region-using-face}.
+
+In terminal frames it's not possible to draw lines as the overlay
+and underline variants normally do, so there they fall back to
+calling the face function instead.
+@end defopt
+
+@defopt magit-diff-unmarked-lines-keep-foreground
+This option controls whether added and removed lines outside the
+hunk-internal region only lose their distinct background color or
+also the foreground color.  Whether the outside of the region is
+dimmed at all depends on @code{magit-diff-highlight-hunk-region-functions}.
+@end defopt
+
+@defopt magit-diff-extra-stat-arguments
+This option specifies additional arguments to be used alongside
+@code{--stat}.
+
+The value is a list of zero or more arguments or a function that
+takes no argument and returns such a list.  These arguments are
+allowed here: @code{--stat-width}, @code{--stat-name-width},
+@code{--stat-graph-width} and @code{--compact-summary}.  Also see 
+@ifinfo
+@ref{git-diff,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-diff">git-diff(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-diff(1) manpage.
+@end iftex
+@end defopt
+
+@node Revision Buffer
+@subsection Revision Buffer
+
+@defopt magit-revision-insert-related-refs
+Whether to show related branches in revision buffers.
+
+@itemize
+@item
+@code{nil} Don't show any related branches.
+@item
+@code{t} Show related local branches.
+@item
+@code{all} Show related local and remote branches.
+@item
+@code{mixed} Show all containing branches and local merged branches.
+@end itemize
+@end defopt
+
+@defopt magit-revision-show-gravatars
+Whether to show gravatar images in revision buffers.
+
+If @code{nil}, then don't insert any gravatar images.  If @code{t}, then insert
+both images.  If @code{author} or @code{committer}, then insert only the
+respective image.
+
+If you have customized the option @code{magit-revision-headers-format}
+and want to insert the images then you might also have to specify
+where to do so.  In that case the value has to be a cons-cell of
+two regular expressions.  The car specifies where to insert the
+author's image.  The top half of the image is inserted right
+after the matched text, the bottom half on the next line in the
+same column.  The cdr specifies where to insert the committer's
+image, accordingly.  Either the car or the cdr may be nil."
+@end defopt
+
+@defopt magit-revision-use-hash-sections
+Whether to turn hashes inside the commit message into sections.
+
+If non-nil, then hashes inside the commit message are turned into
+@code{commit} sections.  There is a trade off to be made between
+performance and reliability:
+
+@itemize
+@item
+@code{slow} calls git for every word to be absolutely sure.
+@item
+@code{quick} skips words less than seven characters long.
+@item
+@code{quicker} additionally skips words that don't contain a number.
+@item
+@code{quickest} uses all words that are at least seven characters long
+and which contain at least one number as well as at least one
+letter.
+@end itemize
+
+If nil, then no hashes are turned into sections, but you can still
+visit the commit at point using "RET".
+@end defopt
+
+The diffs shown in the revision buffer may be automatically restricted
+to a subset of the changed files.  If the revision buffer is displayed
+from a log buffer, the revision buffer will share the same file
+restriction as that log buffer (also see the command
+@code{magit-diff-toggle-file-filter}).
+
+@defopt magit-revision-filter-files-on-follow
+Whether showing a commit from a log buffer honors the log's file
+filter when the log arguments include @code{--follow}.
+
+When this option is nil, displaying a commit from a log ignores the
+log's file filter if the log arguments include @code{--follow}.  Doing so
+avoids showing an empty diff in revision buffers for commits before
+a rename event.  In such cases, the @code{--patch} argument of the log
+transient can be used to show the file-restricted diffs inline.
+
+Set this option to non-nil to keep the log's file restriction even
+if @code{--follow} is present in the log arguments.
+@end defopt
+
+If the revision buffer is not displayed from a log buffer, the file
+restriction is determined as usual (see @ref{Transient Arguments and Buffer Variables}).
+
+@node Ediffing
+@section Ediffing
+
+This section describes how to enter Ediff from Magit buffers.  For
+information on how to use Ediff itself, see @ref{Top,,,ediff,}.
+
+@table @asis
+@item @kbd{e} (@code{magit-ediff-dwim})
+@kindex e
+@findex magit-ediff-dwim
+Compare, stage, or resolve using Ediff.
+
+This command tries to guess what file, and what commit or range the
+user wants to compare, stage, or resolve using Ediff.  It might only
+be able to guess either the file, or range/commit, in which case
+the user is asked about the other.  It might not always guess right,
+in which case the appropriate @code{magit-ediff-*} command has to be used
+explicitly.  If it cannot read the user's mind at all, then it asks
+the user for a command to run.
+
+@item @kbd{E} (@code{magit-ediff})
+@kindex E
+@findex magit-ediff
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+@item @kbd{E r} (@code{magit-ediff-compare})
+@kindex E r
+@findex magit-ediff-compare
+Compare two revisions of a file using Ediff.
+
+If the region is active, use the revisions on the first and last
+line of the region.  With a prefix argument, instead of diffing the
+revisions, choose a revision to view changes along, starting at the
+common ancestor of both revisions (i.e., use a "@dots{}"  range).
+
+@item @kbd{E m} (@code{magit-ediff-resolve-rest})
+@kindex E m
+@findex magit-ediff-resolve-rest
+This command allows you to resolve outstanding conflicts in the file
+at point using Ediff.  If there is no file at point or if it doesn't
+have any unmerged changes, then this command prompts for a file.
+
+Provided that the value of @code{merge.conflictstyle} is @code{diff3}, you can
+view the file's merge-base revision using @code{/} in the Ediff control
+buffer.
+
+The A, B and Ancestor buffers are constructed from the conflict
+markers in the worktree file.  Because you and/or Git may have
+already resolved some conflicts, that means that these buffers
+may not contain the actual versions from the respective blobs.
+
+@item @kbd{E M} (@code{magit-ediff-resolve-all})
+@kindex E M
+@findex magit-ediff-resolve-all
+This command allows you to resolve all conflicts in the file at
+point using Ediff.  If there is no file at point or if it doesn't
+have any unmerged changes, then this command prompts for a file.
+
+Provided that the value of @code{merge.conflictstyle} is @code{diff3}, you can
+view the file's merge-base revision using @code{/} in the Ediff control
+buffer.
+
+First the file in the worktree is moved aside, appending the suffix
+@samp{.ORIG}, so that you could later go back to that version.  Then it is
+reconstructed from the two sides of the conflict and the merge-base,
+if available.
+
+It would be nice if the worktree file were just used as-is, but
+Ediff does not support that.  This means that all conflicts, that
+Git has already resolved, are restored.  On the other hand Ediff
+also tries to resolve conflicts, and in many cases Ediff and Git
+should produce similar results.
+
+However if you have already resolved some conflicts manually, then
+those changes are discarded (though you can recover them from the
+backup file).  In such cases @code{magit-ediff-resolve-rest} might be more
+suitable.
+
+The advantage that this command has over @code{magit-ediff-resolve-rest}
+is that the A, B and Ancestor buffers correspond to blobs from the
+respective commits, allowing you to inspect a side in context and
+to use Magit commands in these buffers to do so.  Blame and log
+commands are particularly useful here.
+
+@item @kbd{E t} (@code{magit-git-mergetool})
+@kindex E t
+@findex magit-git-mergetool
+This command does not actually use Ediff.  While it serves the same
+purpose as @samp{magit-ediff-resolve-rest}, it uses @samp{git mergetool --gui} to
+resolve conflicts.
+
+With a prefix argument this acts as a transient prefix command,
+allowing the user to select the mergetool and change some settings.
+
+@item @kbd{E s} (@code{magit-ediff-stage})
+@kindex E s
+@findex magit-ediff-stage
+Stage and unstage changes to a file using Ediff, defaulting to the
+file at point.
+
+@item @kbd{E u} (@code{magit-ediff-show-unstaged})
+@kindex E u
+@findex magit-ediff-show-unstaged
+Show unstaged changes to a file using Ediff.
+
+@item @kbd{E i} (@code{magit-ediff-show-staged})
+@kindex E i
+@findex magit-ediff-show-staged
+Show staged changes to a file using Ediff.
+
+@item @kbd{E w} (@code{magit-ediff-show-working-tree})
+@kindex E w
+@findex magit-ediff-show-working-tree
+Show changes in a file between @code{HEAD} and working tree using Ediff.
+
+@item @kbd{E c} (@code{magit-ediff-show-commit})
+@kindex E c
+@findex magit-ediff-show-commit
+Show changes to a file introduced by a commit using Ediff.
+
+@item @kbd{E z} (@code{magit-ediff-show-stash})
+@kindex E z
+@findex magit-ediff-show-stash
+Show changes to a file introduced by a stash using Ediff.
+@end table
+
+@defopt magit-ediff-dwim-resolve-function
+This option controls which function @code{magit-ediff-dwim} uses to resolve
+conflicts.  One of @code{magit-ediff-resolve-rest}, @code{magit-ediff-resolve-all}
+or @code{magit-git-mergetool}; which are all discussed above.
+@end defopt
+
+@defopt magit-ediff-dwim-show-on-hunks
+This option controls what command @code{magit-ediff-dwim} calls when
+point is on uncommitted hunks.  When nil, always run
+@code{magit-ediff-stage}.  Otherwise, use @code{magit-ediff-show-staged} and
+@code{magit-ediff-show-unstaged} to show staged and unstaged changes,
+respectively.
+@end defopt
+
+@defopt magit-ediff-show-stash-with-index
+This option controls whether @code{magit-ediff-show-stash} includes a
+buffer containing the file's state in the index at the time the
+stash was created.  This makes it possible to tell which changes in
+the stash were staged.
+@end defopt
+
+@defopt magit-ediff-quit-hook
+This hook is run after quitting an Ediff session that was created
+using a Magit command.  The hook functions are run inside the Ediff
+control buffer, and should not change the current buffer.
+
+This is similar to @code{ediff-quit-hook} but takes the needs of Magit into
+account.  The regular @code{ediff-quit-hook} is ignored by Ediff sessions
+that were created using a Magit command.
+@end defopt
+
+@node References Buffer
+@section References Buffer
+
+@table @asis
+@item @kbd{y} (@code{magit-show-refs})
+@kindex y
+@findex magit-show-refs
+This command lists branches and tags in a dedicated buffer.
+
+However if this command is invoked again from this buffer or if it
+is invoked with a prefix argument, then it acts as a transient
+prefix command, which binds the following suffix commands and some
+infix arguments.
+@end table
+
+All of the following suffix commands list exactly the same branches
+and tags.  The only difference the optional feature that can be
+enabled by changing the value of @code{magit-refs-show-commit-count} (see
+below).  These commands specify a different branch or commit against
+which all the other references are compared.
+
+@table @asis
+@item @kbd{y y} (@code{magit-show-refs-head})
+@kindex y y
+@findex magit-show-refs-head
+This command lists branches and tags in a dedicated buffer.  Each
+reference is being compared with @code{HEAD}.
+
+@item @kbd{y c} (@code{magit-show-refs-current})
+@kindex y c
+@findex magit-show-refs-current
+This command lists branches and tags in a dedicated buffer.  Each
+reference is being compared with the current branch or @code{HEAD} if it
+is detached.
+
+@item @kbd{y o} (@code{magit-show-refs-other})
+@kindex y o
+@findex magit-show-refs-other
+This command lists branches and tags in a dedicated buffer.  Each
+reference is being compared with a branch read from the user.
+
+@item @kbd{y r} (@code{magit-refs-set-show-commit-count})
+@kindex y r
+@findex magit-refs-set-show-commit-count
+This command changes for which refs the commit count is shown.
+@end table
+
+@defopt magit-refs-show-commit-count
+Whether to show commit counts in Magit-Refs mode buffers.
+
+@itemize
+@item
+@code{all} Show counts for branches and tags.
+@item
+@code{branch} Show counts for branches only.
+@item
+@code{nil} Never show counts.
+@end itemize
+
+The default is @code{nil} because anything else can be very expensive.
+@end defopt
+
+@defopt magit-refs-pad-commit-counts
+Whether to pad all commit counts on all sides in Magit-Refs mode
+buffers.
+
+If this is nil, then some commit counts are displayed right next to
+one of the branches that appear next to the count, without any space
+in between.  This might look bad if the branch name faces look too
+similar to @code{magit-dimmed}.
+
+If this is non-nil, then spaces are placed on both sides of all
+commit counts.
+@end defopt
+
+@defopt magit-refs-show-remote-prefix
+Whether to show the remote prefix in lists of remote branches.
+
+Showing the prefix is redundant because the name of the remote is
+already shown in the heading preceding the list of its branches.
+@end defopt
+
+@defopt magit-refs-primary-column-width
+Width of the primary column in `magit-refs-mode' buffers.  The
+primary column is the column that contains the name of the branch
+that the current row is about.
+
+If this is an integer, then the column is that many columns wide.
+Otherwise it has to be a cons-cell of two integers.  The first
+specifies the minimal width, the second the maximal width.  In that
+case the actual width is determined using the length of the names of
+the shown local branches.  (Remote branches and tags are not taken
+into account when calculating to optimal width.)
+@end defopt
+
+@defopt magit-refs-focus-column-width
+Width of the focus column in `magit-refs-mode' buffers.
+
+The focus column is the first column, which marks one branch
+(usually the current branch) as the focused branch using @code{*} or @code{@@}.
+For each other reference, this column optionally shows how many
+commits it is ahead of the focused branch and @code{<}, or if it isn't
+ahead then the commits it is behind and @code{>}, or if it isn't behind
+either, then a @code{=}.
+
+This column may also display only @code{*} or @code{@@} for the focused branch, in
+which case this option is ignored.  Use @code{L v} to change the verbosity
+of this column.
+@end defopt
+
+@defopt magit-refs-margin
+This option specifies whether the margin is initially shown in
+Magit-Refs mode buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+@defopt magit-refs-margin-for-tags
+This option specifies whether to show information about tags in the
+margin.  This is disabled by default because it is slow if there are
+many tags.
+@end defopt
+
+The following variables control how individual refs are displayed.  If
+you change one of these variables (especially the "%c" part), then you
+should also change the others to keep things aligned.  The following
+%-sequences are supported:
+
+@itemize
+@item
+@code{%a} Number of commits this ref has over the one we compare to.
+@item
+@code{%b} Number of commits the ref we compare to has over this one.
+@item
+@code{%c} Number of commits this ref has over the one we compare to.  For
+the ref which all other refs are compared this is instead "@@", if
+it is the current branch, or "#" otherwise.
+@item
+@code{%C} For the ref which all other refs are compared this is "@@", if it
+is the current branch, or "#" otherwise.  For all other refs " ".
+@item
+@code{%h} Hash of this ref's tip.
+@item
+@code{%m} Commit summary of the tip of this ref.
+@item
+@code{%n} Name of this ref.
+@item
+@code{%u} Upstream of this local branch.
+@item
+@code{%U} Upstream of this local branch and additional local vs. upstream
+information.
+@end itemize
+
+@defopt magit-refs-filter-alist
+The purpose of this option is to forgo displaying certain refs
+based on their name.  If you want to not display any refs of a
+certain type, then you should remove the appropriate function
+from @code{magit-refs-sections-hook} instead.
+
+This alist controls which tags and branches are omitted from being
+displayed in @code{magit-refs-mode} buffers.  If it is @code{nil}, then all refs
+are displayed (subject to @code{magit-refs-sections-hook}).
+
+All keys are tried in order until one matches.  Then its value is
+used and subsequent elements are ignored.  If the value is non-nil,
+then the reference is displayed, otherwise it is not.  If no element
+matches, then the reference is displayed.
+
+A key can either be a regular expression that the refname has to
+match, or a function that takes the refname as only argument and
+returns a boolean.  A remote branch such as "origin/master" is
+displayed as just "master", however for this comparison the
+former is used.
+@end defopt
+
+@table @asis
+@item @kbd{@key{RET}} (@code{magit-visit-ref})
+@kindex RET
+@findex magit-visit-ref
+This command visits the reference or revision at point in another
+buffer.  If there is no revision at point or with a prefix argument
+then it prompts for a revision.
+
+This command behaves just like @code{magit-show-commit} as described above,
+except if point is on a reference in a @code{magit-refs-mode} buffer, in
+which case the behavior may be different, but only if you have
+customized the option @code{magit-visit-ref-behavior}.
+@end table
+
+@defopt magit-visit-ref-behavior
+This option controls how @code{magit-visit-ref} behaves in @code{magit-refs-mode}
+buffers.
+
+By default @code{magit-visit-ref} behaves like @code{magit-show-commit}, in all
+buffers, including @code{magit-refs-mode} buffers.  When the type of the
+section at point is @code{commit} then "RET" is bound to @code{magit-show-commit},
+and when the type is either @code{branch} or @code{tag} then it is bound to
+@code{magit-visit-ref}.
+
+"RET" is one of Magit's most essential keys and at least by default
+it should behave consistently across all of Magit, especially
+because users quickly learn that it does something very harmless; it
+shows more information about the thing at point in another buffer.
+
+However "RET" used to behave differently in @code{magit-refs-mode} buffers,
+doing surprising things, some of which cannot really be described as
+"visit this thing".  If you've grown accustomed this behavior, you
+can restore it by adding one or more of the below symbols to the
+value of this option.  But keep in mind that by doing so you don't
+only introduce inconsistencies, you also lose some functionality and
+might have to resort to @code{M-x magit-show-commit} to get it back.
+
+@code{magit-visit-ref} looks for these symbols in the order in which they
+are described here.  If the presence of a symbol applies to the
+current situation, then the symbols that follow do not affect the
+outcome.
+
+@itemize
+@item
+@code{focus-on-ref}
+
+With a prefix argument update the buffer to show commit counts
+and lists of cherry commits relative to the reference at point
+instead of relative to the current buffer or @code{HEAD}.
+
+Instead of adding this symbol, consider pressing "C-u y o RET".
+
+@item
+@code{create-branch}
+
+If point is on a remote branch, then create a new local branch
+with the same name, use the remote branch as its upstream, and
+then check out the local branch.
+
+Instead of adding this symbol, consider pressing "b c RET RET",
+like you would do in other buffers.
+
+@item
+@code{checkout-any}
+
+Check out the reference at point.  If that reference is a tag
+or a remote branch, then this results in a detached @code{HEAD}.
+
+Instead of adding this symbol, consider pressing "b b RET",
+like you would do in other buffers.
+
+@item
+@code{checkout-branch}
+
+Check out the local branch at point.
+
+Instead of adding this symbol, consider pressing "b b RET",
+like you would do in other buffers.
+@end itemize
+@end defopt
+
+@menu
+* References Sections::
+@end menu
+
+@node References Sections
+@subsection References Sections
+
+The contents of references buffers is controlled using the hook
+@code{magit-refs-sections-hook}.  See @ref{Section Hooks} to learn about such hooks
+and how to customize them.  All of the below functions are members of
+the default value.  Note that it makes much less sense to customize
+this hook than it does for the respective hook used for the status
+buffer.
+
+@defopt magit-refs-sections-hook
+Hook run to insert sections into a references buffer.
+@end defopt
+
+@defun magit-insert-local-branches
+Insert sections showing all local branches.
+@end defun
+
+@defun magit-insert-remote-branches
+Insert sections showing all remote-tracking branches.
+@end defun
+
+@defun magit-insert-tags
+Insert sections showing all tags.
+@end defun
+
+@node Bisecting
+@section Bisecting
+
+Also see 
+@ifinfo
+@ref{git-bisect,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-bisect">git-bisect(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-bisect(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{B} (@code{magit-bisect})
+@kindex B
+@findex magit-bisect
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+@end table
+
+When bisecting is not in progress, then the transient features the
+following suffix commands.
+
+@table @asis
+@item @kbd{B B} (@code{magit-bisect-start})
+@kindex B B
+@findex magit-bisect-start
+Start a bisect session.
+
+Bisecting a bug means to find the commit that introduced it.
+This command starts such a bisect session by asking for a known
+good commit and a known bad commit.  If you're bisecting a change
+that isn't a regression, you can select alternate terms that are
+conceptually more fitting than "bad" and "good", but the infix
+arguments to do so are disabled by default.
+
+@item @kbd{B s} (@code{magit-bisect-run})
+@kindex B s
+@findex magit-bisect-run
+Bisect automatically by running commands after each step.
+@end table
+
+When bisecting in progress, then the transient instead features the
+following suffix commands.
+
+@table @asis
+@item @kbd{B b} (@code{magit-bisect-bad})
+@kindex B b
+@findex magit-bisect-bad
+Mark the current commit as bad.  Use this after you have asserted
+that the commit does contain the bug in question.
+
+@item @kbd{B g} (@code{magit-bisect-good})
+@kindex B g
+@findex magit-bisect-good
+Mark the current commit as good.  Use this after you have asserted
+that the commit does not contain the bug in question.
+
+@item @kbd{B m} (@code{magit-bisect-mark})
+@kindex B m
+@findex magit-bisect-mark
+Mark the current commit with one of the bisect terms.  This command
+provides an alternative to @code{magit-bisect-bad} and
+@code{magit-bisect-good} and is useful when using terms other than "bad"
+and "good".  This suffix is disabled by default.
+
+@item @kbd{B k} (@code{magit-bisect-skip})
+@kindex B k
+@findex magit-bisect-skip
+Skip the current commit.  Use this if for some reason the current
+commit is not a good one to test.  This command lets Git choose a
+different one.
+
+@item @kbd{B r} (@code{magit-bisect-reset})
+@kindex B r
+@findex magit-bisect-reset
+After bisecting, cleanup bisection state and return to original
+@code{HEAD}.
+@end table
+
+By default the status buffer shows information about the ongoing
+bisect session.
+
+@defopt magit-bisect-show-graph
+This option controls whether a graph is displayed for the log of
+commits that still have to be bisected.
+@end defopt
+
+@node Visiting Files and Blobs
+@section Visiting Files and Blobs
+
+Magit provides several commands that visit a file or blob (the version
+of a file that is stored in a certain commit).  Actually it provides
+several @strong{groups} of such commands and the several @strong{variants} within each
+group.
+
+Also see @ref{Commands for Buffers Visiting Files}.
+
+@menu
+* General-Purpose Visit Commands::
+* Visiting Files and Blobs from a Diff::
+@end menu
+
+@node General-Purpose Visit Commands
+@subsection General-Purpose Visit Commands
+
+These commands can be used anywhere to open any blob.  Currently no
+keys are bound to these commands by default, but that is likely to
+change.
+
+@deffn Command magit-find-file
+This command reads a filename and revision from the user and visits
+the respective blob in a buffer.  The buffer is displayed in the
+selected window.
+@end deffn
+
+@deffn Command magit-find-file-other-window
+This command reads a filename and revision from the user and visits
+the respective blob in a buffer.  The buffer is displayed in another
+window.
+@end deffn
+
+@deffn Command magit-find-file-other-frame
+This command reads a filename and revision from the user and visits
+the respective blob in a buffer.  The buffer is displayed in another
+frame.
+@end deffn
+
+@node Visiting Files and Blobs from a Diff
+@subsection Visiting Files and Blobs from a Diff
+
+These commands can only be used when point is inside a diff.
+
+@table @asis
+@item @kbd{@key{RET}} (@code{magit-diff-visit-file})
+@kindex RET
+@findex magit-diff-visit-file
+This command visits the appropriate version of the file that the
+diff at point is about.
+
+This commands visits the worktree version of the appropriate file.
+The location of point inside the diff determines which file is being
+visited.  The visited version depends on what changes the diff is
+about.
+
+@enumerate
+@item
+If the diff shows uncommitted changes (i.e., staged or unstaged
+changes), then visit the file in the working tree (i.e., the
+same "real" file that @code{find-file} would visit.  In all other
+cases visit a "blob" (i.e., the version of a file as stored
+in some commit).
+
+@item
+If point is on a removed line, then visit the blob for the
+first parent of the commit that removed that line, i.e., the
+last commit where that line still exists.
+
+@item
+If point is on an added or context line, then visit the blob
+that adds that line, or if the diff shows from more than a
+single commit, then visit the blob from the last of these
+commits.
+@end enumerate
+
+In the file-visiting buffer this command goes to the line that
+corresponds to the line that point is on in the diff.
+
+The buffer is displayed in the selected window.  With a prefix
+argument the buffer is displayed in another window instead.
+@end table
+
+@defopt magit-diff-visit-previous-blob
+This option controls whether @code{magit-diff-visit-file} may visit the
+previous blob.  When this is @code{t} (the default) and point is on a
+removed line in a diff for a committed change, then
+@code{magit-diff-visit-file} visits the blob from the last revision which
+still had that line.
+
+Currently this is only supported for committed changes, for staged
+and unstaged changes @code{magit-diff-visit-file} always visits the file in
+the working tree.
+@end defopt
+
+@table @asis
+@item @kbd{C-<return>} (@code{magit-diff-visit-file-worktree})
+@kindex C-<return>
+@findex magit-diff-visit-file-worktree
+This command visits the worktree version of the appropriate file.
+The location of point inside the diff determines which file is being
+visited.  Unlike @code{magit-diff-visit-file} it always visits the "real"
+file in the working tree, i.e the "current version" of the file.
+
+In the file-visiting buffer this command goes to the line that
+corresponds to the line that point is on in the diff.  Lines that
+were added or removed in the working tree, the index and other
+commits in between are automatically accounted for.
+
+The buffer is displayed in the selected window.  With a prefix
+argument the buffer is displayed in another window instead.
+@end table
+
+Variants of the above two commands exist that instead visit the file
+in another window or in another frame.  If you prefer such behavior,
+then you may want to change the above key bindings, but note that the
+above commands also use another window when invoked with a prefix
+argument.
+
+@deffn Command magit-diff-visit-file-other-window
+@end deffn
+@deffn Command magit-diff-visit-file-other-frame
+@end deffn
+@deffn Command magit-diff-visit-worktree-file-other-window
+@end deffn
+@deffn Command magit-diff-visit-worktree-file-other-frame
+@end deffn
+
+@node Blaming
+@section Blaming
+
+Also see 
+@ifinfo
+@ref{git-blame,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-blame">git-blame(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-blame(1) manpage.
+@end iftex
+
+To start blaming, invoke the @code{magit-file-dispatch} transient prefix
+command.  When using the default key bindings, that can be done
+by pressing @code{C-c M-g}.  When using the recommended bindings, this
+command is instead bound to @code{C-c f}.  Also see @ref{Global Bindings}.
+
+The blaming suffix commands can be invoked directly from the file
+dispatch transient.  However if you want to set an infix argument,
+then you have to enter the blaming sub-prefix first.
+
+@table @asis
+@item @kbd{C-c f B} (@code{magit-blame})
+@itemx @kbd{C-c f b} (@code{magit-blame-addition})
+@itemx @kbd{C-c f B b}
+@itemx @kbd{C-c f r} (@code{magit-blame-removal})
+@itemx @kbd{C-c f B r}
+@itemx @kbd{C-c f f} (@code{magit-blame-reverse})
+@itemx @kbd{C-c f B f}
+@itemx @kbd{C-c f e} (@code{magit-blame-echo})
+@itemx @kbd{C-c f B e}
+@itemx @kbd{C-c f q} (@code{magit-blame-quit})
+@itemx @kbd{C-c f B q}
+@kindex C-c f B
+@kindex C-c f b
+@kindex C-c f B b
+@kindex C-c f r
+@kindex C-c f B r
+@kindex C-c f f
+@kindex C-c f B f
+@kindex C-c f e
+@kindex C-c f B e
+@kindex C-c f q
+@kindex C-c f B q
+@findex magit-blame
+@findex magit-blame-addition
+@findex magit-blame-removal
+@findex magit-blame-reverse
+@findex magit-blame-echo
+@findex magit-blame-quit
+Each of these commands is documented individually right below,
+alongside their default key bindings.  The bindings shown above
+are the recommended bindings, which you can enable by following
+the instructions in @ref{Global Bindings}.
+
+@item @kbd{C-c M-g B} (@code{magit-blame})
+@kindex C-c M-g B
+@findex magit-blame
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+@end table
+
+Note that not all of the following suffixes are available at all
+times.  For example if @code{magit-blame-mode} is not enabled, then the
+command whose purpose is to turn off that mode would not be of any
+use and therefore isn't available.
+
+@table @asis
+@item @kbd{C-c M-g b} (@code{magit-blame-addition})
+@itemx @kbd{C-c M-g B b}
+@kindex C-c M-g b
+@kindex C-c M-g B b
+@findex magit-blame-addition
+This command augments each line or chunk of lines in the current
+file-visiting or blob-visiting buffer with information about what
+commits last touched these lines.
+
+If the buffer visits a revision of that file, then history up to
+that revision is considered.  Otherwise, the file's full history is
+considered, including uncommitted changes.
+
+If Magit-Blame mode is already turned on in the current buffer then
+blaming is done recursively, by visiting REVISION:FILE (using
+@code{magit-find-file}), where REVISION is a parent of the revision that
+added the current line or chunk of lines.
+
+@item @kbd{C-c M-g r} (@code{magit-blame-removal})
+@itemx @kbd{C-c M-g B r}
+@kindex C-c M-g r
+@kindex C-c M-g B r
+@findex magit-blame-removal
+This command augments each line or chunk of lines in the current
+blob-visiting buffer with information about the revision that
+removes it.  It cannot be used in file-visiting buffers.
+
+Like @code{magit-blame-addition}, this command can be used recursively.
+
+@item @kbd{C-c M-g f} (@code{magit-blame-reverse})
+@itemx @kbd{C-c M-g B f}
+@kindex C-c M-g f
+@kindex C-c M-g B f
+@findex magit-blame-reverse
+This command augments each line or chunk of lines in the current
+file-visiting or blob-visiting buffer with information about the
+last revision in which a line still existed.
+
+Like @code{magit-blame-addition}, this command can be used recursively.
+
+@item @kbd{C-c M-g e} (@code{magit-blame-echo})
+@itemx @kbd{C-c M-g B e}
+@kindex C-c M-g e
+@kindex C-c M-g B e
+@findex magit-blame-echo
+This command is like @code{magit-blame-addition} except that it doesn't
+turn on @code{read-only-mode} and that it initially uses the visualization
+style specified by option @code{magit-blame-echo-style}.
+@end table
+
+The following key bindings are available when Magit-Blame mode is
+enabled and Read-Only mode is not enabled.  These commands are also
+available in other buffers; here only the behavior is described that
+is relevant in file-visiting buffers that are being blamed.
+
+@table @asis
+@item @kbd{C-c M-g q} (@code{magit-blame-quit})
+@itemx @kbd{C-c M-g B q}
+@kindex C-c M-g q
+@kindex C-c M-g B q
+@findex magit-blame-quit
+This command turns off Magit-Blame mode.  If the buffer was created
+during a recursive blame, then it also kills the buffer.
+
+@item @kbd{@key{RET}} (@code{magit-show-commit})
+@kindex RET
+@findex magit-show-commit
+This command shows the commit that last touched the line at point.
+
+@item @kbd{@key{SPC}} (@code{magit-diff-show-or-scroll-up})
+@kindex SPC
+@findex magit-diff-show-or-scroll-up
+This command updates the commit buffer.
+
+This either shows the commit that last touched the line at point in
+the appropriate buffer, or if that buffer is already being displayed
+in the current frame and if that buffer contains information about
+that commit, then the buffer is scrolled up instead.
+
+@item @kbd{@key{DEL}} (@code{magit-diff-show-or-scroll-down})
+@kindex DEL
+@findex magit-diff-show-or-scroll-down
+This command updates the commit buffer.
+
+This either shows the commit that last touched the line at point in
+the appropriate buffer, or if that buffer is already being displayed
+in the current frame and if that buffer contains information about
+that commit, then the buffer is scrolled down instead.
+@end table
+
+The following key bindings are available when both Magit-Blame mode
+and Read-Only mode are enabled.
+
+@table @asis
+@item @kbd{b} (@code{magit-blame})
+@kindex b
+@findex magit-blame
+See above.
+
+@item @kbd{n} (@code{magit-blame-next-chunk})
+@kindex n
+@findex magit-blame-next-chunk
+This command moves to the next chunk.
+
+@item @kbd{N} (@code{magit-blame-next-chunk-same-commit})
+@kindex N
+@findex magit-blame-next-chunk-same-commit
+This command moves to the next chunk from the same commit.
+
+@item @kbd{p} (@code{magit-blame-previous-chunk})
+@kindex p
+@findex magit-blame-previous-chunk
+This command moves to the previous chunk.
+
+@item @kbd{P} (@code{magit-blame-previous-chunk-same-commit})
+@kindex P
+@findex magit-blame-previous-chunk-same-commit
+This command moves to the previous chunk from the same commit.
+
+@item @kbd{q} (@code{magit-blame-quit})
+@kindex q
+@findex magit-blame-quit
+This command turns off Magit-Blame mode.  If the buffer was created
+during a recursive blame, then it also kills the buffer.
+
+@item @kbd{M-w} (@code{magit-blame-copy-hash})
+@kindex M-w
+@findex magit-blame-copy-hash
+This command saves the hash of the current chunk's commit to the
+kill ring.
+
+When the region is active, the command saves the region's content
+instead of the hash, like @code{kill-ring-save} would.
+
+@item @kbd{c} (@code{magit-blame-cycle-style})
+@kindex c
+@findex magit-blame-cycle-style
+This command changes how blame information is visualized in the
+current buffer by cycling through the styles specified using the
+option @code{magit-blame-styles}.
+@end table
+
+Blaming is also controlled using the following options.
+
+@defopt magit-blame-styles
+This option defines a list of styles used to visualize blame
+information.  For now see its doc-string to learn more.
+@end defopt
+
+@defopt magit-blame-echo-style
+This option specifies the blame visualization style used by the
+command @code{magit-blame-echo}.  This must be a symbol that is used as the
+identifier for one of the styles defined in @code{magit-blame-styles}.
+@end defopt
+
+@defopt magit-blame-time-format
+This option specifies the format string used to display times when
+showing blame information.
+@end defopt
+
+@defopt magit-blame-read-only
+This option controls whether blaming a buffer also makes temporarily
+read-only.
+@end defopt
+
+@defopt magit-blame-disable-modes
+This option lists incompatible minor-modes that should be disabled
+temporarily when a buffer contains blame information.  They are
+enabled again when the buffer no longer shows blame information.
+@end defopt
+
+@defopt magit-blame-goto-chunk-hook
+This hook is run when moving between chunks.
+@end defopt
+
+@node Manipulating
+@chapter Manipulating
+
+@menu
+* Creating Repository::
+* Cloning Repository::
+* Staging and Unstaging::
+* Applying::
+* Committing::
+* Branching::
+* Merging::
+* Resolving Conflicts::
+* Rebasing::
+* Cherry Picking::
+* Resetting::
+* Stashing::
+@end menu
+
+@node Creating Repository
+@section Creating Repository
+
+@table @asis
+@item @kbd{I} (@code{magit-init})
+@kindex I
+@findex magit-init
+This command initializes a repository and then shows the status
+buffer for the new repository.
+
+If the directory is below an existing repository, then the user has
+to confirm that a new one should be created inside.  If the
+directory is the root of the existing repository, then the user has
+to confirm that it should be reinitialized.
+@end table
+
+@node Cloning Repository
+@section Cloning Repository
+
+To clone a remote or local repository use @code{C}, which is bound to the
+command @code{magit-clone}.  This command either act as a transient prefix
+command, which binds several infix arguments and suffix commands, or
+it can invoke @code{git clone} directly, depending on whether a prefix
+argument is used and on the value of @code{magit-clone-always-transient}.
+
+@defopt magit-clone-always-transient
+This option controls whether the command @code{magit-clone} always acts as
+a transient prefix command, regardless of whether a prefix argument
+is used or not.  If @code{t}, then that command always acts as a transient
+prefix.  If @code{nil}, then a prefix argument has to be used for it to act
+as a transient.
+@end defopt
+
+@table @asis
+@item @kbd{C} (@code{magit-clone})
+@kindex C
+@findex magit-clone
+This command either acts as a transient prefix command as described
+above or does the same thing as @code{transient-clone-regular} as described
+below.
+
+If it acts as a transient prefix, then it binds the following suffix
+commands and several infix arguments.
+
+@item @kbd{C C} (@code{magit-clone-regular})
+@kindex C C
+@findex magit-clone-regular
+This command creates a regular clone of an existing repository.
+The repository and the target directory are read from the user.
+
+@item @kbd{C s} (@code{magit-clone-shallow})
+@kindex C s
+@findex magit-clone-shallow
+This command creates a shallow clone of an existing repository.
+The repository and the target directory are read from the user.
+By default the depth of the cloned history is a single commit,
+but with a prefix argument the depth is read from the user.
+
+@item @kbd{C >} (@code{magit-clone-sparse})
+@kindex C >
+@findex magit-clone-sparse
+This command creates a clone of an existing repository and
+initializes a sparse checkout, avoiding a checkout of the full
+working tree.  To add more directories, use the
+@code{magit-sparse-checkout} transient (see @ref{Sparse checkouts}).
+
+@item @kbd{C b} (@code{magit-clone-bare})
+@kindex C b
+@findex magit-clone-bare
+This command creates a bare clone of an existing repository.
+The repository and the target directory are read from the user.
+
+@item @kbd{C m} (@code{magit-clone-mirror})
+@kindex C m
+@findex magit-clone-mirror
+This command creates a mirror of an existing repository.
+The repository and the target directory are read from the user.
+@end table
+
+The following suffixes are disabled by default. See
+@ref{Enabling and Disabling Suffixes,,,transient,} for how to enable them.
+
+@table @asis
+@item @kbd{C d} (@code{magit-clone-shallow-since})
+@kindex C d
+@findex magit-clone-shallow-since
+This command creates a shallow clone of an existing repository.
+Only commits that were committed after a date are cloned, which
+is read from the user.  The repository and the target directory
+are also read from the user.
+
+@item @kbd{C e} (@code{magit-clone-shallow-exclude})
+@kindex C e
+@findex magit-clone-shallow-exclude
+This command creates a shallow clone of an existing repository.
+This reads a branch or tag from the user.  Commits that are
+reachable from that are not cloned.  The repository and the target
+directory are also read from the user.
+@end table
+
+@defopt magit-clone-set-remote-head
+This option controls whether cloning causes the reference
+@code{refs/remotes/<remote>/HEAD} to be created in the clone.  The default
+is to delete the reference after running @code{git clone}, which insists on
+creating it.  This is because the reference has not been found to be
+particularly useful as it is not automatically updated when the @code{HEAD}
+of the remote changes.  Setting this option to @code{t} preserves Git's
+default behavior of creating the reference.
+@end defopt
+
+@defopt magit-clone-set-remote.pushDefault
+This option controls whether the value of the Git variable
+@code{remote.pushDefault} is set after cloning.
+
+@itemize
+@item
+If @code{t}, then it is always set without asking.
+@item
+If @code{ask}, then the users are asked every time they clone a
+repository.
+@item
+If @code{nil}, then it is never set.
+@end itemize
+@end defopt
+
+@defopt magit-clone-default-directory
+This option control the default directory name used when reading the
+destination for a cloning operation.
+
+@itemize
+@item
+If @code{nil} (the default), then the value of @code{default-directory} is used.
+@item
+If a directory, then that is used.
+@item
+If a function, then that is called with the remote url as the only
+argument and the returned value is used.
+@end itemize
+@end defopt
+
+@defopt magit-clone-name-alist
+This option maps regular expressions, which match repository names,
+to repository urls, making it possible for users to enter short
+names instead of urls when cloning repositories.
+
+Each element has the form @code{(REGEXP HOSTNAME USER)}.  When the user
+enters a name when a cloning command asks for a name or url, then
+that is looked up in this list.  The first element whose REGEXP
+matches is used.
+
+The format specified by option @code{magit-clone-url-format} is used to
+turn the name into an url, using HOSTNAME and the repository name.
+If the provided name contains a slash, then that is used.  Otherwise
+if the name omits the owner of the repository, then the default user
+specified in the matched entry is used.
+
+If USER contains a dot, then it is treated as a Git variable and the
+value of that is used as the username.  Otherwise it is used as the
+username itself.
+@end defopt
+
+@defopt magit-clone-url-format
+The format specified by this option is used when turning repository
+names into urls.  @code{%h} is the hostname and @code{%n} is the repository
+name, including the name of the owner.  The value can be a string
+(representing a single static format) or an alist with elements
+@code{(HOSTNAME . FORMAT)} mapping hostnames to formats.  When an alist
+is used, the @code{t} key represents the default format.
+
+Example of a single format string:
+
+@lisp
+(setq magit-clone-url-format
+      "git@@%h:%n.git")
+@end lisp
+
+Example of by-hostname format strings:
+
+@lisp
+(setq magit-clone-url-format
+      '(("git.example.com" . "git@@%h:~%n")
+        (nil . "git@@%h:%n.git")))
+@end lisp
+@end defopt
+
+@defopt magit-post-clone-hook
+Hook run after the Git process has successfully finished cloning the
+repository.  When the hook is called, @code{default-directory} is
+let-bound to the directory where the repository has been cloned.
+@end defopt
+
+@node Staging and Unstaging
+@section Staging and Unstaging
+
+Like Git, Magit can of course stage and unstage complete files.
+Unlike Git, it also allows users to gracefully un-/stage
+individual hunks and even just part of a hunk.  To stage individual
+hunks and parts of hunks using Git directly, one has to use the very
+modal and rather clumsy interface of a @code{git add --interactive} session.
+
+With Magit, on the other hand, one can un-/stage individual hunks by
+just moving point into the respective section inside a diff displayed
+in the status buffer or a separate diff buffer and typing @code{s} or @code{u}.  To
+operate on just parts of a hunk, mark the changes that should be
+un-/staged using the region and then press the same key that would be
+used to un-/stage.  To stage multiple files or hunks at once use a
+region that starts inside the heading of such a section and ends
+inside the heading of a sibling section of the same type.
+
+Besides staging and unstaging, Magit also provides several other
+"apply variants" that can also operate on a file, multiple files at
+once, a hunk, multiple hunks at once, and on parts of a hunk.  These
+apply variants are described in the next section.
+
+You can also use Ediff to stage and unstage.  See @ref{Ediffing}.
+
+@table @asis
+@item @kbd{s} (@code{magit-stage})
+@kindex s
+@findex magit-stage
+Add the change at point to the staging area.
+
+With a prefix argument and an untracked file (or files) at point,
+stage the file but not its content.  This makes it possible to stage
+only a subset of the new file's changes.
+
+@item @kbd{S} (@code{magit-stage-modified})
+@kindex S
+@findex magit-stage-modified
+Stage all changes to files modified in the worktree.  Stage all new
+content of tracked files and remove tracked files that no longer
+exist in the working tree from the index also.  With a prefix
+argument also stage previously untracked (but not ignored) files.
+
+@item @kbd{u} (@code{magit-unstage})
+@kindex u
+@findex magit-unstage
+Remove the change at point from the staging area.
+
+Only staged changes can be unstaged.  But by default this command
+performs an action that is somewhat similar to unstaging, when it is
+called on a committed change: it reverses the change in the index
+but not in the working tree.
+
+@item @kbd{U} (@code{magit-unstage-all})
+@kindex U
+@findex magit-unstage-all
+Remove all changes from the staging area.
+@end table
+
+@defopt magit-unstage-committed
+This option controls whether @code{magit-unstage} "unstages" committed
+changes by reversing them in the index but not the working tree.
+The alternative is to raise an error.
+@end defopt
+
+@table @asis
+@item @kbd{M-x magit-reverse-in-index}
+@findex magit-reverse-in-index
+This command reverses the committed change at point in the index but
+not the working tree.  By default no key is bound directly to this
+command, but it is indirectly called when @code{u} (@code{magit-unstage}) is
+pressed on a committed change.
+
+This allows extracting a change from @code{HEAD}, while leaving it in the
+working tree, so that it can later be committed using a separate
+commit.  A typical workflow would be:
+
+@enumerate
+@item
+Optionally make sure that there are no uncommitted changes.
+@item
+Visit the @code{HEAD} commit and navigate to the change that should
+not have been included in that commit.
+@item
+Type @code{u} (@code{magit-unstage}) to reverse it in the index.
+This assumes that @code{magit-unstage-committed} is non-nil.
+@item
+Type @code{c e} to extend @code{HEAD} with the staged changes,
+including those that were already staged before.
+@item
+Optionally stage the remaining changes using @code{s} or @code{S} and then
+type @code{c c} to create a new commit.
+@end enumerate
+
+@item @kbd{M-x magit-reset-index}
+@findex magit-reset-index
+Reset the index to some commit.  The commit is read from the user
+and defaults to the commit at point.  If there is no commit at
+point, then it defaults to @code{HEAD}.
+@end table
+
+@menu
+* Staging from File-Visiting Buffers::
+@end menu
+
+@node Staging from File-Visiting Buffers
+@subsection Staging from File-Visiting Buffers
+
+Fine-grained un-/staging has to be done from the status or a diff
+buffer, but it's also possible to un-/stage all changes made to the
+file visited in the current buffer right from inside that buffer.
+
+@table @asis
+@item @kbd{M-x magit-stage-file}
+@findex magit-stage-file
+When invoked inside a file-visiting buffer, then stage all changes
+to that file.  In a Magit buffer, stage the file at point if any.
+Otherwise prompt for a file to be staged.  With a prefix argument
+always prompt the user for a file, even in a file-visiting buffer or
+when there is a file section at point.
+
+@item @kbd{M-x magit-unstage-file}
+@findex magit-unstage-file
+When invoked inside a file-visiting buffer, then unstage all changes
+to that file.  In a Magit buffer, unstage the file at point if any.
+Otherwise prompt for a file to be unstaged.  With a prefix argument
+always prompt the user for a file, even in a file-visiting buffer or
+when there is a file section at point.
+@end table
+
+@node Applying
+@section Applying
+
+Magit provides several "apply variants": stage, unstage, discard,
+reverse, and "regular apply".  At least when operating on a hunk they
+are all implemented using @code{git apply}, which is why they are called
+"apply variants".
+
+@itemize
+@item
+Stage.  Apply a change from the working tree to the index.  The change
+also remains in the working tree.
+
+@item
+Unstage.  Remove a change from the index.  The change remains in the
+working tree.
+
+@item
+Discard.  On a staged change, remove it from the working tree and the
+index.  On an unstaged change, remove it from the working tree only.
+
+@item
+Reverse.  Reverse a change in the working tree.  Both committed and
+staged changes can be reversed.  Unstaged changes cannot be
+reversed.  Discard them instead.
+
+@item
+Apply.  Apply a change to the working tree.  Both committed and staged
+changes can be applied.  Unstaged changes cannot be applied - as
+they already have been applied.
+@end itemize
+
+The previous section described the staging and unstaging commands.
+What follows are the commands which implement the remaining apply
+variants.
+
+@table @asis
+@item @kbd{a} (@code{magit-apply})
+@kindex a
+@findex magit-apply
+Apply the change at point to the working tree.
+
+With a prefix argument fallback to a 3-way merge.  Doing so causes
+the change to be applied to the index as well.
+
+@item @kbd{k} (@code{magit-discard})
+@kindex k
+@findex magit-discard
+Remove the change at point from the working tree.
+
+On a hunk or file with unresolved conflicts prompt which side to
+keep (while discarding the other).  If point is within the text
+of a side, then keep that side without prompting.
+
+@item @kbd{v} (@code{magit-reverse})
+@kindex v
+@findex magit-reverse
+Reverse the change at point in the working tree.
+
+With a prefix argument fallback to a 3-way merge.  Doing so causes
+the change to be applied to the index as well.
+@end table
+
+With a prefix argument all apply variants attempt a 3-way merge when
+appropriate (i.e., when @code{git apply} is used internally).
+
+@node Committing
+@section Committing
+
+When the user initiates a commit, Magit calls @code{git commit} without any
+arguments, so Git has to get it from the user.  It creates the file
+@code{.git/COMMIT_EDITMSG} and then opens that file in an editor.  Magit
+arranges for that editor to be the Emacsclient.  Once the user
+finishes the editing session, the Emacsclient exits and Git creates the
+commit using the file's content as message.
+
+@menu
+* Initiating a Commit::
+* Editing Commit Messages::
+@end menu
+
+@node Initiating a Commit
+@subsection Initiating a Commit
+
+Also see 
+@ifinfo
+@ref{git-commit,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-commit">git-commit(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-commit(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{c} (@code{magit-commit})
+@kindex c
+@findex magit-commit
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{c c} (@code{magit-commit-create})
+@kindex c c
+@findex magit-commit-create
+Create a new commit on @code{HEAD}.  With a prefix argument amend to the
+commit at @code{HEAD} instead.
+
+@item @kbd{c a} (@code{magit-commit-amend})
+@kindex c a
+@findex magit-commit-amend
+Amend the last commit.
+
+@item @kbd{c e} (@code{magit-commit-extend})
+@kindex c e
+@findex magit-commit-extend
+Amend the last commit, without editing the message.  With a prefix
+argument keep the committer date, otherwise change it.  The option
+@code{magit-commit-extend-override-date} can be used to inverse the meaning
+of the prefix argument.
+
+Non-interactively respect the optional OVERRIDE-DATE argument and
+ignore the option.
+
+@item @kbd{c w} (@code{magit-commit-reword})
+@kindex c w
+@findex magit-commit-reword
+Reword the last commit, ignoring staged changes.  With a prefix
+argument keep the committer date, otherwise change it.  The option
+@code{magit-commit-reword-override-date} can be used to inverse the meaning
+of the prefix argument.
+
+Non-interactively respect the optional OVERRIDE-DATE argument and
+ignore the option.
+
+@item @kbd{c f} (@code{magit-commit-fixup})
+@kindex c f
+@findex magit-commit-fixup
+Create a fixup commit.
+
+With a prefix argument the target commit has to be confirmed.
+Otherwise the commit at point may be used without confirmation
+depending on the value of option @code{magit-commit-squash-confirm}.
+
+@item @kbd{c F} (@code{magit-commit-instant-fixup})
+@kindex c F
+@findex magit-commit-instant-fixup
+Create a fixup commit and instantly rebase.
+
+@item @kbd{c s} (@code{magit-commit-squash})
+@kindex c s
+@findex magit-commit-squash
+Create a squash commit, without editing the squash message.
+
+With a prefix argument the target commit has to be confirmed.
+Otherwise the commit at point may be used without confirmation
+depending on the value of option @code{magit-commit-squash-confirm}.
+
+@item @kbd{c S} (@code{magit-commit-instant-squash})
+@kindex c S
+@findex magit-commit-instant-squash
+Create a squash commit and instantly rebase.
+
+@item @kbd{c A} (@code{magit-commit-augment})
+@kindex c A
+@findex magit-commit-augment
+Create a squash commit, editing the squash message.
+
+With a prefix argument the target commit has to be confirmed.
+Otherwise the commit at point may be used without confirmation
+depending on the value of option @code{magit-commit-squash-confirm}.
+@end table
+
+@defopt magit-commit-ask-to-stage
+Whether to ask to stage all unstaged changes when committing and nothing is
+staged.
+@end defopt
+
+@defopt magit-commit-show-diff
+Whether the relevant diff is automatically shown when committing.
+@end defopt
+
+@defopt magit-commit-extend-override-date
+Whether using @code{magit-commit-extend} changes the committer date.
+@end defopt
+
+@defopt magit-commit-reword-override-date
+Whether using @code{magit-commit-reword} changes the committer date.
+@end defopt
+
+@defopt magit-commit-squash-confirm
+Whether the commit targeted by squash and fixup has to be confirmed.
+When non-nil then the commit at point (if any) is used as default
+choice.  Otherwise it has to be confirmed.  This option only affects
+@code{magit-commit-squash} and @code{magit-commit-fixup}.  The "instant" variants
+always require confirmation because making an error while using
+those is harder to recover from.
+@end defopt
+
+@defopt magit-post-commit-hook
+Hook run after creating a commit without the user editing a message.
+
+This hook is run by @code{magit-refresh} if @code{this-command} is a member
+of @code{magit-post-commit-hook-commands}.  This only includes commands
+named @code{magit-commit-*} that do @strong{not} require that the user edits
+the commit message in a buffer.
+
+Also see @code{git-commit-post-finish-hook}.
+@end defopt
+
+@defopt magit-commit-diff-inhibit-same-window
+Whether to inhibit use of same window when showing diff while
+committing.
+
+When writing a commit, then a diff of the changes to be committed
+is automatically shown.  The idea is that the diff is shown in a
+different window of the same frame and for most users that just
+works.  In other words most users can completely ignore this
+option because its value doesn't make a difference for them.
+
+However for users who configured Emacs to never create a new
+window even when the package explicitly tries to do so, then
+displaying two new buffers necessarily means that the first is
+immediately replaced by the second.  In our case the message
+buffer is immediately replaced by the diff buffer, which is of
+course highly undesirable.
+
+A workaround is to suppress this user configuration in this
+particular case.  Users have to explicitly opt-in by toggling
+this option.  We cannot enable the workaround unconditionally
+because that again causes issues for other users: if the frame
+is too tiny or the relevant settings too aggressive, then the
+diff buffer would end up being displayed in a new frame.
+
+Also see @uref{https://github.com/magit/magit/issues/4132}.
+@end defopt
+
+@node Editing Commit Messages
+@subsection Editing Commit Messages
+
+After initiating a commit as described in the previous section, two new
+buffers appear.  One shows the changes that are about to be committed,
+while the other is used to write the message.
+
+Commit messages are edited in an edit session - in the background @code{git}
+is waiting for the editor, in our case @code{emacsclient}, to save the commit
+message in a file (in most cases @code{.git/COMMIT_EDITMSG}) and then return.
+If the editor returns with a non-zero exit status then @code{git} does not
+create the commit.  So the most important commands are those for
+finishing and aborting the commit.
+
+@table @asis
+@item @kbd{C-c C-c} (@code{with-editor-finish})
+@kindex C-c C-c
+@findex with-editor-finish
+Finish the current editing session by returning with exit code 0.
+Git then creates the commit using the message it finds in the file.
+
+@item @kbd{C-c C-k} (@code{with-editor-cancel})
+@kindex C-c C-k
+@findex with-editor-cancel
+Cancel the current editing session by returning with exit code 1.
+Git then cancels the commit, but leaves the file untouched.
+@end table
+
+In addition to being used by @code{git commit}, messages may also be stored
+in a ring that persists until Emacs is closed.  By default the message
+is stored at the beginning and the end of an edit session (regardless
+of whether the session is finished successfully or was canceled).  It
+is sometimes useful to bring back messages from that ring.
+
+@table @asis
+@item @kbd{C-c M-s} (@code{git-commit-save-message})
+@kindex C-c M-s
+@findex git-commit-save-message
+Save the current buffer content to the commit message ring.
+
+@item @kbd{M-p} (@code{git-commit-prev-message})
+@kindex M-p
+@findex git-commit-prev-message
+Cycle backward through the commit message ring, after saving the
+current message to the ring.  With a numeric prefix ARG, go back
+ARG comments.
+
+@item @kbd{M-n} (@code{git-commit-next-message})
+@kindex M-n
+@findex git-commit-next-message
+Cycle forward through the commit message ring, after saving the
+current message to the ring.  With a numeric prefix ARG, go back
+ARG comments.
+@end table
+
+By default the diff for the changes that are about to be committed are
+automatically shown when invoking the commit.  To prevent that, remove
+@code{magit-commit-diff} from @code{server-switch-hook}.
+
+When amending to an existing commit it may be useful to show either
+the changes that are about to be added to that commit or to show those
+changes alongside those that have already been committed.
+
+@table @asis
+@item @kbd{C-c C-d} (@code{magit-diff-while-committing})
+@kindex C-c C-d
+@findex magit-diff-while-committing
+While committing, show the changes that are about to be committed.
+While amending, invoking the command again toggles between showing
+just the new changes or all the changes that will be committed.
+@end table
+
+@menu
+* Using the Revision Stack::
+* Commit Pseudo Headers::
+* Commit Mode and Hooks::
+* Commit Message Conventions::
+@end menu
+
+@node Using the Revision Stack
+@unnumberedsubsubsec Using the Revision Stack
+
+@table @asis
+@item @kbd{C-c C-w} (@code{magit-pop-revision-stack})
+@kindex C-c C-w
+@findex magit-pop-revision-stack
+This command inserts a representation of a revision into the current
+buffer.  It can be used inside buffers used to write commit messages
+but also in other buffers such as buffers used to edit emails or
+ChangeLog files.
+
+By default this command pops the revision which was last added to
+the @code{magit-revision-stack} and inserts it into the current buffer
+according to @code{magit-pop-revision-stack-format}.  Revisions can be put
+on the stack using @code{magit-copy-section-value} and
+@code{magit-copy-buffer-revision}.
+
+If the stack is empty or with a prefix argument it instead reads a
+revision in the minibuffer.  By using the minibuffer history this
+allows selecting an item which was popped earlier or to insert an
+arbitrary reference or revision without first pushing it onto the
+stack.
+
+When reading the revision from the minibuffer, then it might not
+be possible to guess the correct repository.  When this command
+is called inside a repository (e.g., while composing a commit
+message), then that repository is used.  Otherwise (e.g., while
+composing an email) then the repository recorded for the top
+element of the stack is used (even though we insert another
+revision).  If not called inside a repository and with an empty
+stack, or with two prefix arguments, then read the repository in
+the minibuffer too.
+@end table
+
+@defopt magit-pop-revision-stack-format
+This option controls how the command @code{magit-pop-revision-stack}
+inserts a revision into the current buffer.
+
+The entries on the stack have the format @code{(HASH TOPLEVEL)} and this
+option has the format @code{(POINT-FORMAT EOB-FORMAT INDEX-REGEXP)}, all
+of which may be nil or a string (though either one of EOB-FORMAT
+or POINT-FORMAT should be a string, and if INDEX-REGEXP is
+non-nil, then the two formats should be too).
+
+First INDEX-REGEXP is used to find the previously inserted entry,
+by searching backward from point.  The first submatch must match
+the index number.  That number is incremented by one, and becomes
+the index number of the entry to be inserted.  If you don't want
+to number the inserted revisions, then use nil for INDEX-REGEXP@.
+
+If INDEX-REGEXP is non-nil then both POINT-FORMAT and EOB-FORMAT
+should contain \"%N\", which is replaced with the number that was
+determined in the previous step.
+
+Both formats, if non-nil and after removing %N, are then expanded
+using @code{git show --format=FORMAT ...} inside TOPLEVEL@.
+
+The expansion of POINT-FORMAT is inserted at point, and the
+expansion of EOB-FORMAT is inserted at the end of the buffer (if the
+buffer ends with a comment, then it is inserted right before that).
+@end defopt
+
+@node Commit Pseudo Headers
+@unnumberedsubsubsec Commit Pseudo Headers
+
+Some projects use pseudo headers in commit messages.  Magit colorizes
+such headers and provides some commands to insert such headers.
+
+@defopt git-commit-known-pseudo-headers
+A list of Git pseudo headers to be highlighted.
+@end defopt
+
+@table @asis
+@item @kbd{C-c C-i} (@code{git-commit-insert-pseudo-header})
+@kindex C-c C-i
+@findex git-commit-insert-pseudo-header
+Insert a commit message pseudo header.
+
+@item @kbd{C-c C-a} (@code{git-commit-ack})
+@kindex C-c C-a
+@findex git-commit-ack
+Insert a header acknowledging that you have looked at the commit.
+
+@item @kbd{C-c C-r} (@code{git-commit-review})
+@kindex C-c C-r
+@findex git-commit-review
+Insert a header acknowledging that you have reviewed the commit.
+
+@item @kbd{C-c C-s} (@code{git-commit-signoff})
+@kindex C-c C-s
+@findex git-commit-signoff
+Insert a header to sign off the commit.
+
+@item @kbd{C-c C-t} (@code{git-commit-test})
+@kindex C-c C-t
+@findex git-commit-test
+Insert a header acknowledging that you have tested the commit.
+
+@item @kbd{C-c C-o} (@code{git-commit-cc})
+@kindex C-c C-o
+@findex git-commit-cc
+Insert a header mentioning someone who might be interested.
+
+@item @kbd{C-c C-p} (@code{git-commit-reported})
+@kindex C-c C-p
+@findex git-commit-reported
+Insert a header mentioning the person who reported the issue being
+fixed by the commit.
+
+@item @kbd{C-c M-i} (@code{git-commit-suggested})
+@kindex C-c M-i
+@findex git-commit-suggested
+Insert a header mentioning the person who suggested the change.
+@end table
+
+@node Commit Mode and Hooks
+@unnumberedsubsubsec Commit Mode and Hooks
+
+@code{git-commit-mode} is a minor mode that is only used to establish certain
+key bindings.  This makes it possible to use an arbitrary major mode
+in buffers used to edit commit messages.  It is even possible to use
+different major modes in different repositories, which is useful when
+different projects impose different commit message conventions.
+
+@defopt git-commit-major-mode
+The value of this option is the major mode used to edit Git commit
+messages.
+@end defopt
+
+Because @code{git-commit-mode} is a minor mode, we don't use its mode hook
+to setup the buffer, except for the key bindings.  All other setup
+happens in the function @code{git-commit-setup}, which among other things runs
+the hook @code{git-commit-setup-hook}.
+
+@defopt git-commit-setup-hook
+Hook run at the end of @code{git-commit-setup}.
+@end defopt
+
+@noindent
+The following functions are suitable for this hook:
+
+@defun git-commit-save-message
+Save the current buffer content to the commit message ring.
+@end defun
+
+@defun git-commit-setup-changelog-support
+After this function is called, ChangeLog entries are treated as
+paragraphs.
+@end defun
+
+@defun git-commit-turn-on-auto-fill
+Turn on @code{auto-fill-mode}.
+@end defun
+
+@defun git-commit-turn-on-flyspell
+Turn on Flyspell mode.  Also prevent comments from being checked and
+finally check current non-comment text.
+@end defun
+
+@defun git-commit-propertize-diff
+Propertize the diff shown inside the commit message buffer.  Git
+inserts such diffs into the commit message template when the
+@code{--verbose} argument is used.  @code{magit-commit} by default does not offer
+that argument because the diff that is shown in a separate buffer is
+more useful.  But some users disagree, which is why this function
+exists.
+@end defun
+
+@defun bug-reference-mode
+Hyperlink bug references in the buffer.
+@end defun
+
+@defun with-editor-usage-message
+Show usage information in the echo area.
+@end defun
+
+@defopt git-commit-post-finish-hook
+Hook run after the user finished writing a commit message.
+
+This hook is only run after pressing @code{C-c C-c} in a buffer used to
+edit a commit message.  If a commit is created without the user
+typing a message into a buffer, then this hook is not run.
+
+This hook is not run until the new commit has been created.  If
+doing so takes Git longer than one second, then this hook isn't run
+at all.  For certain commands such as @code{magit-rebase-continue} this
+hook is never run because doing so would lead to a race condition.
+
+This hook is only run if @code{magit} is available.
+
+Also see @code{magit-post-commit-hook}.
+@end defopt
+
+@node Commit Message Conventions
+@unnumberedsubsubsec Commit Message Conventions
+
+Git-Commit highlights certain violations of commonly accepted commit
+message conventions.  Certain violations even cause Git-Commit to ask
+you to confirm that you really want to do that.  This nagging can of
+course be turned off, but the result of doing that usually is that
+instead of some code it's now the human who is reviewing your commits
+who has to waste some time telling you to fix your commits.
+
+@defopt git-commit-summary-max-length
+The intended maximal length of the summary line of commit messages.
+Characters beyond this column are colorized to indicate that this
+preference has been violated.
+@end defopt
+
+@defopt git-commit-finish-query-functions
+List of functions called to query before performing commit.
+
+The commit message buffer is current while the functions are called.
+If any of them returns nil, then the commit is not performed and the
+buffer is not killed.  The user should then fix the issue and try
+again.
+
+The functions are called with one argument.  If it is non-nil then
+that indicates that the user used a prefix argument to force
+finishing the session despite issues.  Functions should usually
+honor this wish and return non-nil.
+
+By default the only member is @code{git-commit-check-style-conventions}.
+@end defopt
+
+@defun git-commit-check-style-conventions
+This function checks for violations of certain basic style
+conventions.  For each violation it asks users if they want to
+proceed anyway.
+@end defun
+
+@defopt git-commit-style-convention-checks
+This option controls what conventions the function by the same name
+tries to enforce.  The value is a list of self-explanatory symbols
+identifying certain conventions; @code{non-empty-second-line} and
+@code{overlong-summary-line}.
+@end defopt
+
+@node Branching
+@section Branching
+
+@menu
+* The Two Remotes::
+* Branch Commands::
+* Branch Git Variables::
+* Auxiliary Branch Commands::
+@end menu
+
+@node The Two Remotes
+@subsection The Two Remotes
+
+The upstream branch of some local branch is the branch into which the
+commits on that local branch should eventually be merged, usually
+something like @code{origin/master}.  For the @code{master} branch itself the
+upstream branch and the branch it is being pushed to, are usually the
+same remote branch.  But for a feature branch the upstream branch and
+the branch it is being pushed to should differ.
+
+The commits on feature branches too should @emph{eventually} end up in a
+remote branch such as @code{origin/master} or @code{origin/maint}.  Such a branch
+should therefore be used as the upstream.  But feature branches
+shouldn't be pushed directly to such branches.  Instead a feature
+branch @code{my-feature} is usually pushed to @code{my-fork/my-feature} or if you
+are a contributor @code{origin/my-feature}.  After the new feature has been
+reviewed, the maintainer merges the feature into @code{master}.  And finally
+@code{master} (not @code{my-feature} itself) is pushed to @code{origin/master}.
+
+But new features seldom are perfect on the first try, and so feature
+branches usually have to be reviewed, improved, and re-pushed several
+times.  Pushing should therefore be easy to do, and for that reason
+many Git users have concluded that it is best to use the remote branch
+to which the local feature branch is being pushed as its upstream.
+
+But luckily Git has long ago gained support for a push-remote which
+can be configured separately from the upstream branch, using the
+variables @code{branch.<name>.pushRemote} and @code{remote.pushDefault}.  So we no
+longer have to choose which of the two remotes should be used as "the
+remote".
+
+Each of the fetching, pulling, and pushing transient commands features
+three suffix commands that act on the current branch and some other
+branch.  Of these, @code{p} is bound to a command which acts on the
+push-remote, @code{u} is bound to a command which acts on the upstream, and @code{e}
+is bound to a command which acts on any other branch.  The status
+buffer shows unpushed and unpulled commits for both the push-remote
+and the upstream.
+
+It's fairly simple to configure these two remotes.  The values of all
+the variables that are related to fetching, pulling, and pushing (as
+well as some other branch-related variables) can be inspected and
+changed using the command @code{magit-branch-configure}, which is available
+from many transient prefix commands that deal with branches.  It is
+also possible to set the push-remote or upstream while pushing (see
+@ref{Pushing}).
+
+@node Branch Commands
+@subsection Branch Commands
+
+The transient prefix command @code{magit-branch} is used to create and
+checkout branches, and to make changes to existing branches.  It is
+not used to fetch, pull, merge, rebase, or push branches, i.e., this
+command deals with branches themselves, not with the commits reachable
+from them.  Those features are available from separate transient
+command.
+
+@table @asis
+@item @kbd{b} (@code{magit-branch})
+@kindex b
+@findex magit-branch
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+By default it also binds and displays the values of some
+branch-related Git variables and allows changing their values.
+@end table
+
+@defopt magit-branch-direct-configure
+This option controls whether the transient command @code{magit-branch} can
+be used to directly change the values of Git variables.  This defaults
+to @code{t} (to avoid changing key bindings).  When set to @code{nil}, then no
+variables are displayed by that transient command, and its suffix
+command @code{magit-branch-configure} has to be used instead to view and
+change branch related variables.
+@end defopt
+
+@table @asis
+@item @kbd{b C} (@code{magit-branch-configure})
+@itemx @kbd{f C}
+@itemx @kbd{F C}
+@itemx @kbd{P C}
+@kindex b C
+@kindex f C
+@kindex F C
+@kindex P C
+@findex magit-branch-configure
+This transient prefix command binds commands that set the value of
+branch-related variables and displays them in a temporary buffer
+until the transient is exited.
+
+With a prefix argument, this command always prompts for a branch.
+
+Without a prefix argument this depends on whether it was invoked as
+a suffix of @code{magit-branch} and on the @code{magit-branch-direct-configure}
+option.  If @code{magit-branch} already displays the variables for the
+current branch, then it isn't useful to invoke another transient
+that displays them for the same branch.  In that case this command
+prompts for a branch.
+@end table
+
+The variables are described in @ref{Branch Git Variables}.
+
+@table @asis
+@item @kbd{b b} (@code{magit-checkout})
+@kindex b b
+@findex magit-checkout
+Checkout a revision read in the minibuffer and defaulting to the
+branch or arbitrary revision at point.  If the revision is a local
+branch then that becomes the current branch.  If it is something
+else then @code{HEAD} becomes detached.  Checkout fails if the working tree
+or the staging area contain changes.
+
+@item @kbd{b n} (@code{magit-branch-create})
+@kindex b n
+@findex magit-branch-create
+Create a new branch.  The user is asked for a branch or arbitrary
+revision to use as the starting point of the new branch.  When a
+branch name is provided, then that becomes the upstream branch of
+the new branch.  The name of the new branch is also read in the
+minibuffer.
+
+Also see option @code{magit-branch-prefer-remote-upstream}.
+
+@item @kbd{b c} (@code{magit-branch-and-checkout})
+@kindex b c
+@findex magit-branch-and-checkout
+This command creates a new branch like @code{magit-branch-create}, but then
+also checks it out.
+
+Also see option @code{magit-branch-prefer-remote-upstream}.
+
+@item @kbd{b l} (@code{magit-branch-checkout})
+@kindex b l
+@findex magit-branch-checkout
+This command checks out an existing or new local branch.  It reads a
+branch name from the user offering all local branches and a subset
+of remote branches as candidates.  Remote branches for which a local
+branch by the same name exists are omitted from the list of
+candidates.  The user can also enter a completely new branch name.
+
+@itemize
+@item
+If the user selects an existing local branch, then that is checked
+out.
+
+@item
+If the user selects a remote branch, then it creates and checks
+out a new local branch with the same name, and configures the
+selected remote branch as the push target.
+
+@item
+If the user enters a new branch name, then it creates and checks
+that out, after also reading the starting-point from the user.
+@end itemize
+
+In the latter two cases the upstream is also set.  Whether it is set
+to the chosen starting point or something else depends on the value
+of @code{magit-branch-adjust-remote-upstream-alist}.
+
+@item @kbd{b s} (@code{magit-branch-spinoff})
+@kindex b s
+@findex magit-branch-spinoff
+This command creates and checks out a new branch starting at and
+tracking the current branch.  That branch in turn is reset to the
+last commit it shares with its upstream.  If the current branch has
+no upstream or no unpushed commits, then the new branch is created
+anyway and the previously current branch is not touched.
+
+This is useful to create a feature branch after work has already
+began on the old branch (likely but not necessarily "master").
+
+If the current branch is a member of the value of option
+@code{magit-branch-prefer-remote-upstream} (which see), then the current
+branch will be used as the starting point as usual, but the upstream
+of the starting-point may be used as the upstream of the new branch,
+instead of the starting-point itself.
+
+If optional FROM is non-nil, then the source branch is reset
+to @code{FROM~}, instead of to the last commit it shares with its
+upstream.  Interactively, FROM is only ever non-nil, if the
+region selects some commits, and among those commits, FROM is
+the commit that is the fewest commits ahead of the source
+branch.
+
+The commit at the other end of the selection actually does not
+matter, all commits between FROM and @code{HEAD} are moved to the new
+branch.  If FROM is not reachable from @code{HEAD} or is reachable from the
+source branch's upstream, then an error is raised.
+
+@item @kbd{b S} (@code{magit-branch-spinout})
+@kindex b S
+@findex magit-branch-spinout
+This command behaves like @code{magit-branch-spinoff}, except that it does
+not change the current branch.  If there are any uncommitted changes,
+then it behaves exactly like @code{magit-branch-spinoff}.
+
+@item @kbd{b x} (@code{magit-branch-reset})
+@kindex b x
+@findex magit-branch-reset
+This command resets a branch, defaulting to the branch at point, to
+the tip of another branch or any other commit.
+
+When the branch being reset is the current branch, then a hard reset
+is performed.  If there are any uncommitted changes, then the user
+has to confirm the reset because those changes would be lost.
+
+This is useful when you have started work on a feature branch but
+realize it's all crap and want to start over.
+
+When resetting to another branch and a prefix argument is used, then
+the target branch is set as the upstream of the branch that is being
+reset.
+
+@item @kbd{b k} (@code{magit-branch-delete})
+@kindex b k
+@findex magit-branch-delete
+Delete one or multiple branches.  If the region marks multiple
+branches, then offer to delete those.  Otherwise, prompt for a single
+branch to be deleted, defaulting to the branch at point.
+
+Require confirmation when deleting branches is dangerous in some
+way.  Option @code{magit-no-confirm} can be customized to not require
+confirmation in certain cases.  See its docstring to learn why
+confirmation is required by default in certain cases or if a
+prompt is confusing.
+
+@item @kbd{b m} (@code{magit-branch-rename})
+@kindex b m
+@findex magit-branch-rename
+Rename a branch.  The branch and the new name are read in the
+minibuffer.  With prefix argument the branch is renamed even if that
+name conflicts with an existing branch.
+@end table
+
+@defopt magit-branch-read-upstream-first
+When creating a branch, whether to read the upstream branch before
+the name of the branch that is to be created.  The default is @code{t},
+and I recommend you leave it at that.
+@end defopt
+
+@defopt magit-branch-prefer-remote-upstream
+This option specifies whether remote upstreams are favored over
+local upstreams when creating new branches.
+
+When a new branch is created, then the branch, commit, or stash at
+point is suggested as the starting point of the new branch, or if
+there is no such revision at point the current branch.  In either
+case the user may choose another starting point.
+
+If the chosen starting point is a branch, then it may also be set
+as the upstream of the new branch, depending on the value of the
+Git variable `branch.autoSetupMerge'.  By default this is done
+for remote branches, but not for local branches.
+
+You might prefer to always use some remote branch as upstream.
+If the chosen starting point is (1) a local branch, (2) whose
+name matches a member of the value of this option, (3) the
+upstream of that local branch is a remote branch with the same
+name, and (4) that remote branch can be fast-forwarded to the
+local branch, then the chosen branch is used as starting point,
+but its own upstream is used as the upstream of the new branch.
+
+Members of this option's value are treated as branch names that
+have to match exactly unless they contain a character that makes
+them invalid as a branch name.  Recommended characters to use
+to trigger interpretation as a regexp are "*" and "^".  Some
+other characters which you might expect to be invalid, actually
+are not, e.g., ".+$" are all perfectly valid.  More precisely,
+if @code{git check-ref-format --branch STRING} exits with a non-zero
+status, then treat STRING as a regexp.
+
+Assuming the chosen branch matches these conditions you would end
+up with with e.g.:
+
+@example
+feature --upstream--> origin/master
+@end example
+
+instead of
+
+@example
+feature --upstream--> master --upstream--> origin/master
+@end example
+
+Which you prefer is a matter of personal preference.  If you do
+prefer the former, then you should add branches such as @code{master},
+@code{next}, and @code{maint} to the value of this options.
+@end defopt
+
+@defopt magit-branch-adjust-remote-upstream-alist
+The value of this option is an alist of branches to be used as
+the upstream when branching a remote branch.
+
+When creating a local branch from an ephemeral branch located on a
+remote, e.g., a feature or hotfix branch, then that remote branch
+should usually not be used as the upstream branch, since the
+push-remote already allows accessing it and having both the upstream
+and the push-remote reference the same related branch would be
+wasteful.  Instead a branch like "maint" or "master" should be used
+as the upstream.
+
+This option allows specifying the branch that should be used as the
+upstream when branching certain remote branches.  The value is an
+alist of the form @code{((UPSTREAM . RULE)...)}.  The first matching
+element is used, the following elements are ignored.
+
+UPSTREAM is the branch to be used as the upstream for branches
+specified by RULE@.  It can be a local or a remote branch.
+
+RULE can either be a regular expression, matching branches whose
+upstream should be the one specified by UPSTREAM@.  Or it can be a
+list of the only branches that should @strong{not} use UPSTREAM; all other
+branches will.  Matching is done after stripping the remote part of
+the name of the branch that is being branched from.
+
+If you use a finite set of non-ephemeral branches across all your
+repositories, then you might use something like:
+
+@lisp
+(("origin/master" . ("master" "next" "maint")))
+@end lisp
+
+Or if the names of all your ephemeral branches contain a slash,
+at least in some repositories, then a good value could be:
+
+@lisp
+(("origin/master" . "/"))
+@end lisp
+
+Of course you can also fine-tune:
+
+@lisp
+(("origin/maint" . "\\`hotfix/")
+ ("origin/master" . "\\`feature/"))
+@end lisp
+
+UPSTREAM can be a local branch:
+
+@lisp
+(("master" . ("master" "next" "maint")))
+@end lisp
+@end defopt
+
+Because the main branch is no longer almost always named "master"
+you should also account for other common names:
+
+@lisp
+(("main"  . ("main" "master" "next" "maint"))
+ ("master" . ("main" "master" "next" "maint")))
+@end lisp
+
+@deffn Command magit-branch-orphan
+This command creates and checks out a new orphan branch with
+contents from a given revision.
+@end deffn
+
+@deffn Command magit-branch-or-checkout
+This command is a hybrid between @code{magit-checkout} and
+@code{magit-branch-and-checkout} and is intended as a replacement for the
+former in @code{magit-branch}.
+
+It first asks the user for an existing branch or revision.  If the
+user input actually can be resolved as a branch or revision, then it
+checks that out, just like @code{magit-checkout} would.
+
+Otherwise it creates and checks out a new branch using the input as
+its name.  Before doing so it reads the starting-point for the new
+branch.  This is similar to what @code{magit-branch-and-checkout} does.
+
+To use this command instead of @code{magit-checkout} add this to your init
+file:
+
+@lisp
+(transient-replace-suffix 'magit-branch 'magit-checkout
+  '("b" "dwim" magit-branch-or-checkout))
+@end lisp
+@end deffn
+
+@node Branch Git Variables
+@subsection Branch Git Variables
+
+These variables can be set from the transient prefix command
+@code{magit-branch-configure}.  By default they can also be set from
+@code{magit-branch}.  See @ref{Branch Commands}.
+
+@defvar branch.NAME.merge
+Together with @code{branch.NAME.remote} this variable defines the upstream
+branch of the local branch named NAME@.  The value of this variable
+is the full reference of the upstream @emph{branch}.
+@end defvar
+
+@defvar branch.NAME.remote
+Together with @code{branch.NAME.merge} this variable defines the upstream
+branch of the local branch named NAME@.  The value of this variable
+is the name of the upstream @emph{remote}.
+@end defvar
+
+@defvar branch.NAME.rebase
+This variable controls whether pulling into the branch named NAME is
+done by rebasing or by merging the fetched branch.
+
+@itemize
+@item
+When @code{true} then pulling is done by rebasing.
+@item
+When @code{false} then pulling is done by merging.
+@item
+When undefined then the value of @code{pull.rebase} is used.  The default
+of that variable is @code{false}.
+@end itemize
+@end defvar
+
+@defvar branch.NAME.pushRemote
+This variable specifies the remote that the branch named NAME is
+usually pushed to.  The value has to be the name of an existing
+remote.
+
+It is not possible to specify the name of @emph{branch} to push the local
+branch to.  The name of the remote branch is always the same as the
+name of the local branch.
+
+If this variable is undefined but @code{remote.pushDefault} is defined,
+then the value of the latter is used.  By default @code{remote.pushDefault}
+is undefined.
+@end defvar
+
+@defvar branch.NAME.description
+This variable can be used to describe the branch named NAME@.  That
+description is used, e.g., when turning the branch into a series of
+patches.
+@end defvar
+
+The following variables specify defaults which are used if the above
+branch-specific variables are not set.
+
+@defvar pull.rebase
+This variable specifies whether pulling is done by rebasing or by
+merging.  It can be overwritten using @code{branch.NAME.rebase}.
+
+@itemize
+@item
+When @code{true} then pulling is done by rebasing.
+@item
+When @code{false} (the default) then pulling is done by merging.
+@end itemize
+
+Since it is never a good idea to merge the upstream branch into a
+feature or hotfix branch and most branches are such branches, you
+should consider setting this to @code{true}, and @code{branch.master.rebase} to
+@code{false}.
+@end defvar
+
+@defvar remote.pushDefault
+This variable specifies what remote the local branches are usually
+pushed to.  This can be overwritten per branch using
+@code{branch.NAME.pushRemote}.
+@end defvar
+
+The following variables are used during the creation of a branch and
+control whether the various branch-specific variables are
+automatically set at this time.
+
+@defvar branch.autoSetupMerge
+This variable specifies under what circumstances creating a branch
+NAME should result in the variables @code{branch.NAME.merge} and
+@code{branch.NAME.remote} being set according to the starting point used to
+create the branch.  If the starting point isn't a branch, then these
+variables are never set.
+
+@itemize
+@item
+When @code{always} then the variables are set regardless of whether the
+starting point is a local or a remote branch.
+@item
+When @code{true} (the default) then the variables are set when the starting
+point is a remote branch, but not when it is a local branch.
+@item
+When @code{false} then the variables are never set.
+@end itemize
+@end defvar
+
+@defvar branch.autoSetupRebase
+This variable specifies whether creating a branch NAME should result
+in the variable @code{branch.NAME.rebase} being set to @code{true}.
+
+@itemize
+@item
+When @code{always} then the variable is set regardless of whether the
+starting point is a local or a remote branch.
+@item
+When @code{local} then the variable are set when the starting point is a
+local branch, but not when it is a remote branch.
+@item
+When @code{remote} then the variable are set when the starting point is a
+remote branch, but not when it is a local branch.
+@item
+When @code{never} (the default) then the variable is never set.
+@end itemize
+@end defvar
+
+Note that the respective commands always change the repository-local
+values.  If you want to change the global value, which is used when
+the local value is undefined, then you have to do so on the command
+line, e.g.:
+
+@example
+git config --global remote.autoSetupMerge always
+@end example
+
+For more information about these variables you should also see
+@ifinfo
+@ref{git-config,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-config">git-config(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-config(1) manpage.
+@end iftex
+ Also see 
+@ifinfo
+@ref{git-branch,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-branch">git-branch(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-branch(1) manpage.
+@end iftex
+, 
+@ifinfo
+@ref{git-checkout,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-checkout">git-checkout(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-checkout(1) manpage.
+@end iftex
+ and @ref{Pushing}.
+
+@defopt magit-prefer-remote-upstream
+This option controls whether commands that read a branch from the
+user and then set it as the upstream branch, offer a local or a
+remote branch as default completion candidate, when they have the
+choice.
+
+This affects all commands that use @code{magit-read-upstream-branch} or
+@code{magit-read-starting-point}, which includes all commands that change
+the upstream and many which create new branches.
+@end defopt
+
+@node Auxiliary Branch Commands
+@subsection Auxiliary Branch Commands
+
+These commands are not available from the transient @code{magit-branch} by
+default.
+
+@deffn Command magit-branch-shelve
+This command shelves a branch.  This is done by deleting the branch,
+and creating a new reference "refs/shelved/BRANCH-NAME" pointing at
+the same commit as the branch pointed at.  If the deleted branch had
+a reflog, then that is preserved as the reflog of the new reference.
+
+This is useful if you want to move a branch out of sight, but are
+not ready to completely discard it yet.
+@end deffn
+
+@deffn Command magit-branch-unshelve
+This command unshelves a branch that was previously shelved using
+@code{magit-branch-shelve}.  This is done by deleting the reference
+"refs/shelved/BRANCH-NAME" and creating a branch "BRANCH-NAME"
+pointing at the same commit as the deleted reference pointed at.
+If the deleted reference had a reflog, then that is restored as
+the reflog of the branch.
+@end deffn
+
+@node Merging
+@section Merging
+
+Also see 
+@ifinfo
+@ref{git-merge,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-merge">git-merge(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-merge(1) manpage.
+@end iftex
+  For information on how to resolve
+merge conflicts see the next section.
+
+@table @asis
+@item @kbd{m} (@code{magit-merge})
+@kindex m
+@findex magit-merge
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+@end table
+
+When no merge is in progress, then the transient features the
+following suffix commands.
+
+@table @asis
+@item @kbd{m m} (@code{magit-merge-plain})
+@kindex m m
+@findex magit-merge-plain
+This command merges another branch or an arbitrary revision into the
+current branch.  The branch or revision to be merged is read in the
+minibuffer and defaults to the branch at point.
+
+Unless there are conflicts or a prefix argument is used, then the
+resulting merge commit uses a generic commit message, and the user
+does not get a chance to inspect or change it before the commit is
+created.  With a prefix argument this does not actually create the
+merge commit, which makes it possible to inspect how conflicts were
+resolved and to adjust the commit message.
+
+@item @kbd{m e} (@code{magit-merge-editmsg})
+@kindex m e
+@findex magit-merge-editmsg
+This command merges another branch or an arbitrary revision into the
+current branch and opens a commit message buffer, so that the user
+can make adjustments.  The commit is not actually created until the
+user finishes with @code{C-c C-c}.
+
+@item @kbd{m n} (@code{magit-merge-nocommit})
+@kindex m n
+@findex magit-merge-nocommit
+This command merges another branch or an arbitrary revision into the
+current branch, but does not actually create the merge commit.  The
+user can then further adjust the merge, even when automatic conflict
+resolution succeeded and/or adjust the commit message.
+
+@item @kbd{m a} (@code{magit-merge-absorb})
+@kindex m a
+@findex magit-merge-absorb
+This command merges another local branch into the current branch and
+then removes the former.
+
+Before the source branch is merged, it is first force pushed to its
+push-remote, provided the respective remote branch already exists.
+This ensures that the respective pull-request (if any) won't get
+stuck on some obsolete version of the commits that are being merged.
+Finally, if @code{magit-branch-pull-request} was used to create the merged
+branch, then the respective remote branch is also removed.
+
+@item @kbd{m i} (@code{magit-merge-into})
+@kindex m i
+@findex magit-merge-into
+This command merges the current branch into another local branch and
+then removes the former.  The latter becomes the new current branch.
+
+Before the source branch is merged, it is first force pushed to its
+push-remote, provided the respective remote branch already exists.
+This ensures that the respective pull-request (if any) won't get
+stuck on some obsolete version of the commits that are being merged.
+Finally, if @code{magit-branch-pull-request} was used to create the merged
+branch, then the respective remote branch is also removed.
+
+@item @kbd{m s} (@code{magit-merge-squash})
+@kindex m s
+@findex magit-merge-squash
+This command squashes the changes introduced by another branch or an
+arbitrary revision into the current branch.  This only applies the
+changes made by the squashed commits.  No information is preserved
+that would allow creating an actual merge commit.  Instead of this
+command you should probably use a command from the apply transient.
+
+@item @kbd{m p} (@code{magit-merge-preview})
+@kindex m p
+@findex magit-merge-preview
+This command shows a preview of merging another branch or an
+arbitrary revision into the current branch.
+
+Note that commands, that normally change how a diff is displayed, do
+not work in buffers created by this command, because the underlying
+Git command does not support diff arguments.
+@end table
+
+When a merge is in progress, then the transient instead features the
+following suffix commands.
+
+@table @asis
+@item @kbd{m m} (@code{magit-merge})
+@kindex m m
+@findex magit-merge
+After the user resolved conflicts, this command proceeds with the
+merge.  If some conflicts weren't resolved, then this command fails.
+
+@item @kbd{m a} (@code{magit-merge-abort})
+@kindex m a
+@findex magit-merge-abort
+This command aborts the current merge operation.
+@end table
+
+@node Resolving Conflicts
+@section Resolving Conflicts
+
+When merging branches (or otherwise combining or changing history)
+conflicts can occur.  If you edited two completely different parts of
+the same file in two branches and then merge one of these branches
+into the other, then Git can resolve that on its own, but if you edit
+the same area of a file, then a human is required to decide how the
+two versions, or "sides of the conflict", are to be combined into one.
+
+Here we can only provide a brief introduction to the subject and point
+you toward some tools that can help.  If you are new to this, then
+please also consult Git's own documentation as well as other
+resources.
+
+If a file has conflicts and Git cannot resolve them by itself, then it
+puts both versions into the affected file along with special markers
+whose purpose is to denote the boundaries of the unresolved part of
+the file and between the different versions.  These boundary lines
+begin with the strings consisting of seven times the same character,
+one of @code{<}, @code{|}, @code{=} and @code{>}, and are followed by information about the source
+of the respective versions, e.g.:
+
+@example
+<<<<<<< HEAD
+Take the blue pill.
+=======
+Take the red pill.
+>>>>>>> feature
+@end example
+
+In this case you have chosen to take the red pill on one branch and on
+another you picked the blue pill.  Now that you are merging these two
+diverging branches, Git cannot possibly know which pill you want to
+take.
+
+To resolve that conflict you have to create a version of the affected
+area of the file by keeping only one of the sides, possibly by editing
+it in order to bring in the changes from the other side, remove the
+other versions as well as the markers, and then stage the result.  A
+possible resolution might be:
+
+@example
+Take both pills.
+@end example
+
+Often it is useful to see not only the two sides of the conflict but
+also the "original" version from before the same area of the file was
+modified twice on different branches.  Instruct Git to insert that
+version as well by running this command once:
+
+@example
+git config --global merge.conflictStyle diff3
+@end example
+
+The above conflict might then have looked like this:
+
+@example
+<<<<<<< HEAD
+Take the blue pill.
+||||||| merged common ancestors
+Take either the blue or the red pill, but not both.
+=======
+Take the red pill.
+>>>>>>> feature
+@end example
+
+If that were the case, then the above conflict resolution would not
+have been correct, which demonstrates why seeing the original version
+alongside the conflicting versions can be useful.
+
+You can perform the conflict resolution completely by hand, but Emacs
+also provides some packages that help in the process: Smerge, Ediff
+(@ref{Top,,,ediff,}), and Emerge (@ref{Emerge,,,emacs,}).  Magit does not provide
+its own tools for conflict resolution, but it does make using Smerge
+and Ediff more convenient.  (Ediff supersedes Emerge, so you probably
+don't want to use the latter anyway.)
+
+In the Magit status buffer, files with unresolved conflicts are listed
+in the "Unstaged changes" and/or "Staged changes" sections.  They are
+prefixed with the word "unmerged", which in this context essentially
+is a synonym for "unresolved".
+
+Pressing @code{RET} while point is on such a file section shows a buffer
+visiting that file, turns on @code{smerge-mode} in that buffer, and places
+point inside the first area with conflicts.  You should then resolve
+that conflict using regular edit commands and/or Smerge commands.
+
+Unfortunately Smerge does not have a manual, but you can get a list of
+commands and binding @code{C-c ^ C-h} and press @code{RET} while point is on a
+command name to read its documentation.
+
+Normally you would edit one version and then tell Smerge to keep only
+that version.  Use @code{C-c ^ m} (@code{smerge-keep-mine}) to keep the @code{HEAD}
+version or @code{C-c ^ o} (@code{smerge-keep-other}) to keep the version that
+follows "|||||||".  Then use @code{C-c ^ n} to move to the next conflicting
+area in the same file.  Once you are done resolving conflicts, return
+to the Magit status buffer.  The file should now be shown as
+"modified", no longer as "unmerged", because Smerge automatically
+stages the file when you save the buffer after resolving the last
+conflict.
+
+Magit now wraps the mentioned Smerge commands, allowing you to use
+these key bindings without having to go to the file-visiting buffer.
+Additionally @code{k} (@code{magit-discard}) on a hunk with unresolved conflicts
+asks which side to keep or, if point is on a side, then it keeps it
+without prompting.  Similarly @code{k} on a unresolved file ask which side
+to keep.
+
+Alternatively you could use Ediff, which uses separate buffers for the
+different versions of the file.  To resolve conflicts in a file using
+Ediff press @code{e} while point is on such a file in the status buffer.
+
+Ediff can be used for other purposes as well.  For more information on
+how to enter Ediff from Magit, see @ref{Ediffing}.  Explaining how to use
+Ediff is beyond the scope of this manual, instead see @ref{Top,,,ediff,}.
+
+If you are unsure whether you should Smerge or Ediff, then use the
+former.  It is much easier to understand and use, and except for
+truly complex conflicts, the latter is usually overkill.
+
+@node Rebasing
+@section Rebasing
+
+Also see 
+@ifinfo
+@ref{git-rebase,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-rebase">git-rebase(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-rebase(1) manpage.
+@end iftex
+  For information on how to resolve
+conflicts that occur during rebases see the preceding section.
+
+@table @asis
+@item @kbd{r} (@code{magit-rebase})
+@kindex r
+@findex magit-rebase
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+@end table
+
+When no rebase is in progress, then the transient features the
+following suffix commands.
+
+Using one of these commands @emph{starts} a rebase sequence.  Git might then
+stop somewhere along the way, either because you told it to do so, or
+because applying a commit failed due to a conflict.  When that
+happens, then the status buffer shows information about the rebase
+sequence which is in progress in a section similar to a log section.
+See @ref{Information About In-Progress Rebase}.
+
+For information about the upstream and the push-remote, see @ref{The Two Remotes}.
+
+@table @asis
+@item @kbd{r p} (@code{magit-rebase-onto-pushremote})
+@kindex r p
+@findex magit-rebase-onto-pushremote
+This command rebases the current branch onto its push-remote.
+
+With a prefix argument or when the push-remote is either not
+configured or unusable, then let the user first configure the
+push-remote.
+
+@item @kbd{r u} (@code{magit-rebase-onto-upstream})
+@kindex r u
+@findex magit-rebase-onto-upstream
+This command rebases the current branch onto its upstream branch.
+
+With a prefix argument or when the upstream is either not
+configured or unusable, then let the user first configure
+the upstream.
+
+@item @kbd{r e} (@code{magit-rebase-branch})
+@kindex r e
+@findex magit-rebase-branch
+This command rebases the current branch onto a branch read in the
+minibuffer.  All commits that are reachable from head but not from
+the selected branch TARGET are being rebased.
+
+@item @kbd{r s} (@code{magit-rebase-subset})
+@kindex r s
+@findex magit-rebase-subset
+This command starts a non-interactive rebase sequence to transfer
+commits from START to @code{HEAD} onto NEWBASE@.  START has to be selected
+from a list of recent commits.
+@end table
+
+By default Magit uses the @code{--autostash} argument, which causes
+uncommitted changes to be stored in a stash before the rebase begins.
+These changes are restored after the rebase completes and if possible
+the stash is removed.  If the stash does not apply cleanly, then the
+stash is not removed.  In case something goes wrong when resolving
+the conflicts, this allows you to start over.
+
+Even though one of the actions is dedicated to interactive rebases,
+the transient also features the infix argument @code{--interactive}.  This
+can be used to turn one of the other, non-interactive rebase variants
+into an interactive rebase.
+
+For example if you want to clean up a feature branch and at the same
+time rebase it onto @code{master}, then you could use @code{r-iu}.  But we recommend
+that you instead do that in two steps.  First use @code{ri} to cleanup the
+feature branch, and then in a second step @code{ru} to rebase it onto @code{master}.
+That way if things turn out to be more complicated than you thought
+and/or you make a mistake and have to start over, then you only have
+to redo half the work.
+
+Explicitly enabling @code{--interactive} won't have an effect on the
+following commands as they always use that argument anyway, even if it
+is not enabled in the transient.
+
+@table @asis
+@item @kbd{r i} (@code{magit-rebase-interactive})
+@kindex r i
+@findex magit-rebase-interactive
+This command starts an interactive rebase sequence.
+
+@item @kbd{r f} (@code{magit-rebase-autosquash})
+@kindex r f
+@findex magit-rebase-autosquash
+This command combines squash and fixup commits with their intended
+targets.
+
+@item @kbd{r m} (@code{magit-rebase-edit-commit})
+@kindex r m
+@findex magit-rebase-edit-commit
+This command starts an interactive rebase sequence that lets the
+user edit a single older commit.
+
+@item @kbd{r w} (@code{magit-rebase-reword-commit})
+@kindex r w
+@findex magit-rebase-reword-commit
+This command starts an interactive rebase sequence that lets the
+user reword a single older commit.
+
+@item @kbd{r k} (@code{magit-rebase-remove-commit})
+@kindex r k
+@findex magit-rebase-remove-commit
+This command removes a single older commit using rebase.
+@end table
+
+When a rebase is in progress, then the transient instead features
+the following suffix commands.
+
+@table @asis
+@item @kbd{r r} (@code{magit-rebase-continue})
+@kindex r r
+@findex magit-rebase-continue
+This command restart the current rebasing operation.
+
+In some cases this pops up a commit message buffer for you do edit.
+With a prefix argument the old message is reused as-is.
+
+@item @kbd{r s} (@code{magit-rebase-skip})
+@kindex r s
+@findex magit-rebase-skip
+This command skips the current commit and restarts the current
+rebase operation.
+
+@item @kbd{r e} (@code{magit-rebase-edit})
+@kindex r e
+@findex magit-rebase-edit
+This command lets the user edit the todo list of the current rebase
+operation.
+
+@item @kbd{r a} (@code{magit-rebase-abort})
+@kindex r a
+@findex magit-rebase-abort
+This command aborts the current rebase operation, restoring the
+original branch.
+@end table
+
+@menu
+* Editing Rebase Sequences::
+* Information About In-Progress Rebase::
+@end menu
+
+@node Editing Rebase Sequences
+@subsection Editing Rebase Sequences
+
+@table @asis
+@item @kbd{C-c C-c} (@code{with-editor-finish})
+@kindex C-c C-c
+@findex with-editor-finish
+Finish the current editing session by returning with exit code 0.
+Git then uses the rebase instructions it finds in the file.
+
+@item @kbd{C-c C-k} (@code{with-editor-cancel})
+@kindex C-c C-k
+@findex with-editor-cancel
+Cancel the current editing session by returning with exit code 1.
+Git then forgoes starting the rebase sequence.
+
+@item @kbd{@key{RET}} (@code{git-rebase-show-commit})
+@kindex RET
+@findex git-rebase-show-commit
+Show the commit on the current line in another buffer and select
+that buffer.
+
+@item @kbd{@key{SPC}} (@code{git-rebase-show-or-scroll-up})
+@kindex SPC
+@findex git-rebase-show-or-scroll-up
+Show the commit on the current line in another buffer without
+selecting that buffer.  If the revision buffer is already visible in
+another window of the current frame, then instead scroll that window
+up.
+
+@item @kbd{@key{DEL}} (@code{git-rebase-show-or-scroll-down})
+@kindex DEL
+@findex git-rebase-show-or-scroll-down
+Show the commit on the current line in another buffer without
+selecting that buffer.  If the revision buffer is already visible in
+another window of the current frame, then instead scroll that window
+down.
+
+@item @kbd{p} (@code{git-rebase-backward-line})
+@kindex p
+@findex git-rebase-backward-line
+Move to previous line.
+
+@item @kbd{n} (@code{forward-line})
+@kindex n
+@findex forward-line
+Move to next line.
+
+@item @kbd{M-p} (@code{git-rebase-move-line-up})
+@kindex M-p
+@findex git-rebase-move-line-up
+Move the current commit (or command) up.
+
+@item @kbd{M-n} (@code{git-rebase-move-line-down})
+@kindex M-n
+@findex git-rebase-move-line-down
+Move the current commit (or command) down.
+
+@item @kbd{r} (@code{git-rebase-reword})
+@kindex r
+@findex git-rebase-reword
+Edit message of commit on current line.
+
+@item @kbd{e} (@code{git-rebase-edit})
+@kindex e
+@findex git-rebase-edit
+Stop at the commit on the current line.
+
+@item @kbd{s} (@code{git-rebase-squash})
+@kindex s
+@findex git-rebase-squash
+Meld commit on current line into previous commit, and edit message.
+
+@item @kbd{f} (@code{git-rebase-fixup})
+@kindex f
+@findex git-rebase-fixup
+Meld commit on current line into previous commit, discarding the
+current commit's message.
+
+@item @kbd{k} (@code{git-rebase-kill-line})
+@kindex k
+@findex git-rebase-kill-line
+Kill the current action line.
+
+@item @kbd{c} (@code{git-rebase-pick})
+@kindex c
+@findex git-rebase-pick
+Use commit on current line.
+
+@item @kbd{x} (@code{git-rebase-exec})
+@kindex x
+@findex git-rebase-exec
+Insert a shell command to be run after the proceeding commit.
+
+If there already is such a command on the current line, then edit
+that instead.  With a prefix argument insert a new command even when
+there already is one on the current line.  With empty input remove
+the command on the current line, if any.
+
+@item @kbd{b} (@code{git-rebase-break})
+@kindex b
+@findex git-rebase-break
+Insert a break action before the current line, instructing Git to
+return control to the user.
+
+@item @kbd{y} (@code{git-rebase-insert})
+@kindex y
+@findex git-rebase-insert
+Read an arbitrary commit and insert it below current line.
+
+@item @kbd{C-x u} (@code{git-rebase-undo})
+@kindex C-x u
+@findex git-rebase-undo
+Undo some previous changes.  Like @code{undo} but works in read-only
+buffers.
+@end table
+
+@defopt git-rebase-auto-advance
+Whether to move to next line after changing a line.
+@end defopt
+
+@defopt git-rebase-show-instructions
+Whether to show usage instructions inside the rebase buffer.
+@end defopt
+
+@defopt git-rebase-confirm-cancel
+Whether confirmation is required to cancel.
+@end defopt
+
+When a rebase is performed with the @code{--rebase-merges} option, the
+sequence will include a few other types of actions and the following
+commands become relevant.
+
+@table @asis
+@item @kbd{l} (@code{git-rebase-label})
+@kindex l
+@findex git-rebase-label
+This commands inserts a label action or edits the one at point.
+
+@item @kbd{t} (@code{git-rebase-reset})
+@kindex t
+@findex git-rebase-reset
+This command inserts a reset action or edits the one at point.  The
+prompt will offer the labels that are currently present in the
+buffer.
+
+@item @kbd{MM} (@code{git-rebase-merge})
+@kindex MM
+@findex git-rebase-merge
+The command inserts a merge action or edits the one at point.  The
+prompt will offer the labels that are currently present in the
+buffer.  Specifying a message to reuse via @code{-c} or @code{-C} is not
+supported; an editor will always be invoked for the merge.
+
+@item @kbd{Mt} (@code{git-rebase-merge-toggle-editmsg})
+@kindex Mt
+@findex git-rebase-merge-toggle-editmsg
+This command toggles between the @code{-C} and @code{-c} options of the merge
+action at point.  These options both specify a commit whose message
+should be reused.  The lower-case variant instructs Git to invoke
+the editor when creating the merge, allowing the user to edit the
+message.
+@end table
+
+@node Information About In-Progress Rebase
+@subsection Information About In-Progress Rebase
+
+While a rebase sequence is in progress, the status buffer features a
+section that lists the commits that have already been applied as well
+as the commits that still have to be applied.
+
+The commits are split in two halves.  When rebase stops at a commit,
+either because the user has to deal with a conflict or because s/he
+explicitly requested that rebase stops at that commit, then point is
+placed on the commit that separates the two groups, i.e., on @code{HEAD}.
+The commits above it have not been applied yet, while the @code{HEAD} and the
+commits below it have already been applied.  In between these two
+groups of applied and yet-to-be applied commits, there sometimes is a
+commit which has been dropped.
+
+Each commit is prefixed with a word and these words are additionally
+shown in different colors to indicate the status of the commits.
+
+The following colors are used:
+
+@itemize
+@item
+Commits that use the same foreground color as the @code{default} face have
+not been applied yet.
+
+@item
+Yellow commits have some special relationship to the commit rebase
+stopped at.  This is used for the words "join", "goal", "same" and
+"work" (see below).
+
+@item
+Gray commits have already been applied.
+
+@item
+The blue commit is the @code{HEAD} commit.
+
+@item
+The green commit is the commit the rebase sequence stopped at.  If
+this is the same commit as @code{HEAD} (e.g., because you haven't done
+anything yet after rebase stopped at the commit, then this commit is
+shown in blue, not green).  There can only be a green @strong{and} a blue
+commit at the same time, if you create one or more new commits after
+rebase stops at a commit.
+
+@item
+Red commits have been dropped.  They are shown for reference only,
+e.g., to make it easier to diff.
+@end itemize
+
+Of course these colors are subject to the color-theme in use.
+
+The following words are used:
+
+@itemize
+@item
+Commits prefixed with @code{pick}, @code{reword}, @code{edit}, @code{squash}, and @code{fixup} have not
+been applied yet.  These words have the same meaning here as they do
+in the buffer used to edit the rebase sequence.  See @ref{Editing Rebase Sequences}.  When the @code{--rebase-merges} option was specified,
+@code{reset}, @code{label}, and @code{merge} lines may also be present.
+
+@item
+Commits prefixed with @code{done} and @code{onto} have already been applied.
+It is possible for such a commit to be the @code{HEAD}, in which case it
+is blue.  Otherwise it is grey.
+
+@itemize
+@item
+The commit prefixed with @code{onto} is the commit on top of which all
+the other commits are being re-applied.  This commit itself did
+not have to be re-applied, it is the commit rebase did rewind to
+before starting to re-apply other commits.
+
+@item
+Commits prefixed with @code{done} have already been re-applied.  This
+includes commits that have been re-applied but also new commits
+that you have created during the rebase.
+@end itemize
+
+@item
+All other commits, those not prefixed with any of the above words,
+are in some way related to the commit at which rebase stopped.
+
+To determine whether a commit is related to the stopped-at commit
+their hashes, trees and patch-ids @footnote{The patch-id is a hash of the @emph{changes} introduced by a
+commit.  It differs from the hash of the commit itself, which is a
+hash of the result of applying that change (i.e., the resulting trees
+and blobs) as well as author and committer information, the commit
+message, and the hashes of the parents of the commit.  The patch-id
+hash on the other hand is created only from the added and removed
+lines, even line numbers and whitespace changes are ignored when
+calculating this hash.  The patch-ids of two commits can be used to
+answer the question "Do these commits make the same change?".} are being compared.
+The commit message is not used for this purpose.
+
+Generally speaking commits that are related to the stopped-at commit
+can have any of the used colors, though not all color/word
+combinations are possible.
+
+Words used for stopped-at commits are:
+
+@itemize
+@item
+When a commit is prefixed with @code{void}, then that indicates that
+Magit knows for sure that all the changes in that commit have been
+applied using several new commits.  This commit is no longer
+reachable from @code{HEAD}, and it also isn't one of the commits that
+will be applied when resuming the session.
+
+@item
+When a commit is prefixed with @code{join}, then that indicates that the
+rebase sequence stopped at that commit due to a conflict - you now
+have to join (merge) the changes with what has already been
+applied.  In a sense this is the commit rebase stopped at, but
+while its effect is already in the index and in the worktree (with
+conflict markers), the commit itself has not actually been applied
+yet (it isn't the @code{HEAD}).  So it is shown in yellow, like the other
+commits that still have to be applied.
+
+@item
+When a commit is prefixed with @code{stop} or a @emph{blue} or @emph{green} @code{same}, then
+that indicates that rebase stopped at this commit, that it is
+still applied or has been applied again, and that at least its
+patch-id is unchanged.
+
+@itemize
+@item
+When a commit is prefixed with @code{stop}, then that indicates that
+rebase stopped at that commit because you requested that
+earlier, and its patch-id is unchanged.  It might even still be
+the exact same commit.
+
+@item
+When a commit is prefixed with a @emph{blue} or @emph{green} @code{same}, then that
+indicates that while its tree or hash changed, its patch-id did
+not.  If it is blue, then it is the @code{HEAD} commit (as always for
+blue).  When it is green, then it no longer is @code{HEAD} because
+other commit have been created since (but before continuing the
+rebase).
+@end itemize
+
+@item
+When a commit is prefixed with @code{goal}, a @emph{yellow} @code{same,} or @code{work}, then
+that indicates that rebase applied that commit but that you then
+reset @code{HEAD} to an earlier commit (likely to split it up into
+multiple commits), and that there are some uncommitted changes
+remaining which likely (but not necessarily) originate from that
+commit.
+
+@itemize
+@item
+When a commit is prefixed with @code{goal}, then that indicates that it
+is still possible to create a new commit with the exact same
+tree (the "goal") without manually editing any files, by
+committing the index, or by staging all changes and then
+committing that.  This is the case when the original tree still
+exists in the index or worktree in untainted form.
+
+@item
+When a commit is prefixed with a yellow @code{same}, then that
+indicates that it is no longer possible to create a commit with
+the exact same tree, but that it is still possible to create a
+commit with the same patch-id.  This would be the case if you
+created a new commit with other changes, but the changes from
+the original commit still exist in the index or working tree in
+untainted form.
+
+@item
+When a commit is prefixed with @code{work}, then that indicates that
+you reset @code{HEAD} to an earlier commit, and that there are some
+staged and/or unstaged changes (likely, but not necessarily)
+originating from that commit.  However it is no longer possible
+to create a new commit with the same tree or at least the same
+patch-id because you have already made other changes.
+@end itemize
+
+@item
+When a commit is prefixed with @code{poof} or @code{gone}, then that indicates
+that rebase applied that commit but that you then reset @code{HEAD} to an
+earlier commit (likely to split it up into multiple commits), and
+that there are no uncommitted changes.
+
+@itemize
+@item
+When a commit is prefixed with @code{poof}, then that indicates that it
+is no longer reachable from @code{HEAD}, but that it has been replaced
+with one or more commits, which together have the exact same
+effect.
+
+@item
+When a commit is prefixed with @code{gone}, then that indicates that it
+is no longer reachable from @code{HEAD} and that we also cannot
+determine whether its changes are still in effect in one or more
+new commits.  They might be, but if so, then there must also be
+other changes which makes it impossible to know for sure.
+@end itemize
+@end itemize
+@end itemize
+
+Do not worry if you do not fully understand the above.  That's okay,
+you will acquire a good enough understanding through practice.
+
+For other sequence operations such as cherry-picking, a similar section
+is displayed, but they lack some of the features described above, due
+to limitations in the git commands used to implement them.  Most
+importantly these sequences only support "picking" a commit but not
+other actions such as "rewording", and they do not keep track of the
+commits which have already been applied.
+
+@node Cherry Picking
+@section Cherry Picking
+
+Also see 
+@ifinfo
+@ref{git-cherry-pick,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-cherry-pick">git-cherry-pick(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-cherry-pick(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{A} (@code{magit-cherry-pick})
+@kindex A
+@findex magit-cherry-pick
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+@end table
+
+When no cherry-pick or revert is in progress, then the transient
+features the following suffix commands.
+
+@table @asis
+@item @kbd{A A} (@code{magit-cherry-copy})
+@kindex A A
+@findex magit-cherry-copy
+This command copies COMMITS from another branch onto the current
+branch.  If the region selects multiple commits, then those are
+copied, without prompting.  Otherwise the user is prompted for a
+commit or range, defaulting to the commit at point.
+
+@item @kbd{A a} (@code{magit-cherry-apply})
+@kindex A a
+@findex magit-cherry-apply
+This command applies the changes in COMMITS from another branch onto
+the current branch.  If the region selects multiple commits, then
+those are used, without prompting.  Otherwise the user is prompted
+for a commit or range, defaulting to the commit at point.
+
+This command also has a top-level binding, which can be invoked
+without using the transient by typing @code{a} at the top-level.
+@end table
+
+The following commands not only apply some commits to some branch, but
+also remove them from some other branch.  The removal is performed
+using either @code{git-update-ref} or if necessary @code{git-rebase}.  Both applying
+commits as well as removing them using @code{git-rebase} can lead to
+conflicts.  If that happens, then these commands abort and you not
+only have to resolve the conflicts but also finish the process the
+same way you would have to if these commands didn't exist at all.
+
+@table @asis
+@item @kbd{A h} (@code{magit-cherry-harvest})
+@kindex A h
+@findex magit-cherry-harvest
+This command moves the selected COMMITS that must be located on
+another BRANCH onto the current branch instead, removing them from
+the former.  When this command succeeds, then the same branch is
+current as before.
+
+Applying the commits on the current branch or removing them from the
+other branch can lead to conflicts.  When that happens, then this
+command stops and you have to resolve the conflicts and then finish
+the process manually.
+
+@item @kbd{A d} (@code{magit-cherry-donate})
+@kindex A d
+@findex magit-cherry-donate
+This command moves the selected COMMITS from the current branch onto
+another existing BRANCH, removing them from the former.  When this
+command succeeds, then the same branch is current as before.  @code{HEAD}
+is allowed to be detached initially.
+
+Applying the commits on the other branch or removing them from the
+current branch can lead to conflicts.  When that happens, then this
+command stops and you have to resolve the conflicts and then finish
+the process manually.
+
+@item @kbd{A n} (@code{magit-cherry-spinout})
+@kindex A n
+@findex magit-cherry-spinout
+This command moves the selected COMMITS from the current branch onto
+a new branch BRANCH, removing them from the former.  When this
+command succeeds, then the same branch is current as before.
+
+Applying the commits on the other branch or removing them from the
+current branch can lead to conflicts.  When that happens, then this
+command stops and you have to resolve the conflicts and then finish
+the process manually.
+
+@item @kbd{A s} (@code{magit-cherry-spinoff})
+@kindex A s
+@findex magit-cherry-spinoff
+This command moves the selected COMMITS from the current branch onto
+a new branch BRANCH, removing them from the former.  When this
+command succeeds, then the new branch is checked out.
+
+Applying the commits on the other branch or removing them from the
+current branch can lead to conflicts.  When that happens, then this
+command stops and you have to resolve the conflicts and then finish
+the process manually.
+@end table
+
+When a cherry-pick or revert is in progress, then the transient
+instead features the following suffix commands.
+
+@table @asis
+@item @kbd{A A} (@code{magit-sequence-continue})
+@kindex A A
+@findex magit-sequence-continue
+Resume the current cherry-pick or revert sequence.
+
+@item @kbd{A s} (@code{magit-sequence-skip})
+@kindex A s
+@findex magit-sequence-skip
+Skip the stopped at commit during a cherry-pick or revert sequence.
+
+@item @kbd{A a} (@code{magit-sequence-abort})
+@kindex A a
+@findex magit-sequence-abort
+Abort the current cherry-pick or revert sequence.  This discards all
+changes made since the sequence started.
+@end table
+
+@menu
+* Reverting::
+@end menu
+
+@node Reverting
+@subsection Reverting
+
+@table @asis
+@item @kbd{V} (@code{magit-revert})
+@kindex V
+@findex magit-revert
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+@end table
+
+When no cherry-pick or revert is in progress, then the transient
+features the following suffix commands.
+
+@table @asis
+@item @kbd{V V} (@code{magit-revert-and-commit})
+@kindex V V
+@findex magit-revert-and-commit
+Revert a commit by creating a new commit.  Prompt for a commit,
+defaulting to the commit at point.  If the region selects multiple
+commits, then revert all of them, without prompting.
+
+@item @kbd{V v} (@code{magit-revert-no-commit})
+@kindex V v
+@findex magit-revert-no-commit
+Revert a commit by applying it in reverse to the working tree.
+Prompt for a commit, defaulting to the commit at point.  If the
+region selects multiple commits, then revert all of them, without
+prompting.
+@end table
+
+When a cherry-pick or revert is in progress, then the transient
+instead features the following suffix commands.
+
+@table @asis
+@item @kbd{V V} (@code{magit-sequence-continue})
+@kindex V V
+@findex magit-sequence-continue
+Resume the current cherry-pick or revert sequence.
+
+@item @kbd{V s} (@code{magit-sequence-skip})
+@kindex V s
+@findex magit-sequence-skip
+Skip the stopped at commit during a cherry-pick or revert sequence.
+
+@item @kbd{V a} (@code{magit-sequence-abort})
+@kindex V a
+@findex magit-sequence-abort
+Abort the current cherry-pick or revert sequence.  This discards all
+changes made since the sequence started.
+@end table
+
+@node Resetting
+@section Resetting
+
+Also see 
+@ifinfo
+@ref{git-reset,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-reset">git-reset(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-reset(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{x} (@code{magit-reset-quickly})
+@kindex x
+@findex magit-reset-quickly
+Reset the @code{HEAD} and index to some commit read from the user and
+defaulting to the commit at point, and possibly also reset the
+working tree.  With a prefix argument reset the working tree
+otherwise don't.
+
+@item @kbd{X m} (@code{magit-reset-mixed})
+@kindex X m
+@findex magit-reset-mixed
+Reset the @code{HEAD} and index to some commit read from the user and
+defaulting to the commit at point.  The working tree is kept as-is.
+
+@item @kbd{X s} (@code{magit-reset-soft})
+@kindex X s
+@findex magit-reset-soft
+Reset the @code{HEAD} to some commit read from the user and defaulting
+to the commit at point.  The index and the working tree are kept
+as-is.
+
+@item @kbd{X h} (@code{magit-reset-hard})
+@kindex X h
+@findex magit-reset-hard
+Reset the @code{HEAD}, index, and working tree to some commit read from the
+user and defaulting to the commit at point.
+
+@item @kbd{X k} (@code{magit-reset-keep})
+@kindex X k
+@findex magit-reset-keep
+Reset the @code{HEAD}, index, and working tree to some commit read from the
+user and defaulting to the commit at point.  Uncommitted changes are
+kept as-is.
+
+@item @kbd{X i} (@code{magit-reset-index})
+@kindex X i
+@findex magit-reset-index
+Reset the index to some commit read from the user and defaulting to
+the commit at point.  Keep the @code{HEAD} and working tree as-is, so if
+the commit refers to the @code{HEAD}, then this effectively unstages all
+changes.
+
+@item @kbd{X w} (@code{magit-reset-worktree})
+@kindex X w
+@findex magit-reset-worktree
+Reset the working tree to some commit read from the user and
+defaulting to the commit at point.  Keep the @code{HEAD} and index as-is.
+
+@item @kbd{X f} (@code{magit-file-checkout})
+@kindex X f
+@findex magit-file-checkout
+Update file in the working tree and index to the contents from a
+revision.  Both the revision and file are read from the user.
+@end table
+
+@node Stashing
+@section Stashing
+
+Also see 
+@ifinfo
+@ref{git-stash,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-stash">git-stash(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-stash(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{z} (@code{magit-stash})
+@kindex z
+@findex magit-stash
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{z z} (@code{magit-stash-both})
+@kindex z z
+@findex magit-stash-both
+Create a stash of the index and working tree.  Untracked files are
+included according to infix arguments.  One prefix argument is
+equivalent to @code{--include-untracked} while two prefix arguments are
+equivalent to @code{--all}.
+
+@item @kbd{z i} (@code{magit-stash-index})
+@kindex z i
+@findex magit-stash-index
+Create a stash of the index only.  Unstaged and untracked changes
+are not stashed.
+
+@item @kbd{z w} (@code{magit-stash-worktree})
+@kindex z w
+@findex magit-stash-worktree
+Create a stash of unstaged changes in the working tree.  Untracked
+files are included according to infix arguments.  One prefix
+argument is equivalent to @code{--include-untracked} while two prefix
+arguments are equivalent to @code{--all}.
+
+@item @kbd{z x} (@code{magit-stash-keep-index})
+@kindex z x
+@findex magit-stash-keep-index
+Create a stash of the index and working tree, keeping index intact.
+Untracked files are included according to infix arguments.  One
+prefix argument is equivalent to @code{--include-untracked} while two
+prefix arguments are equivalent to @code{--all}.
+
+@item @kbd{z Z} (@code{magit-snapshot-both})
+@kindex z Z
+@findex magit-snapshot-both
+Create a snapshot of the index and working tree.  Untracked files
+are included according to infix arguments.  One prefix argument is
+equivalent to @code{--include-untracked} while two prefix arguments are
+equivalent to @code{--all}.
+
+@item @kbd{z I} (@code{magit-snapshot-index})
+@kindex z I
+@findex magit-snapshot-index
+Create a snapshot of the index only.  Unstaged and untracked changes
+are not stashed.
+
+@item @kbd{z W} (@code{magit-snapshot-worktree})
+@kindex z W
+@findex magit-snapshot-worktree
+Create a snapshot of unstaged changes in the working tree.
+Untracked files are included according to infix arguments.  One
+prefix argument is equivalent to @code{--include-untracked} while two
+prefix arguments are equivalent to @code{--all}-.
+
+@item @kbd{z a} (@code{magit-stash-apply})
+@kindex z a
+@findex magit-stash-apply
+Apply a stash to the working tree.
+
+First try @code{git stash apply --index}, which tries to preserve
+the index stored in the stash, if any.  This may fail because
+applying the stash could result in conflicts and those have to
+be stored in the index, making it impossible to also store the
+stash's index there as well.
+
+If the above failed, then try @code{git stash apply}.  This fails
+(with or without @code{--index}) if there are any uncommitted
+changes to files that are also modified in the stash.
+
+If both of the above failed, then apply using @code{git apply}.
+If there are no conflicting files, use @code{--3way}.  If there are
+conflicting files, then using @code{--3way} requires that those
+files are staged first, which may be undesirable, so prompt
+the user whether to use @code{--3way} or @code{--reject}.
+
+Customize @code{magit-no-confirm} if you want to always use @code{--3way},
+without being prompted.
+
+@item @kbd{z p} (@code{magit-stash-pop})
+@kindex z p
+@findex magit-stash-pop
+Apply a stash to the working tree.  On complete success (if the
+stash can be applied without any conflicts, and while preserving
+the stash's index) then remove the stash from stash list.
+
+First try @code{git stash pop --index}, which tries to preserve
+the index stored in the stash, if any.  This may fail because
+applying the stash could result in conflicts and those have to
+be stored in the index, making it impossible to also store the
+stash's index there as well.
+
+If the above failed, then try @code{git stash apply}.  This fails
+(with or without @code{--index}) if there are any uncommitted
+changes to files that are also modified in the stash.
+
+If both of the above failed, then apply using @code{git apply}.
+If there are no conflicting files, use @code{--3way}.  If there are
+conflicting files, then using @code{--3way} requires that those
+files are staged first, which may be undesirable, so prompt
+the user whether to use @code{--3way} or @code{--reject}.
+
+Customize @code{magit-no-confirm} if you want to always use @code{--3way},
+without being prompted.
+
+@item @kbd{z k} (@code{magit-stash-drop})
+@kindex z k
+@findex magit-stash-drop
+Remove a stash from the stash list.  When the region is active, offer
+to drop all contained stashes.
+
+@item @kbd{z v} (@code{magit-stash-show})
+@kindex z v
+@findex magit-stash-show
+Show all diffs of a stash in a buffer.
+
+@item @kbd{z b} (@code{magit-stash-branch})
+@kindex z b
+@findex magit-stash-branch
+Create and checkout a new branch from an existing stash.  The new
+branch starts at the commit that was current when the stash was
+created.
+
+@item @kbd{z B} (@code{magit-stash-branch-here})
+@kindex z B
+@findex magit-stash-branch-here
+Create and checkout a new branch from an existing stash.  Use the
+current branch or @code{HEAD} as the starting-point of the new branch.
+Then apply the stash, dropping it if it applies cleanly.
+
+@item @kbd{z f} (@code{magit-stash-format-patch})
+@kindex z f
+@findex magit-stash-format-patch
+Create a patch from STASH@.
+
+@item @kbd{k} (@code{magit-stash-clear})
+@kindex k
+@findex magit-stash-clear
+Remove all stashes saved in REF's reflog by deleting REF@.
+
+@item @kbd{z l} (@code{magit-stash-list})
+@kindex z l
+@findex magit-stash-list
+List all stashes in a buffer.
+@end table
+
+@defopt magit-stashes-margin
+This option specifies whether the margin is initially shown in
+stashes buffers and how it is formatted.
+
+The value has the form @code{(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)}.
+
+@itemize
+@item
+If INIT is non-nil, then the margin is shown initially.
+@item
+STYLE controls how to format the author or committer date.  It can
+be one of @code{age} (to show the age of the commit), @code{age-abbreviated} (to
+abbreviate the time unit to a character), or a string (suitable
+for @code{format-time-string}) to show the actual date.  Option
+@code{magit-log-margin-show-committer-date} controls which date is being
+displayed.
+@item
+WIDTH controls the width of the margin.  This exists for forward
+compatibility and currently the value should not be changed.
+@item
+AUTHOR controls whether the name of the author is also shown by
+default.
+@item
+AUTHOR-WIDTH has to be an integer.  When the name of the author
+is shown, then this specifies how much space is used to do so.
+@end itemize
+@end defopt
+
+@node Transferring
+@chapter Transferring
+
+@menu
+* Remotes::
+* Fetching::
+* Pulling::
+* Pushing::
+* Plain Patches::
+* Maildir Patches::
+@end menu
+
+@node Remotes
+@section Remotes
+
+@menu
+* Remote Commands::
+* Remote Git Variables::
+@end menu
+
+@node Remote Commands
+@subsection Remote Commands
+
+The transient prefix command @code{magit-remote} is used to add remotes and
+to make changes to existing remotes.  This command only deals with
+remotes themselves, not with branches or the transfer of commits.
+Those features are available from separate transient commands.
+
+Also see 
+@ifinfo
+@ref{git-remote,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-remote">git-remote(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-remote(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{M} (@code{magit-remote})
+@kindex M
+@findex magit-remote
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+By default it also binds and displays the values of some
+remote-related Git variables and allows changing their values.
+@end table
+
+@defopt magit-remote-direct-configure
+This option controls whether remote-related Git variables are
+accessible directly from the transient @code{magit-remote}.
+
+If @code{t} (the default) and a local branch is checked out, then
+@code{magit-remote} features the variables for the upstream remote of that
+branch, or if @code{HEAD} is detached, for @code{origin}, provided that exists.
+
+If @code{nil}, then @code{magit-remote-configure} has to be used to do so.
+@end defopt
+
+@table @asis
+@item @kbd{M C} (@code{magit-remote-configure})
+@kindex M C
+@findex magit-remote-configure
+This transient prefix command binds commands that set the value of
+remote-related variables and displays them in a temporary buffer
+until the transient is exited.
+
+With a prefix argument, this command always prompts for a remote.
+
+Without a prefix argument this depends on whether it was invoked as
+a suffix of @code{magit-remote} and on the @code{magit-remote-direct-configure}
+option.  If @code{magit-remote} already displays the variables for the
+upstream, then it does not make sense to invoke another transient
+that displays them for the same remote.  In that case this command
+prompts for a remote.
+@end table
+
+The variables are described in @ref{Remote Git Variables}.
+
+@table @asis
+@item @kbd{M a} (@code{magit-remote-add})
+@kindex M a
+@findex magit-remote-add
+This command add a remote and fetches it.  The remote name and url
+are read in the minibuffer.
+
+@item @kbd{M r} (@code{magit-remote-rename})
+@kindex M r
+@findex magit-remote-rename
+This command renames a remote.  Both the old and the new names are
+read in the minibuffer.
+
+@item @kbd{M u} (@code{magit-remote-set-url})
+@kindex M u
+@findex magit-remote-set-url
+This command changes the url of a remote.  Both the remote and the
+new url are read in the minibuffer.
+
+@item @kbd{M k} (@code{magit-remote-remove})
+@kindex M k
+@findex magit-remote-remove
+This command deletes a remote, read in the minibuffer.
+
+@item @kbd{M p} (@code{magit-remote-prune})
+@kindex M p
+@findex magit-remote-prune
+This command removes stale remote-tracking branches for a remote
+read in the minibuffer.
+
+@item @kbd{M P} (@code{magit-remote-prune-refspecs})
+@kindex M P
+@findex magit-remote-prune-refspecs
+This command removes stale refspecs for a remote read in the
+minibuffer.
+
+A refspec is stale if there no longer exists at least one branch
+on the remote that would be fetched due to that refspec.  A stale
+refspec is problematic because its existence causes Git to refuse
+to fetch according to the remaining non-stale refspecs.
+
+If only stale refspecs remain, then this command offers to either
+delete the remote or to replace the stale refspecs with the default
+refspec ("+refs/heads/*:refs/remotes/REMOTE/*").
+
+This command also removes the remote-tracking branches that were
+created due to the now stale refspecs.  Other stale branches are
+not removed.
+@end table
+
+@defopt magit-remote-add-set-remote.pushDefault
+This option controls whether the user is asked whether they want to
+set @code{remote.pushDefault} after adding a remote.
+
+If @code{ask}, then users is always ask.  If @code{ask-if-unset}, then the user is
+only if the variable isn't set already.  If @code{nil}, then the user isn't
+asked and the variable isn't set.  If the value is a string, then
+the variable is set without the user being asked, provided that the
+name of the added remote is equal to that string and the variable
+isn't already set.
+@end defopt
+
+@node Remote Git Variables
+@subsection Remote Git Variables
+
+These variables can be set from the transient prefix command
+@code{magit-remote-configure}.  By default they can also be set from
+@code{magit-remote}.  See @ref{Remote Commands}.
+
+@defvar remote.NAME.url
+This variable specifies the url of the remote named NAME@.  It can
+have multiple values.
+@end defvar
+
+@defvar remote.NAME.fetch
+The refspec used when fetching from the remote named NAME@.  It can
+have multiple values.
+@end defvar
+
+@defvar remote.NAME.pushurl
+This variable specifies the url used for pushing to the remote
+named NAME@.  If it is not specified, then @code{remote.NAME.url} is used
+instead.  It can have multiple values.
+@end defvar
+
+@defvar remote.NAME.push
+The refspec used when pushing to the remote named NAME@.  It can
+have multiple values.
+@end defvar
+
+@defvar remote.NAME.tagOpts
+This variable specifies what tags are fetched by default.  If the
+value is @code{--no-tags} then no tags are fetched.  If the value is
+@code{--tags}, then all tags are fetched.  If this variable has no value,
+then only tags are fetched that are reachable from fetched branches.
+@end defvar
+
+@node Fetching
+@section Fetching
+
+Also see 
+@ifinfo
+@ref{git-fetch,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-fetch">git-fetch(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-fetch(1) manpage.
+@end iftex
+ For information about the upstream and the
+push-remote, see @ref{The Two Remotes}.
+
+@table @asis
+@item @kbd{f} (@code{magit-fetch})
+@kindex f
+@findex magit-fetch
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{f p} (@code{magit-fetch-from-pushremote})
+@kindex f p
+@findex magit-fetch-from-pushremote
+This command fetches from the current push-remote.
+
+With a prefix argument or when the push-remote is either not
+configured or unusable, then let the user first configure the
+push-remote.
+
+@item @kbd{f u} (@code{magit-fetch-from-upstream})
+@kindex f u
+@findex magit-fetch-from-upstream
+This command fetch from the upstream of the current branch.
+
+If the upstream is configured for the current branch and names
+an existing remote, then use that.  Otherwise try to use another
+remote: If only a single remote is configured, then use that.
+Otherwise if a remote named "origin" exists, then use that.
+
+If no remote can be determined, then this command is not available
+from the @code{magit-fetch} transient prefix and invoking it directly
+results in an error.
+
+@item @kbd{f e} (@code{magit-fetch-other})
+@kindex f e
+@findex magit-fetch-other
+This command fetch from a repository read from the minibuffer.
+
+@item @kbd{f o} (@code{magit-fetch-branch})
+@kindex f o
+@findex magit-fetch-branch
+This command fetches a branch from a remote, both of which are read
+from the minibuffer.
+
+@item @kbd{f r} (@code{magit-fetch-refspec})
+@kindex f r
+@findex magit-fetch-refspec
+This command fetches from a remote using an explicit refspec, both
+of which are read from the minibuffer.
+
+@item @kbd{f a} (@code{magit-fetch-all})
+@kindex f a
+@findex magit-fetch-all
+This command fetches from all remotes.
+
+@item @kbd{f m} (@code{magit-fetch-modules})
+@kindex f m
+@findex magit-fetch-modules
+This command fetches all submodules.  With a prefix argument, it
+acts as a transient prefix command, allowing the caller to set
+options.
+@end table
+
+@defopt magit-pull-or-fetch
+By default fetch and pull commands are available from separate
+transient prefix command.  Setting this to @code{t} adds some (but not all)
+of the above suffix commands to the @code{magit-pull} transient.
+
+If you do that, then you might also want to change the key binding
+for these prefix commands, e.g.:
+
+@lisp
+(setq magit-pull-or-fetch t)
+(define-key magit-mode-map "f" 'magit-pull) ; was magit-fetch
+(define-key magit-mode-map "F" nil)         ; was magit-pull
+@end lisp
+@end defopt
+
+@node Pulling
+@section Pulling
+
+Also see 
+@ifinfo
+@ref{git-pull,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-pull">git-pull(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-pull(1) manpage.
+@end iftex
+ For information about the upstream and the
+push-remote, see @ref{The Two Remotes}.
+
+@table @asis
+@item @kbd{F} (@code{magit-pull})
+@kindex F
+@findex magit-pull
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+@item @kbd{F p} (@code{magit-pull-from-pushremote})
+@kindex F p
+@findex magit-pull-from-pushremote
+This command pulls from the push-remote of the current branch.
+
+With a prefix argument or when the push-remote is either not
+configured or unusable, then let the user first configure the
+push-remote.
+
+@item @kbd{F u} (@code{magit-pull-from-upstream})
+@kindex F u
+@findex magit-pull-from-upstream
+This command pulls from the upstream of the current branch.
+
+With a prefix argument or when the upstream is either not
+configured or unusable, then let the user first configure
+the upstream.
+
+@item @kbd{F e} (@code{magit-pull-branch})
+@kindex F e
+@findex magit-pull-branch
+This command pulls from a branch read in the minibuffer.
+@end table
+
+@node Pushing
+@section Pushing
+
+Also see 
+@ifinfo
+@ref{git-push,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-push">git-push(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-push(1) manpage.
+@end iftex
+ For information about the upstream and the
+push-remote, see @ref{The Two Remotes}.
+
+@table @asis
+@item @kbd{P} (@code{magit-push})
+@kindex P
+@findex magit-push
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{P p} (@code{magit-push-current-to-pushremote})
+@kindex P p
+@findex magit-push-current-to-pushremote
+This command pushes the current branch to its push-remote.
+
+With a prefix argument or when the push-remote is either not
+configured or unusable, then let the user first configure the
+push-remote.
+
+@item @kbd{P u} (@code{magit-push-current-to-upstream})
+@kindex P u
+@findex magit-push-current-to-upstream
+This command pushes the current branch to its upstream branch.
+
+With a prefix argument or when the upstream is either not
+configured or unusable, then let the user first configure
+the upstream.
+
+@item @kbd{P e} (@code{magit-push-current})
+@kindex P e
+@findex magit-push-current
+This command pushes the current branch to a branch read in the
+minibuffer.
+
+@item @kbd{P o} (@code{magit-push-other})
+@kindex P o
+@findex magit-push-other
+This command pushes an arbitrary branch or commit somewhere.  Both
+the source and the target are read in the minibuffer.
+
+@item @kbd{P r} (@code{magit-push-refspecs})
+@kindex P r
+@findex magit-push-refspecs
+This command pushes one or multiple refspecs to a remote, both of
+which are read in the minibuffer.
+
+To use multiple refspecs, separate them with commas.  Completion is
+only available for the part before the colon, or when no colon is
+used.
+
+@item @kbd{P m} (@code{magit-push-matching})
+@kindex P m
+@findex magit-push-matching
+This command pushes all matching branches to another repository.
+
+If only one remote exists, then push to that.  Otherwise prompt for
+a remote, offering the remote configured for the current branch as
+default.
+
+@item @kbd{P t} (@code{magit-push-tags})
+@kindex P t
+@findex magit-push-tags
+This command pushes all tags to another repository.
+
+If only one remote exists, then push to that.  Otherwise prompt for
+a remote, offering the remote configured for the current branch as
+default.
+
+@item @kbd{P T} (@code{magit-push-tag})
+@kindex P T
+@findex magit-push-tag
+This command pushes a tag to another repository.
+@end table
+
+One of the infix arguments, @code{--force-with-lease}, deserves a word of
+caution.  It is passed without a value, which means "permit a force
+push as long as the remote-tracking branches match their counterparts
+on the remote end".  If you've set up a tool to do automatic fetches
+(Magit itself does not provide such functionality), using
+@code{--force-with-lease} can be dangerous because you don't actually
+control or know the state of the remote-tracking refs.  In that case,
+you should consider setting @code{push.useForceIfIncludes} to @code{true}
+(available since Git 2.30).
+
+Two more push commands exist, which by default are not available from
+the push transient.  See their doc-strings for instructions on how to
+add them to the transient.
+
+@deffn Command magit-push-implicitly args
+This command pushes somewhere without using an explicit refspec.
+
+This command simply runs @code{git push -v [ARGS]}.  ARGS are the infix
+arguments.  No explicit refspec arguments are used.  Instead the
+behavior depends on at least these Git variables: @code{push.default},
+@code{remote.pushDefault}, @code{branch.<branch>.pushRemote},
+@code{branch.<branch>.remote}, @code{branch.<branch>.merge}, and
+@code{remote.<remote>.push}.
+
+If you add this suffix to a transient prefix without explicitly
+specifying the description, then an attempt is made to predict
+what this command will do.  For example:
+
+@lisp
+(transient-insert-suffix 'magit-push \"p\"
+  '(\"i\" magit-push-implicitly))"
+@end lisp
+@end deffn
+
+@deffn Command magit-push-to-remote remote args
+This command pushes to the remote REMOTE without using an explicit
+refspec.  The remote is read in the minibuffer.
+
+This command simply runs @code{git push -v [ARGS] REMOTE}.  ARGS are the
+infix arguments.  No refspec arguments are used.  Instead the
+behavior depends on at least these Git variables: @code{push.default},
+@code{remote.pushDefault}, @code{branch.<branch>.pushRemote},
+@code{branch.<branch>.remote}, @code{branch.<branch>.merge}, and
+@code{remote.<remote>.push}.
+@end deffn
+
+@node Plain Patches
+@section Plain Patches
+
+@table @asis
+@item @kbd{W} (@code{magit-patch})
+@kindex W
+@findex magit-patch
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{W c} (@code{magit-patch-create})
+@kindex W c
+@findex magit-patch-create
+This command creates patches for a set commits.  If the region marks
+several commits, then it creates patches for all of them.  Otherwise
+it functions as a transient prefix command, which features several
+infix arguments and binds itself as a suffix command.  When this
+command is invoked as a suffix of itself, then it creates a patch
+using the specified infix arguments.
+
+@item @kbd{w a} (@code{magit-patch-apply})
+@kindex w a
+@findex magit-patch-apply
+This command applies a patch.  This is a transient prefix command,
+which features several infix arguments and binds itself as a suffix
+command.  When this command is invoked as a suffix of itself, then
+it applies a patch using the specified infix arguments.
+
+@item @kbd{W s} (@code{magit-patch-save})
+@kindex W s
+@findex magit-patch-save
+This command creates a patch from the current diff.
+
+Inside @code{magit-diff-mode} or @code{magit-revision-mode} buffers, @code{C-x C-w} is
+also bound to this command.
+@end table
+
+It is also possible to save a plain patch file by using @code{C-x C-w} inside
+a @code{magit-diff-mode} or @code{magit-revision-mode} buffer.
+
+@node Maildir Patches
+@section Maildir Patches
+
+Also see 
+@ifinfo
+@ref{git-am,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-am">git-am(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-am(1) manpage.
+@end iftex
+ and 
+@ifinfo
+@ref{git-apply,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-apply">git-apply(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-apply(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{w} (@code{magit-am})
+@kindex w
+@findex magit-am
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{w w} (@code{magit-am-apply-patches})
+@kindex w w
+@findex magit-am-apply-patches
+This command applies one or more patches.  If the region marks
+files, then those are applied as patches.  Otherwise this command
+reads a file-name in the minibuffer, defaulting to the file at
+point.
+
+@item @kbd{w m} (@code{magit-am-apply-maildir})
+@kindex w m
+@findex magit-am-apply-maildir
+This command applies patches from a maildir.
+
+@item @kbd{w a} (@code{magit-patch-apply})
+@kindex w a
+@findex magit-patch-apply
+This command applies a plain patch.  For a longer description see
+@ref{Plain Patches}.  This command is only available from the @code{magit-am}
+transient for historic reasons.
+@end table
+
+When an "am" operation is in progress, then the transient instead
+features the following suffix commands.
+
+@table @asis
+@item @kbd{w w} (@code{magit-am-continue})
+@kindex w w
+@findex magit-am-continue
+This command resumes the current patch applying sequence.
+
+@item @kbd{w s} (@code{magit-am-skip})
+@kindex w s
+@findex magit-am-skip
+This command skips the stopped at patch during a patch applying
+sequence.
+
+@item @kbd{w a} (@code{magit-am-abort})
+@kindex w a
+@findex magit-am-abort
+This command aborts the current patch applying sequence.  This
+discards all changes made since the sequence started.
+@end table
+
+@node Miscellaneous
+@chapter Miscellaneous
+
+@menu
+* Tagging::
+* Notes::
+* Submodules::
+* Subtree::
+* Worktree::
+* Sparse checkouts::
+* Bundle::
+* Common Commands::
+* Wip Modes::
+* Commands for Buffers Visiting Files::
+* Minor Mode for Buffers Visiting Blobs::
+@end menu
+
+@node Tagging
+@section Tagging
+
+Also see 
+@ifinfo
+@ref{git-tag,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-tag">git-tag(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-tag(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{t} (@code{magit-tag})
+@kindex t
+@findex magit-tag
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{t t} (@code{magit-tag-create})
+@kindex t t
+@findex magit-tag-create
+This command creates a new tag with the given NAME at REV@.  With a
+prefix argument it creates an annotated tag.
+
+@item @kbd{t r} (@code{magit-tag-release})
+@kindex t r
+@findex magit-tag-release
+This commands creates a release tag.  It assumes that release tags
+match @code{magit-release-tag-regexp}.
+
+First it prompts for the name of the new tag using the highest
+existing tag as initial input and leaving it to the user to
+increment the desired part of the version string.  If you use
+unconventional release tags or version numbers (e.g.,
+@code{v1.2.3-custom.1}), you can set the @code{magit-release-tag-regexp} and
+@code{magit-tag-version-regexp-alist} variables.
+
+If @code{--annotate} is enabled then it prompts for the message of the
+new tag.  The proposed tag message is based on the message of the
+highest tag, provided that that contains the corresponding version
+string and substituting the new version string for that.  Otherwise
+it proposes something like "Foo-Bar 1.2.3", given, for example, a
+TAG "v1.2.3" and a repository located at something like
+"/path/to/foo-bar".
+
+@item @kbd{t k} (@code{magit-tag-delete})
+@kindex t k
+@findex magit-tag-delete
+This command deletes one or more tags.  If the region marks multiple
+tags (and nothing else), then it offers to delete those.  Otherwise,
+it prompts for a single tag to be deleted, defaulting to the tag at
+point.
+
+@item @kbd{t p} (@code{magit-tag-prune})
+@kindex t p
+@findex magit-tag-prune
+This command offers to delete tags missing locally from REMOTE, and
+vice versa.
+@end table
+
+@node Notes
+@section Notes
+
+Also see 
+@ifinfo
+@ref{git-notes,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-notes">git-notes(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-notes(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{T} (@code{magit-notes})
+@kindex T
+@findex magit-notes
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+@item @kbd{T T} (@code{magit-notes-edit})
+@kindex T T
+@findex magit-notes-edit
+Edit the note attached to a commit, defaulting to the commit at
+point.
+
+By default use the value of Git variable @code{core.notesRef} or
+"refs/notes/commits" if that is undefined.
+
+@item @kbd{T r} (@code{magit-notes-remove})
+@kindex T r
+@findex magit-notes-remove
+Remove the note attached to a commit, defaulting to the commit at
+point.
+
+By default use the value of Git variable @code{core.notesRef} or
+"refs/notes/commits" if that is undefined.
+
+@item @kbd{T p} (@code{magit-notes-prune})
+@kindex T p
+@findex magit-notes-prune
+Remove notes about unreachable commits.
+@end table
+
+It is possible to merge one note ref into another.  That may result in
+conflicts which have to resolved in the temporary worktree
+".git/NOTES@math{_MERGE}@math{_WORKTREE}".
+
+@table @asis
+@item @kbd{T m} (@code{magit-notes-merge})
+@kindex T m
+@findex magit-notes-merge
+Merge the notes of a ref read from the user into the current notes
+ref.  The current notes ref is the value of Git variable
+@code{core.notesRef} or "refs/notes/commits" if that is undefined.
+@end table
+
+When a notes merge is in progress then the transient features the
+following suffix commands, instead of those listed above.
+
+@table @asis
+@item @kbd{T c} (@code{magit-notes-merge-commit})
+@kindex T c
+@findex magit-notes-merge-commit
+Commit the current notes ref merge, after manually resolving
+conflicts.
+
+@item @kbd{T a} (@code{magit-notes-merge-abort})
+@kindex T a
+@findex magit-notes-merge-abort
+Abort the current notes ref merge.
+@end table
+
+The following variables control what notes reference @code{magit-notes-*},
+@code{git notes} and @code{git show} act on and display.  Both the local and global
+values are displayed and can be modified.
+
+@defvar core.notesRef
+This variable specifies the notes ref that is displayed by default
+and which commands act on by default.
+@end defvar
+
+@defvar notes.displayRef
+This variable specifies additional notes ref to be displayed in
+addition to the ref specified by @code{core.notesRef}.  It can have
+multiple values and may end with @code{*} to display all refs in the
+@code{refs/notes/} namespace (or @code{**} if some names contain slashes).
+@end defvar
+
+@node Submodules
+@section Submodules
+
+Also see 
+@ifinfo
+@ref{git-submodule,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-submodule">git-submodule(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-submodule(1) manpage.
+@end iftex
+
+@menu
+* Listing Submodules::
+* Submodule Transient::
+@end menu
+
+@node Listing Submodules
+@subsection Listing Submodules
+
+The command @code{magit-list-submodules} displays a list of the current
+repository's submodules in a separate buffer.  It's also possible to
+display information about submodules directly in the status buffer of
+the super-repository by adding @code{magit-insert-modules} to the hook
+@code{magit-status-sections-hook} as described in @ref{Status Module Sections}.
+
+@deffn Command magit-list-submodules
+This command displays a list of the current repository's populated
+submodules in a separate buffer.
+
+It can be invoked by pressing @code{RET} on the section titled "Modules".
+@end deffn
+
+@defopt magit-submodule-list-columns
+This option controls what columns are displayed by the command
+@code{magit-list-submodules} and how they are displayed.
+
+Each element has the form @code{(HEADER WIDTH FORMAT PROPS)}.
+
+HEADER is the string displayed in the header.  WIDTH is the width
+of the column.  FORMAT is a function that is called with one
+argument, the repository identification (usually its basename),
+and with @code{default-directory} bound to the toplevel of its working
+tree.  It has to return a string to be inserted or nil.  PROPS is
+an alist that supports the keys @code{:right-align}, @code{:pad-right} and
+@code{:sort}.
+
+The @code{:sort} function has a weird interface described in the
+docstring of @code{tabulated-list--get-sort}.  Alternatively @code{<} and
+@code{magit-repolist-version<} can be used as those functions are
+automatically replaced with functions that satisfy the interface.
+Set @code{:sort} to @code{nil} to inhibit sorting; if unspecified, then the
+column is sortable using the default sorter.
+
+You may wish to display a range of numeric columns using just one
+character per column and without any padding between columns, in
+which case you should use an appropriate HEADER, set WIDTH to 1,
+and set @code{:pad-right} to 9. @code{+} is substituted for numbers higher than 9.
+@end defopt
+
+@node Submodule Transient
+@subsection Submodule Transient
+
+@table @asis
+@item @kbd{o} (@code{magit-submodule})
+@kindex o
+@findex magit-submodule
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+@end table
+
+Some of the below commands default to act on the modules that are
+selected using the region.  For brevity their description talk about
+"the selected modules", but if no modules are selected, then they act
+on the current module instead, or if point isn't on a module, then the
+read a single module to act on.  With a prefix argument these commands
+ignore the selection and the current module and instead act on all
+suitable modules.
+
+@table @asis
+@item @kbd{o a} (@code{magit-submodule-add})
+@kindex o a
+@findex magit-submodule-add
+This commands adds the repository at URL as a module.  Optional PATH
+is the path to the module relative to the root of the super-project.
+If it is nil then the path is determined based on URL@.
+
+@item @kbd{o r} (@code{magit-submodule-register})
+@kindex o r
+@findex magit-submodule-register
+This command registers the selected modules by copying their urls
+from ".gitmodules" to "$GIT@math{_DIR}/config".  These values can then be
+edited before running @code{magit-submodule-populate}.  If you don't need
+to edit any urls, then use the latter directly.
+
+@item @kbd{o p} (@code{magit-submodule-populate})
+@kindex o p
+@findex magit-submodule-populate
+This command creates the working directory or directories of the
+selected modules, checking out the recorded commits.
+
+@item @kbd{o u} (@code{magit-submodule-update})
+@kindex o u
+@findex magit-submodule-update
+This command updates the selected modules checking out the recorded
+commits.
+
+@item @kbd{o s} (@code{magit-submodule-synchronize})
+@kindex o s
+@findex magit-submodule-synchronize
+This command synchronizes the urls of the selected modules, copying
+the values from ".gitmodules" to the ".git/config" of the
+super-project as well those of the modules.
+
+@item @kbd{o d} (@code{magit-submodule-unpopulate})
+@kindex o d
+@findex magit-submodule-unpopulate
+This command removes the working directory of the selected modules.
+
+@item @kbd{o l} (@code{magit-list-submodules})
+@kindex o l
+@findex magit-list-submodules
+This command displays a list of the current repository's modules.
+
+@item @kbd{o f} (@code{magit-fetch-modules})
+@kindex o f
+@findex magit-fetch-modules
+This command fetches all populated modules.  With a prefix argument,
+it acts as a transient prefix command, allowing the caller to set
+options.
+
+Also fetch the super-repository, because @code{git fetch} does not
+support not doing that.
+@end table
+
+@node Subtree
+@section Subtree
+
+Also see 
+@ifinfo
+@ref{git-subtree,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-subtree">git-subtree(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-subtree(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{O} (@code{magit-subtree})
+@kindex O
+@findex magit-subtree
+This transient prefix command binds the two sub-transients; one for
+importing a subtree and one for exporting a subtree.
+
+@item @kbd{O i} (@code{magit-subtree-import})
+@kindex O i
+@findex magit-subtree-import
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+The suffixes of this command import subtrees.
+
+If the @code{--prefix} argument is set, then the suffix commands use that
+prefix without prompting the user.  If it is unset, then they read
+the prefix in the minibuffer.
+
+@item @kbd{O i a} (@code{magit-subtree-add})
+@kindex O i a
+@findex magit-subtree-add
+This command adds COMMIT from REPOSITORY as a new subtree at PREFIX@.
+
+@item @kbd{O i c} (@code{magit-subtree-add-commit})
+@kindex O i c
+@findex magit-subtree-add-commit
+This command add COMMIT as a new subtree at PREFIX@.
+
+@item @kbd{O i m} (@code{magit-subtree-merge})
+@kindex O i m
+@findex magit-subtree-merge
+This command merges COMMIT into the PREFIX subtree.
+
+@item @kbd{O i f} (@code{magit-subtree-pull})
+@kindex O i f
+@findex magit-subtree-pull
+This command pulls COMMIT from REPOSITORY into the PREFIX subtree.
+
+@item @kbd{O e} (@code{magit-subtree-export})
+@kindex O e
+@findex magit-subtree-export
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+The suffixes of this command export subtrees.
+
+If the @code{--prefix} argument is set, then the suffix commands use that
+prefix without prompting the user.  If it is unset, then they read
+the prefix in the minibuffer.
+
+@item @kbd{O e p} (@code{magit-subtree-push})
+@kindex O e p
+@findex magit-subtree-push
+This command extract the history of the subtree PREFIX and pushes it
+to REF on REPOSITORY@.
+
+@item @kbd{O e s} (@code{magit-subtree-split})
+@kindex O e s
+@findex magit-subtree-split
+This command extracts the history of the subtree PREFIX@.
+@end table
+
+@node Worktree
+@section Worktree
+
+Also see 
+@ifinfo
+@ref{git-worktree,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-worktree">git-worktree(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-worktree(1) manpage.
+@end iftex
+
+@table @asis
+@item @kbd{Z} (@code{magit-worktree})
+@kindex Z
+@findex magit-worktree
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+@item @kbd{Z b} (@code{magit-worktree-checkout})
+@kindex Z b
+@findex magit-worktree-checkout
+Checkout BRANCH in a new worktree at PATH@.
+
+@item @kbd{Z c} (@code{magit-worktree-branch})
+@kindex Z c
+@findex magit-worktree-branch
+Create a new BRANCH and check it out in a new worktree at PATH@.
+
+@item @kbd{Z m} (@code{magit-worktree-move})
+@kindex Z m
+@findex magit-worktree-move
+Move an existing worktree to a new PATH@.
+
+@item @kbd{Z k} (@code{magit-worktree-delete})
+@kindex Z k
+@findex magit-worktree-delete
+Delete a worktree, defaulting to the worktree at point.
+The primary worktree cannot be deleted.
+
+@item @kbd{Z g} (@code{magit-worktree-status})
+@kindex Z g
+@findex magit-worktree-status
+Show the status for the worktree at point.
+
+If there is no worktree at point, then read one in the minibuffer.
+If the worktree at point is the one whose status is already being
+displayed in the current buffer, then show it in Dired instead.
+@end table
+
+@node Sparse checkouts
+@section Sparse checkouts
+
+Sparse checkouts provide a way to restrict the working tree to a
+subset of directories.  See 
+@ifinfo
+@ref{git-sparse-checkout,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-sparse-checkout">git-sparse-checkout(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-sparse-checkout(1) manpage.
+@end iftex
+
+@strong{Warning}: Git introduced the @code{git sparse-checkout} command in version
+2.25 and still advertises it as experimental and subject to change.
+Magit's interface should be considered the same.  In particular, if
+Git introduces a backward incompatible change, Magit's sparse checkout
+functionality may be updated in a way that requires a more recent Git
+version.
+
+@table @asis
+@item @kbd{>} (@code{magit-sparse-checkout})
+@kindex >
+@findex magit-sparse-checkout
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+@item @kbd{> e} (@code{magit-sparse-checkout-enable})
+@kindex > e
+@findex magit-sparse-checkout-enable
+This command initializes a sparse checkout that includes only the
+files in the top-level directory.
+
+Note that @code{magit-sparse-checkout-set} and
+@code{magit-sparse-checkout-add} automatically initialize a sparse
+checkout if necessary.  However, you may want to call
+@code{magit-sparse-checkout-enable} explicitly to re-initialize a sparse
+checkout after calling @code{magit-sparse-checkout-disable}, to pass
+additional arguments to @code{git sparse-checkout init}, or to execute
+the initialization asynchronously.
+
+@item @kbd{> s} (@code{magit-sparse-checkout-set})
+@kindex > s
+@findex magit-sparse-checkout-set
+This command takes a list of directories and configures the sparse
+checkout to include only files in those subdirectories.  Any
+previously included directories are excluded unless they are in the
+provided list of directories.
+
+@item @kbd{> a} (@code{magit-sparse-checkout-add})
+@kindex > a
+@findex magit-sparse-checkout-add
+This command is like @code{magit-sparse-checkout-set}, but instead adds
+the specified list of directories to the set of directories that is
+already included in the sparse checkout.
+
+@item @kbd{> r} (@code{magit-sparse-checkout-reapply})
+@kindex > r
+@findex magit-sparse-checkout-reapply
+This command applies the currently configured sparse checkout
+patterns to the working tree.  This is useful to call if excluded
+files have been checked out after operations such as merging or
+rebasing.
+
+@item @kbd{> d} (@code{magit-sparse-checkout-disable})
+@kindex > d
+@findex magit-sparse-checkout-disable
+This command restores the full checkout.  To return to the previous
+sparse checkout, call @code{magit-sparse-checkout-enable}.
+@end table
+
+A sparse checkout can also be initiated when cloning a repository by
+using the @code{magit-clone-sparse} command in the @code{magit-clone} transient
+(see @ref{Cloning Repository}).
+
+If you want the status buffer to indicate when a sparse checkout is
+enabled, add the function @code{magit-sparse-checkout-insert-header} to
+@code{magit-status-headers-hook}.
+
+@node Bundle
+@section Bundle
+
+Also see 
+@ifinfo
+@ref{git-bundle,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-bundle">git-bundle(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-bundle(1) manpage.
+@end iftex
+
+@deffn Command magit-bundle
+This transient prefix command binds several suffix commands for
+running @code{git bundle} subcommands and displays them in a temporary
+buffer until a suffix is invoked.
+@end deffn
+
+@node Common Commands
+@section Common Commands
+
+@deffn Command magit-switch-to-repository-buffer
+@end deffn
+@deffn Command magit-switch-to-repository-buffer-other-window
+@end deffn
+@deffn Command magit-switch-to-repository-buffer-other-frame
+@end deffn
+@deffn Command magit-display-repository-buffer
+These commands read any existing Magit buffer that belongs to the
+current repository from the user and then switch to the selected
+buffer (without refreshing it).
+
+The last variant uses @code{magit-display-buffer} to do so and thus
+respects @code{magit-display-buffer-function}.
+@end deffn
+
+These are some of the commands that can be used in all buffers whose
+major-modes derive from @code{magit-mode}.  There are other common commands
+beside the ones below, but these didn't fit well anywhere else.
+
+@table @asis
+@item @kbd{C-w} (@code{magit-copy-section-value})
+@kindex C-w
+@findex magit-copy-section-value
+This command saves the value of the current section to the
+@code{kill-ring}, and, provided that the current section is a commit,
+branch, or tag section, it also pushes the (referenced) revision to
+the @code{magit-revision-stack}.
+
+When the current section is a branch or a tag, and a prefix argument
+is used, then it saves the revision at its tip to the @code{kill-ring}
+instead of the reference name.
+
+When the region is active, this command saves that to the
+@code{kill-ring}, like @code{kill-ring-save} would, instead of behaving as
+described above. If a prefix argument is used and the region is
+within a hunk, then it strips the diff marker column and keeps
+only either the added or removed lines, depending on the sign of
+the prefix argument.
+
+@item @kbd{M-w} (@code{magit-copy-buffer-revision})
+@kindex M-w
+@findex magit-copy-buffer-revision
+This command saves the revision being displayed in the current buffer
+to the @code{kill-ring} and also pushes it to the @code{magit-revision-stack}.  It
+is mainly intended for use in @code{magit-revision-mode} buffers, the only
+buffers where it is always unambiguous exactly which revision should
+be saved.
+
+Most other Magit buffers usually show more than one revision, in
+some way or another, so this command has to select one of them, and
+that choice might not always be the one you think would have been
+the best pick.
+@end table
+
+Outside of Magit @code{M-w} and @code{C-w} are usually bound to @code{kill-ring-save} and
+@code{kill-region}, and these commands would also be useful in Magit buffers.
+Therefore when the region is active, then both of these commands
+behave like @code{kill-ring-save} instead of as described above.
+
+@node Wip Modes
+@section Wip Modes
+
+Git keeps @strong{committed} changes around long enough for users to recover
+changes they have accidentally deleted.  It does so by not garbage
+collecting any committed but no longer referenced objects for a
+certain period of time, by default 30 days.
+
+But Git does @strong{not} keep track of @strong{uncommitted} changes in the working tree
+and not even the index (the staging area).  Because Magit makes it so
+convenient to modify uncommitted changes, it also makes it easy to
+shoot yourself in the foot in the process.
+
+For that reason Magit provides a global mode that saves @strong{tracked} files
+to work-in-progress references after or before certain actions.  (At
+present untracked files are never saved and for technical reasons
+nothing is saved before the first commit has been created).
+
+Two separate work-in-progress references are used to track the state
+of the index and of the working tree: @code{refs/wip/index/<branchref>} and
+@code{refs/wip/wtree/<branchref>}, where @code{<branchref>} is the full ref of the
+current branch, e.g., @code{refs/heads/master}.  When the @code{HEAD} is detached
+then @code{HEAD} is used in place of @code{<branchref>}.
+
+Checking out another branch (or detaching @code{HEAD}) causes the use of
+different wip refs for subsequent changes.
+
+@defopt magit-wip-mode
+When this mode is enabled, then uncommitted changes are committed
+to dedicated work-in-progress refs whenever appropriate (i.e., when
+dataloss would be a possibility otherwise).
+
+Setting this variable directly does not take effect; either use the
+Custom interface to do so or call the respective mode function.
+
+For historic reasons this mode is implemented on top of four other
+@code{magit-wip-*} modes, which can also be used individually, if you want
+finer control over when the wip refs are updated; but that is
+discouraged.  See @ref{Legacy Wip Modes}.
+@end defopt
+
+To view the log for a branch and its wip refs use the commands
+@code{magit-wip-log} and @code{magit-wip-log-current}.  You should use @code{--graph} when
+using these commands.
+
+@deffn Command magit-wip-log
+This command shows the log for a branch and its wip refs.
+With a negative prefix argument only the worktree wip ref is shown.
+
+The absolute numeric value of the prefix argument controls how many
+"branches" of each wip ref are shown.  This is only relevant if the
+value of @code{magit-wip-merge-branch} is @code{nil}.
+@end deffn
+
+@deffn Command magit-wip-log-current
+This command shows the log for the current branch and its wip refs.
+With a negative prefix argument only the worktree wip ref is shown.
+
+The absolute numeric value of the prefix argument controls how many
+"branches" of each wip ref are shown.  This is only relevant if the
+value of @code{magit-wip-merge-branch} is @code{nil}.
+@end deffn
+
+@table @asis
+@item @kbd{X w} (@code{magit-reset-worktree})
+@kindex X w
+@findex magit-reset-worktree
+This command resets the working tree to some commit read from the
+user and defaulting to the commit at point, while keeping the @code{HEAD}
+and index as-is.
+
+This can be used to restore files to the state committed to a wip
+ref.  Note that this will discard any unstaged changes that might
+have existed before invoking this command (but of course only after
+committing that to the working tree wip ref).
+@end table
+
+Note that even if you enable @code{magit-wip-mode} this won't give you
+perfect protection.  The most likely scenario for losing changes
+despite the use of @code{magit-wip-mode} is making a change outside Emacs and
+then destroying it also outside Emacs.  In some such a scenario,
+Magit, being an Emacs package, didn't get the opportunity to keep you
+from shooting yourself in the foot.
+
+When you are unsure whether Magit did commit a change to the wip refs,
+then you can explicitly request that all changes to all tracked files
+are being committed.
+
+@table @asis
+@item @kbd{M-x magit-wip-commit}
+@findex magit-wip-commit
+This command commits all changes to all tracked files to the index
+and working tree work-in-progress refs.  Like the modes described above,
+it does not commit untracked files, but it does check all tracked
+files for changes.  Use this command when you suspect that the modes
+might have overlooked a change made outside Emacs/Magit.
+@end table
+
+@defopt magit-wip-namespace
+The namespace used for work-in-progress refs.  It has to end with
+a slash.  The wip refs are named @code{<namespace>index/<branchref>} and
+@code{<namespace>wtree/<branchref>}.  When snapshots are created while
+the @code{HEAD} is detached then @code{HEAD} is used in place of @code{<branchref>}.
+@end defopt
+
+@defopt magit-wip-mode-lighter
+Mode-line lighter for @code{magit-wip--mode}.
+@end defopt
+
+@menu
+* Wip Graph::
+* Legacy Wip Modes::
+@end menu
+
+@node Wip Graph
+@subsection Wip Graph
+
+@defopt magit-wip-merge-branch
+This option controls whether the current branch is merged into the
+wip refs after a new commit was created on the branch.
+
+If non-nil and the current branch has new commits, then it is
+merged into the wip ref before creating a new wip commit.  This
+makes it easier to inspect wip history and the wip commits are
+never garbage collected.
+
+If nil and the current branch has new commits, then the wip ref
+is reset to the tip of the branch before creating a new wip
+commit.  With this setting wip commits are eventually garbage
+collected.
+@end defopt
+
+When @code{magit-wip-merge-branch} is @code{t}, then the history looks like this:
+
+@example
+  *--*--*--*--*--*       refs/wip/index/refs/heads/master
+ /     /     /
+A-----B-----C            refs/heads/master
+@end example
+
+When @code{magit-wip-merge-branch} is @code{nil}, then creating a commit on the real
+branch and then making a change causes the wip refs to be recreated to
+fork from the new commit.  But the old commits on the wip refs are not
+lost.  They are still available from the reflog.  To make it easier to
+see when the fork point of a wip ref was changed, an additional commit
+with the message "restart autosaving" is created on it (@code{xxO} commits
+below are such boundary commits).
+
+Starting with
+
+@example
+      BI0---BI1    refs/wip/index/refs/heads/master
+     /
+A---B              refs/heads/master
+     \
+      BW0---BW1    refs/wip/wtree/refs/heads/master
+@end example
+
+and committing the staged changes and editing and saving a file would
+result in
+
+@example
+      BI0---BI1        refs/wip/index/refs/heads/master
+     /
+A---B---C              refs/heads/master
+     \   \
+      \   CW0---CW1    refs/wip/wtree/refs/heads/master
+       \
+        BW0---BW1      refs/wip/wtree/refs/heads/master@@@{2@}
+@end example
+
+The fork-point of the index wip ref is not changed until some change
+is being staged.  Likewise just checking out a branch or creating a
+commit does not change the fork-point of the working tree wip ref.  The
+fork-points are not adjusted until there actually is a change that
+should be committed to the respective wip ref.
+
+@node Legacy Wip Modes
+@subsection Legacy Wip Modes
+
+It is recommended that you use the mode @code{magit-wip-mode} (which see) and
+ignore the existence of the following modes, which are preserved for
+historic reasons.
+
+Setting the following variables directly does not take effect; either
+use the Custom interface to do so or call the respective mode
+functions.
+
+@defopt magit-wip-after-save-mode
+When this mode is enabled, then saving a buffer that visits a file
+tracked in a Git repository causes its current state to be committed
+to the working tree wip ref for the current branch.
+@end defopt
+
+@defopt magit-wip-after-apply-mode
+When this mode is enabled, then applying (i.e., staging, unstaging,
+discarding, reversing, and regularly applying) a change to a file
+tracked in a Git repository causes its current state to be committed
+to the index and/or working tree wip refs for the current branch.
+@end defopt
+
+If you only ever edit files using Emacs and only ever interact with
+Git using Magit, then the above two modes should be enough to protect
+each and every change from accidental loss.  In practice nobody does
+that.  Two additional modes exists that do commit to the wip refs
+before making changes that could cause the loss of earlier changes.
+
+@defopt magit-wip-before-change-mode
+When this mode is enabled, then certain commands commit the existing
+changes to the files they are about to make changes to.
+@end defopt
+
+@defopt magit-wip-initial-backup-mode
+When this mode is enabled, then the current version of a file is
+committed to the worktree wip ref before the buffer visiting that
+file is saved for the first time since the buffer was created.
+
+This backs up the same version of the file that @code{backup-buffer} would
+save.  While @code{backup-buffer} uses a backup file, this mode uses the
+same worktree wip ref as used by the other Magit Wip modes.  Like
+@code{backup-buffer}, it only does this once; unless you kill the buffer
+and visit the file again only one backup will be created per Emacs
+session.
+
+This mode ignores the variables that affect @code{backup-buffer} and can be
+used along-side that function, which is recommended because it only
+backs up files that are tracked in a Git repository.
+@end defopt
+
+@defopt magit-wip-after-save-local-mode-lighter
+Mode-line lighter for @code{magit-wip-after-save-local-mode}.
+@end defopt
+
+@defopt magit-wip-after-apply-mode-lighter
+Mode-line lighter for @code{magit-wip-after-apply-mode}.
+@end defopt
+
+@defopt magit-wip-before-change-mode-lighter
+Mode-line lighter for @code{magit-wip-before-change-mode}.
+@end defopt
+
+@defopt magit-wip-initial-backup-mode-lighter
+Mode-line lighter for @code{magit-wip-initial-backup-mode}.
+@end defopt
+
+@node Commands for Buffers Visiting Files
+@section Commands for Buffers Visiting Files
+
+By default Magit defines a few global key bindings.  These bindings
+are a compromise between providing no bindings at all and providing
+the better bindings I would have liked to use instead.  Magit cannot
+provide the set of recommended bindings by default because those key
+sequences are strictly reserved for bindings added by the user.
+Also see @ref{Global Bindings} and @ref{Key Binding Conventions,,,elisp,}.
+
+To use the recommended bindings, add this to your init file and
+restart Emacs.
+
+@lisp
+(setq magit-define-global-key-bindings 'recommended)
+@end lisp
+
+If you don't want Magit to add any bindings to the global keymap at
+all, add this to your init file and restart Emacs.
+
+@lisp
+(setq magit-define-global-key-bindings nil)
+@end lisp
+
+@table @asis
+@item @kbd{C-c f} (@code{magit-file-dispatch})
+@itemx @kbd{C-c f s} (@code{magit-stage-file})
+@itemx @kbd{C-c f s} (@code{magit-stage-buffer-file})
+@itemx @kbd{C-c f u} (@code{magit-unstage-file})
+@itemx @kbd{C-c f u} (@code{magit-unstage-buffer-file})
+@itemx @kbd{C-c f , x} (@code{magit-file-untrack})
+@itemx @kbd{C-c f , r} (@code{magit-file-rename})
+@itemx @kbd{C-c f , k} (@code{magit-file-delete})
+@itemx @kbd{C-c f , c} (@code{magit-file-checkout})
+@itemx @kbd{C-c f D} (@code{magit-diff})
+@itemx @kbd{C-c f d} (@code{magit-diff-buffer-file})
+@itemx @kbd{C-c f L} (@code{magit-log})
+@itemx @kbd{C-c f l} (@code{magit-log-buffer-file})
+@itemx @kbd{C-c f t} (@code{magit-log-trace-definition})
+@itemx @kbd{C-c f M} (@code{magit-log-merged})
+@itemx @kbd{C-c f B} (@code{magit-blame})
+@itemx @kbd{C-c f b} (@code{magit-blame-additions})
+@itemx @kbd{C-c f r} (@code{magit-blame-removal})
+@itemx @kbd{C-c f f} (@code{magit-blame-reverse})
+@itemx @kbd{C-c f m} (@code{magit-blame-echo})
+@itemx @kbd{C-c f q} (@code{magit-blame-quit})
+@itemx @kbd{C-c f p} (@code{magit-blob-previous})
+@itemx @kbd{C-c f n} (@code{magit-blob-next})
+@itemx @kbd{C-c f v} (@code{magit-find-file})
+@itemx @kbd{C-c f V} (@code{magit-blob-visit-file})
+@itemx @kbd{C-c f g} (@code{magit-status-here})
+@itemx @kbd{C-c f G} (@code{magit-display-repository-buffer})
+@itemx @kbd{C-c f c} (@code{magit-commit})
+@itemx @kbd{C-c f e} (@code{magit-edit-line-commit})
+@kindex C-c f
+@kindex C-c f s
+@kindex C-c f s
+@kindex C-c f u
+@kindex C-c f u
+@kindex C-c f , x
+@kindex C-c f , r
+@kindex C-c f , k
+@kindex C-c f , c
+@kindex C-c f D
+@kindex C-c f d
+@kindex C-c f L
+@kindex C-c f l
+@kindex C-c f t
+@kindex C-c f M
+@kindex C-c f B
+@kindex C-c f b
+@kindex C-c f r
+@kindex C-c f f
+@kindex C-c f m
+@kindex C-c f q
+@kindex C-c f p
+@kindex C-c f n
+@kindex C-c f v
+@kindex C-c f V
+@kindex C-c f g
+@kindex C-c f G
+@kindex C-c f c
+@kindex C-c f e
+@findex magit-file-dispatch
+@findex magit-stage-file
+@findex magit-stage-buffer-file
+@findex magit-unstage-file
+@findex magit-unstage-buffer-file
+@findex magit-file-untrack
+@findex magit-file-rename
+@findex magit-file-delete
+@findex magit-file-checkout
+@findex magit-diff
+@findex magit-diff-buffer-file
+@findex magit-log
+@findex magit-log-buffer-file
+@findex magit-log-trace-definition
+@findex magit-log-merged
+@findex magit-blame
+@findex magit-blame-additions
+@findex magit-blame-removal
+@findex magit-blame-reverse
+@findex magit-blame-echo
+@findex magit-blame-quit
+@findex magit-blob-previous
+@findex magit-blob-next
+@findex magit-find-file
+@findex magit-blob-visit-file
+@findex magit-status-here
+@findex magit-display-repository-buffer
+@findex magit-commit
+@findex magit-edit-line-commit
+Each of these commands is documented individually right below,
+alongside their default key bindings.  The bindings shown above
+are the recommended bindings, which you can enable by following
+the instructions further up.
+
+@item @kbd{C-c M-g} (@code{magit-file-dispatch})
+@kindex C-c M-g
+@findex magit-file-dispatch
+This transient prefix command binds the following suffix commands
+and displays them in a temporary buffer until a suffix is invoked.
+
+@item @kbd{C-c M-g s} (@code{magit-stage-file})
+@itemx @kbd{C-c M-g s} (@code{magit-stage-buffer-file})
+@kindex C-c M-g s
+@kindex C-c M-g s
+@findex magit-stage-file
+@findex magit-stage-buffer-file
+Stage all changes to the file being visited in the current buffer.
+When not visiting a file, then the first command is used, which
+prompts for a file.
+
+@item @kbd{C-c M-g u} (@code{magit-unstage-file})
+@itemx @kbd{C-c M-g u} (@code{magit-unstage-buffer-file})
+@kindex C-c M-g u
+@kindex C-c M-g u
+@findex magit-unstage-file
+@findex magit-unstage-buffer-file
+Unstage all changes to the file being visited in the current buffer.
+When not visiting a file, then the first command is used, which
+prompts for a file.
+
+@item @kbd{C-c M-g , x} (@code{magit-file-untrack})
+@kindex C-c M-g , x
+@findex magit-file-untrack
+This command untracks a file read from the user, defaulting to the
+visited file.
+
+@item @kbd{C-c M-g , r} (@code{magit-file-rename})
+@kindex C-c M-g , r
+@findex magit-file-rename
+This command renames a file read from the user, defaulting to the
+visited file.
+
+@item @kbd{C-c M-g , k} (@code{magit-file-delete})
+@kindex C-c M-g , k
+@findex magit-file-delete
+This command deletes a file read from the user, defaulting to the
+visited file.
+
+@item @kbd{C-c M-g , c} (@code{magit-file-checkout})
+@kindex C-c M-g , c
+@findex magit-file-checkout
+This command updates a file in the working tree and index to the
+contents from a revision.  Both the revision and file are read
+from the user.
+
+@item @kbd{C-c M-g D} (@code{magit-diff})
+@kindex C-c M-g D
+@findex magit-diff
+This transient prefix command binds several diff suffix commands and
+infix arguments and displays them in a temporary buffer until a
+suffix is invoked.  See @ref{Diffing}.
+
+This is the same command that @code{d} is bound to in Magit buffers.
+If this command is invoked from a file-visiting buffer, then the
+initial value of the option (@code{--}) that limits the diff to certain
+file(s) is set to the visited file.
+
+@item @kbd{C-c M-g d} (@code{magit-diff-buffer-file})
+@kindex C-c M-g d
+@findex magit-diff-buffer-file
+This command shows the diff for the file of blob that the current
+buffer visits.
+@end table
+
+@defopt magit-diff-buffer-file-locked
+This option controls whether @code{magit-diff-buffer-file} uses a dedicated
+buffer.  See @ref{Modes and Buffers}.
+@end defopt
+
+@table @asis
+@item @kbd{C-c M-g L} (@code{magit-log})
+@kindex C-c M-g L
+@findex magit-log
+This transient prefix command binds several log suffix commands and
+infix arguments and displays them in a temporary buffer until a
+suffix is invoked.  See @ref{Logging}.
+
+This is the same command that @code{l} is bound to in Magit buffers.
+If this command is invoked from a file-visiting buffer, then the
+initial value of the option (@code{--}) that limits the log to certain
+file(s) is set to the visited file.
+
+@item @kbd{C-c M-g l} (@code{magit-log-buffer-file})
+@kindex C-c M-g l
+@findex magit-log-buffer-file
+This command shows the log for the file of blob that the current
+buffer visits.  Renames are followed when a prefix argument is used
+or when @code{--follow} is an active log argument.  When the region is
+active, the log is restricted to the selected line range.
+@end table
+
+@defopt magit-log-buffer-file-locked
+This option controls whether @code{magit-log-buffer-file} uses a dedicated
+buffer.  See @ref{Modes and Buffers}.
+@end defopt
+
+@table @asis
+@item @kbd{C-c M-g t} (@code{magit-log-trace-definition})
+@kindex C-c M-g t
+@findex magit-log-trace-definition
+This command shows the log for the definition at point.
+
+@item @kbd{C-c M-g M} (@code{magit-log-merged})
+@kindex C-c M-g M
+@findex magit-log-merged
+This command reads a commit and a branch in shows a log concerning
+the merge of the former into the latter.  This shows multiple commits
+even in case of a fast-forward merge.
+
+@item @kbd{C-c M-g B} (@code{magit-blame})
+@kindex C-c M-g B
+@findex magit-blame
+This transient prefix command binds all blaming suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.
+
+For more information about this and the following commands also see
+@ref{Blaming}.
+
+In addition to the @code{magit-blame} sub-transient, the dispatch transient
+also binds several blaming suffix commands directly.  See @ref{Blaming}
+for information about those commands and bindings.
+
+@item @kbd{C-c M-g p} (@code{magit-blob-previous})
+@kindex C-c M-g p
+@findex magit-blob-previous
+This command visits the previous blob which modified the current
+file.
+
+@item @kbd{C-c M-g n} (@code{magit-blob-next})
+@kindex C-c M-g n
+@findex magit-blob-next
+This command visits the next blob which modified the current file.
+
+@item @kbd{C-c M-g v} (@code{magit-find-file})
+@kindex C-c M-g v
+@findex magit-find-file
+This command reads a revision and file and visits the respective
+blob.
+
+@item @kbd{C-c M-g V} (@code{magit-blob-visit-file})
+@kindex C-c M-g V
+@findex magit-blob-visit-file
+This command visits the file from the working tree, corresponding
+to the current blob.  When visiting a blob or the version from the
+index, then it goes to the same location in the respective file in
+the working tree.
+
+@item @kbd{C-c M-g g} (@code{magit-status-here})
+@kindex C-c M-g g
+@findex magit-status-here
+This command displays the status of the current repository in a
+buffer, like @code{magit-status} does.  Additionally it tries to go to
+the position in that buffer, which corresponds to the position
+in the current file-visiting buffer (if any).
+
+@item @kbd{C-c M-g G} (@code{magit-display-repository-buffer})
+@kindex C-c M-g G
+@findex magit-display-repository-buffer
+This command reads and displays a Magit buffer belonging to the
+current repository, without refreshing it.
+
+@item @kbd{C-c M-g c} (@code{magit-commit})
+@kindex C-c M-g c
+@findex magit-commit
+This transient prefix command binds the following suffix commands
+along with the appropriate infix arguments and displays them in a
+temporary buffer until a suffix is invoked.  See @ref{Initiating a Commit}.
+
+@item @kbd{C-c M-g e} (@code{magit-edit-line-commit})
+@kindex C-c M-g e
+@findex magit-edit-line-commit
+This command makes the commit editable that added the current line.
+
+With a prefix argument it makes the commit editable that removes the
+line, if any.  The commit is determined using @code{git blame} and made
+editable using @code{git rebase --interactive} if it is reachable from
+@code{HEAD}, or by checking out the commit (or a branch that points at it)
+otherwise.
+@end table
+
+@node Minor Mode for Buffers Visiting Blobs
+@section Minor Mode for Buffers Visiting Blobs
+
+The @code{magit-blob-mode} enables certain Magit features in blob-visiting
+buffers.  Such buffers can be created using @code{magit-find-file} and some
+of the commands mentioned below, which also take care of turning on
+this minor mode.  Currently this mode only establishes a few key
+bindings, but this might be extended.
+
+@table @asis
+@item @kbd{p} (@code{magit-blob-previous})
+@kindex p
+@findex magit-blob-previous
+Visit the previous blob which modified the current file.
+
+@item @kbd{n} (@code{magit-blob-next})
+@kindex n
+@findex magit-blob-next
+Visit the next blob which modified the current file.
+
+@item @kbd{q} (@code{magit-kill-this-buffer})
+@kindex q
+@findex magit-kill-this-buffer
+Kill the current buffer.
+@end table
+
+@node Customizing
+@chapter Customizing
+
+Both Git and Emacs are highly customizable.  Magit is both a Git
+porcelain as well as an Emacs package, so it makes sense to customize
+it using both Git variables as well as Emacs options.  However this
+flexibility doesn't come without problems, including but not limited
+to the following.
+
+@itemize
+@item
+Some Git variables automatically have an effect in Magit without
+requiring any explicit support.  Sometimes that is desirable - in
+other cases, it breaks Magit.
+
+When a certain Git setting breaks Magit but you want to keep using
+that setting on the command line, then that can be accomplished by
+overriding the value for Magit only by appending something like
+@code{("-c" "some.variable=compatible-value")} to
+@code{magit-git-global-arguments}.
+
+@item
+Certain settings like @code{fetch.prune=true} are respected by Magit
+commands (because they simply call the respective Git command) but
+their value is not reflected in the respective transient buffers.
+In this case the @code{--prune} argument in @code{magit-fetch} might be active or
+inactive, but that doesn't keep the Git variable from being honored
+by the suffix commands anyway.  So pruning might happen despite the
+@code{--prune} arguments being displayed in a way that seems to indicate
+that no pruning will happen.
+@end itemize
+
+I intend to address these and similar issues in a future release.
+
+@menu
+* Per-Repository Configuration::
+* Essential Settings::
+@end menu
+
+@node Per-Repository Configuration
+@section Per-Repository Configuration
+
+Magit can be configured on a per-repository level using both Git
+variables as well as Emacs options.
+
+To set a Git variable for one repository only, simply set it in
+@code{/path/to/repo/.git/config} instead of @code{$HOME/.gitconfig} or
+@code{/etc/gitconfig}.  See 
+@ifinfo
+@ref{git-config,,,gitman,}.
+@end ifinfo
+@ifhtml
+@html
+the <a href="http://git-scm.com/docs/git-config">git-config(1)</a> manpage.
+@end html
+@end ifhtml
+@iftex
+the git-config(1) manpage.
+@end iftex
+
+Similarly, Emacs options can be set for one repository only by editing
+@code{/path/to/repo/.dir-locals.el}.  See @ref{Directory Variables,,,emacs,}.
+For example to disable automatic refreshes of file-visiting buffers in
+just one huge repository use this:
+
+@itemize
+@item
+@code{/path/to/huge/repo/.dir-locals.el}
+
+@lisp
+((nil . ((magit-refresh-buffers . nil))))
+@end lisp
+@end itemize
+
+It might only be costly to insert certain information into Magit
+buffers for repositories that are exceptionally large, in which case
+you can disable the respective section inserters just for that
+repository:
+
+@itemize
+@item
+@code{/path/to/tag/invested/repo/.dir-locals.el}
+
+@lisp
+((magit-status-mode
+  . ((eval . (magit-disable-section-inserter 'magit-insert-tags-header)))))
+@end lisp
+@end itemize
+
+@defun magit-disable-section-inserter fn
+This function disables the section inserter FN in the current
+repository.  It is only intended for use in @code{.dir-locals.el} and
+@code{.dir-locals-2.el}.
+@end defun
+
+If you want to apply the same settings to several, but not all,
+repositories then keeping the repository-local config files in sync
+would quickly become annoying.  To avoid that you can create config
+files for certain classes of repositories (e.g., "huge repositories")
+and then include those files in the per-repository config files.
+For example:
+
+@itemize
+@item
+@code{/path/to/huge/repo/.git/config}
+
+@example
+[include]
+        path = /path/to/huge-gitconfig
+@end example
+
+@item
+@code{/path/to/huge-gitconfig}
+
+@example
+[status]
+        showUntrackedFiles = no
+@end example
+
+@item
+@code{$HOME/.emacs.d/init.el}
+
+@lisp
+(dir-locals-set-class-variables 'huge-git-repository
+   '((nil . ((magit-refresh-buffers . nil)))))
+
+(dir-locals-set-directory-class
+   "/path/to/huge/repo/" 'huge-git-repository)
+@end lisp
+@end itemize
+
+@node Essential Settings
+@section Essential Settings
+
+The next three sections list and discuss several variables that many
+users might want to customize, for safety and/or performance reasons.
+
+@menu
+* Safety::
+* Performance::
+* Global Bindings::
+@end menu
+
+@node Safety
+@subsection Safety
+
+This section discusses various variables that you might want to
+change (or @strong{not} change) for safety reasons.
+
+Git keeps @strong{committed} changes around long enough for users to recover
+changes they have accidentally been deleted.  It does not do the same
+for @strong{uncommitted} changes in the working tree and not even the index
+(the staging area).  Because Magit makes it so easy to modify
+uncommitted changes, it also makes it easy to shoot yourself in the
+foot in the process.  For that reason Magit provides three global
+modes that save @strong{tracked} files to work-in-progress references after or
+before certain actions.  See @ref{Wip Modes}.
+
+These modes are not enabled by default because of performance
+concerns.  Instead a lot of potentially destructive commands require
+confirmation every time they are used.  In many cases this can be
+disabled by adding a symbol to @code{magit-no-confirm} (see @ref{Completion and Confirmation}).  If you enable the various wip modes then you should
+add @code{safe-with-wip} to this list.
+
+Similarly it isn't necessary to require confirmation before moving a
+file to the system trash - if you trashed a file by mistake then you
+can recover it from there.  Option @code{magit-delete-by-moving-to-trash}
+controls whether the system trash is used, which is the case by default.
+Nevertheless, @code{trash} isn't a member of @code{magit-no-confirm} - you
+might want to change that.
+
+By default buffers visiting files are automatically reverted when the
+visited file changes on disk.  This isn't as risky as it might seem,
+but to make an informed decision you should see @ref{Risk of Reverting Automatically}.
+
+@node Performance
+@subsection Performance
+
+After Magit has run @code{git} for side-effects, it also refreshes the
+current Magit buffer and the respective status buffer.  This is
+necessary because otherwise outdated information might be displayed
+without the user noticing.  Magit buffers are updated by recreating
+their content from scratch, which makes updating simpler and less
+error-prone, but also more costly.  Keeping it simple and just
+re-creating everything from scratch is an old design decision and
+departing from that will require major refactoring.
+
+Meanwhile you can tell Magit to only automatically refresh the current
+Magit buffer, but not the status buffer.  If you do that, then the
+status buffer is only refreshed automatically if it is the
+current buffer.
+
+@lisp
+(setq magit-refresh-status-buffer nil)
+@end lisp
+
+You should also check whether any third-party packages have added
+anything to @code{magit-refresh-buffer-hook}, @code{magit-pre-refresh-hook}, and
+@code{magit-post-refresh-hook}.  If so, then check whether those additions
+impact performance significantly.
+
+Magit can be told to refresh buffers verbosely using @code{M-x
+magit-toggle-verbose-refresh}.  Enabling this helps figuring out which
+sections are bottlenecks. Each line printed to the @code{*Messages*} buffer
+contains a section name, the number of seconds it took to show this
+section, and from 0 to 2 exclamation marks: the more exclamation marks
+the slower the section is.
+
+Magit also reverts buffers for visited files located inside the
+current repository when the visited file changes on disk.  That is
+implemented on top of @code{auto-revert-mode} from the built-in library
+@code{autorevert}.  To figure out whether that impacts performance, check
+whether performance is significantly worse, when many buffers exist
+and/or when some buffers visit files using TRAMP@.  If so, then this
+should help.
+
+@lisp
+(setq auto-revert-buffer-list-filter
+      'magit-auto-revert-repository-buffer-p)
+@end lisp
+
+For alternative approaches see @ref{Automatic Reverting of File-Visiting Buffers}.
+
+If you have enabled any features that are disabled by default, then
+you should check whether they impact performance significantly.  It's
+likely that they were not enabled by default because it is known that
+they reduce performance at least in large repositories.
+
+If performance is only slow inside certain unusually large
+repositories, then you might want to disable certain features on a
+per-repository or per-repository-class basis only.  See
+@ref{Per-Repository Configuration}.  For example it takes a long time to
+determine the next and current tag in repository with exceptional
+numbers of tags.  It would therefore be a good idea to disable
+@code{magit-insert-tags-headers}, as explained at the mentioned node.
+
+@menu
+* Microsoft Windows Performance::
+* MacOS Performance::
+@end menu
+
+@anchor{Log Performance}
+@subsubheading Log Performance
+
+When showing logs, Magit limits the number of commits initially shown
+in the hope that this avoids unnecessary work.  When @code{--graph} is
+used, then this unfortunately does not have the desired effect for
+large histories.  Junio, Git's maintainer, said on the Git mailing
+list (@uref{https://www.spinics.net/lists/git/msg232230.html}): "@code{--graph} wants
+to compute the whole history and the max-count only affects the output
+phase after @code{--graph} does its computation".
+
+In other words, it's not that Git is slow at outputting the
+differences, or that Magit is slow at parsing the output - the problem
+is that Git first goes outside and has a smoke.
+
+We actually work around this issue by limiting the number of commits
+not only by using @code{-<N>} but by also using a range.  But unfortunately
+that's not always possible.
+
+When more than a few thousand commits are shown, then the use of
+@code{--graph} can slow things down.
+
+Using @code{--color --graph} is even slower.  Magit uses code that is part of
+Emacs to turn control characters into faces.  That code is pretty slow
+and this is quite noticeable when showing a log with many branches and
+merges.  For that reason @code{--color} is not enabled by default anymore.
+Consider leaving it at that.
+
+@anchor{Diff Performance}
+@subsubheading Diff Performance
+
+If diffs are slow, then consider turning off some optional diff
+features by setting all or some of the following variables to @code{nil}:
+@code{magit-diff-highlight-indentation}, @code{magit-diff-highlight-trailing},
+@code{magit-diff-paint-whitespace}, @code{magit-diff-highlight-hunk-body}, and
+@code{magit-diff-refine-hunk}.
+
+When showing a commit instead of some arbitrary diff, then some
+additional information is displayed.  Calculating this information
+can be quite expensive given certain circumstances.  If looking at
+a commit using @code{magit-revision-mode} takes considerably more time than
+looking at the same commit in @code{magit-diff-mode}, then consider setting
+@code{magit-revision-insert-related-refs} to @code{nil}.
+
+When you are often confronted with diffs that contain deleted files,
+then you might want to enable the @code{--irreversible-delete} argument.  If
+you do that then diffs still show that a file was deleted but without
+also showing the complete deleted content of the file.  This argument
+is not available by default, see @ref{Enabling and Disabling Suffixes,,,transient,}.  Once you have done that you should enable it and save that
+setting, see @ref{Saving Values,,,transient,}.  You should do this in both
+the diff (@code{d}) and the diff refresh (@code{D}) transient popups.
+
+@anchor{Refs Buffer Performance}
+@subsubheading Refs Buffer Performance
+
+When refreshing the "references buffer" is slow, then that's usually
+because several hundred refs are being displayed.  The best way to
+address that is to display fewer refs, obviously.
+
+If you are not, or only mildly, interested in seeing the list of tags,
+then start by not displaying them:
+
+@lisp
+(remove-hook 'magit-refs-sections-hook 'magit-insert-tags)
+@end lisp
+
+Then you should also make sure that the listed remote branches
+actually all exist.  You can do so by pruning branches which no longer
+exist using @code{f-pa}.
+
+@anchor{Committing Performance}
+@subsubheading Committing Performance
+
+When you initiate a commit, then Magit by default automatically shows
+a diff of the changes you are about to commit.  For large commits this
+can take a long time, which is especially distracting when you are
+committing large amounts of generated data which you don't actually
+intend to inspect before committing.  This behavior can be turned off
+using:
+
+@lisp
+(remove-hook 'server-switch-hook 'magit-commit-diff)
+(remove-hook 'with-editor-filter-visit-hook 'magit-commit-diff)
+@end lisp
+
+Then you can type @code{C-c C-d} to show the diff when you actually want to
+see it, but only then.  Alternatively you can leave the hook alone and
+just type @code{C-g} in those cases when it takes too long to generate the
+diff.  If you do that, then you will end up with a broken diff buffer,
+but doing it this way has the advantage that you usually get to see
+the diff, which is useful because it increases the odds that you spot
+potential issues.
+
+@node Microsoft Windows Performance
+@unnumberedsubsubsec Microsoft Windows Performance
+
+In order to update the status buffer, @code{git} has to be run a few dozen
+times.  That is problematic on Microsoft Windows, because that
+operating system is exceptionally slow at starting processes.  Sadly
+this is an issue that can only be fixed by Microsoft itself, and they
+don't appear to be particularly interested in doing so.
+
+Beside the subprocess issue, there are also other Windows-specific
+performance issues. Some of these have workarounds.  The
+maintainers of "Git for Windows" try to improve performance on Windows.
+Always use the latest release in order to benefit from the latest
+performance tweaks.  Magit too tries to work around some
+Windows-specific issues.
+
+According to some sources, setting the following Git variables can also
+help.
+
+@example
+git config --global core.preloadindex true   # default since v2.1
+git config --global core.fscache true        # default since v2.8
+git config --global gc.auto 256
+@end example
+
+You should also check whether an anti-virus program is affecting
+performance.
+
+@node MacOS Performance
+@unnumberedsubsubsec MacOS Performance
+
+Before Emacs 26.1 child processes were created using @code{fork} on macOS@.
+That needlessly copied GUI resources, which is expensive.  The result
+was that forking took about 30 times as long on Darwin than on Linux,
+and because Magit starts many @code{git} processes that made quite a
+difference.
+
+So make sure that you are using at least Emacs 26.1, in which case the
+faster @code{vfork} will be used.  (The creation of child processes still
+takes about twice as long on Darwin compared to Linux.)  See @footnote{@uref{https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html}}
+for more information.
+
+Additionally, @code{git} installed from a package manager like @code{brew} or @code{nix}
+seems to be slower than the native executable. Profile the @code{git}
+executable you're running against the one at @code{/usr/bin/git}, and if
+you notice a notable difference try using the latter as
+@code{magit-git-executable}.
+
+@node Global Bindings
+@subsection Global Bindings
+
+@defopt magit-define-global-key-bindings
+This option controls which set of Magit key bindings, if any, may
+be added to the global keymap, even before Magit is first used in
+the current Emacs session.
+
+@itemize
+@item
+If the value is @code{nil}, no bindings are added.
+
+@item
+If @code{default}, maybe add:
+
+@multitable {aaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa}
+@item @code{C-x g}
+@tab @code{magit-status}
+@item @code{C-x M-g}
+@tab @code{magit-dispatch}
+@item @code{C-c M-g}
+@tab @code{magit-file-dispatch}
+@end multitable
+
+@item
+If @code{recommended}, maybe add:
+
+@multitable {aaaaaaa} {aaaaaaaaaaaaaaaaaaaaa}
+@item @code{C-x g}
+@tab @code{magit-status}
+@item @code{C-c g}
+@tab @code{magit-dispatch}
+@item @code{C-c f}
+@tab @code{magit-file-dispatch}
+@end multitable
+
+These bindings are strongly recommended, but we cannot use
+them by default, because the @code{C-c <LETTER>} namespace is
+strictly reserved for bindings added by the user (see
+@ref{Key Binding Conventions,,,elisp,}).
+@end itemize
+
+The bindings in the chosen set may be added when
+@code{after-init-hook} is run.  Each binding is added if, and only
+if, at that time no other key is bound to the same command,
+and no other command is bound to the same key.  In other words
+we try to avoid adding bindings that are unnecessary, as well
+as bindings that conflict with other bindings.
+
+Adding these bindings is delayed until @code{after-init-hook} is
+run to allow users to set the variable anywhere in their init
+file (without having to make sure to do so before @code{magit} is
+loaded or autoloaded) and to increase the likelihood that all
+the potentially conflicting user bindings have already been
+added.
+
+To set this variable use either @code{setq} or the Custom interface.
+Do not use the function @code{customize-set-variable} because doing
+that would cause Magit to be loaded immediately, when that form
+is evaluated (this differs from @code{custom-set-variables}, which
+doesn't load the libraries that define the customized variables).
+
+Setting this variable has no effect if @code{after-init-hook} has
+already been run.
+@end defopt
+
+@node Plumbing
+@chapter Plumbing
+
+The following sections describe how to use several of Magit's core
+abstractions to extend Magit itself or implement a separate extension.
+
+A few of the low-level features used by Magit have been factored out
+into separate libraries/packages, so that they can be used by other
+packages, without having to depend on Magit.  See @ref{Top,,,with-editor,} for
+information about @code{with-editor}.  @code{transient} doesn't have a manual yet.
+
+If you are trying to find an unused key that you can bind to a
+command provided by your own Magit extension, then checkout
+@uref{https://github.com/magit/magit/wiki/Plugin-Dispatch-Key-Registry}.
+
+@menu
+* Calling Git::
+* Section Plumbing::
+* Refreshing Buffers::
+* Conventions::
+@end menu
+
+@node Calling Git
+@section Calling Git
+
+Magit provides many specialized functions for calling Git.  All of
+these functions are defined in either @code{magit-git.el} or @code{magit-process.el}
+and have one of the prefixes @code{magit-run-}, @code{magit-call-}, @code{magit-start-},
+or @code{magit-git-} (which is also used for other things).
+
+All of these functions accept an indefinite number of arguments, which
+are strings that specify command line arguments for Git (or in some
+cases an arbitrary executable).  These arguments are flattened before
+being passed on to the executable; so instead of strings they can also
+be lists of strings and arguments that are @code{nil} are silently dropped.
+Some of these functions also require a single mandatory argument
+before these command line arguments.
+
+Roughly speaking, these functions run Git either to get some value or
+for side-effects.  The functions that return a value are useful to
+collect the information necessary to populate a Magit buffer, while
+the others are used to implement Magit commands.
+
+The functions in the value-only group always run synchronously, and
+they never trigger a refresh.  The function in the side-effect group
+can be further divided into subgroups depending on whether they run
+Git synchronously or asynchronously, and depending on whether they
+trigger a refresh when the executable has finished.
+
+@menu
+* Getting a Value from Git::
+* Calling Git for Effect::
+@end menu
+
+@node Getting a Value from Git
+@subsection Getting a Value from Git
+
+These functions run Git in order to get a value, an exit
+status, or output.  Of course you could also use them to run Git
+commands that have side-effects, but that should be avoided.
+
+@defun magit-git-exit-code &rest args
+Executes git with ARGS and returns its exit code.
+@end defun
+
+@defun magit-git-success &rest args
+Executes git with ARGS and returns @code{t} if the exit code is @code{0}, @code{nil}
+otherwise.
+@end defun
+
+@defun magit-git-failure &rest args
+Executes git with ARGS and returns @code{t} if the exit code is @code{1}, @code{nil}
+otherwise.
+@end defun
+
+@defun magit-git-true &rest args
+Executes git with ARGS and returns @code{t} if the first line printed by
+git is the string "true", @code{nil} otherwise.
+@end defun
+
+@defun magit-git-false &rest args
+Executes git with ARGS and returns @code{t} if the first line printed by
+git is the string "false", @code{nil} otherwise.
+@end defun
+
+@defun magit-git-insert &rest args
+Executes git with ARGS and inserts its output at point.
+@end defun
+
+@defun magit-git-string &rest args
+Executes git with ARGS and returns the first line of its output.  If
+there is no output or if it begins with a newline character, then
+this returns @code{nil}.
+@end defun
+
+@defun magit-git-lines &rest args
+Executes git with ARGS and returns its output as a list of lines.
+Empty lines anywhere in the output are omitted.
+@end defun
+
+@defun magit-git-items &rest args
+Executes git with ARGS and returns its null-separated output as a
+list.  Empty items anywhere in the output are omitted.
+
+If the value of option @code{magit-git-debug} is non-nil and git exits with
+a non-zero exit status, then warn about that in the echo area and
+add a section containing git's standard error in the current
+repository's process buffer.
+@end defun
+
+@defun magit-process-git destination &rest args
+Calls Git synchronously in a separate process, returning its exit
+code.  DESTINATION specifies how to handle the output, like for
+@code{call-process}, except that file handlers are supported.  Enables
+Cygwin's "noglob" option during the call and ensures unix eol
+conversion.
+@end defun
+
+@defun magit-process-file process &optional infile buffer display &rest args
+Processes files synchronously in a separate process.  Identical to
+@code{process-file} but temporarily enables Cygwin's "noglob" option during
+the call and ensures unix eol conversion.
+@end defun
+
+If an error occurs when using one of the above functions, then that
+is usually due to a bug, i.e., using an argument which is not
+actually supported.  Such errors are usually not reported, but when
+they occur we need to be able to debug them.
+
+@defopt magit-git-debug
+Whether to report errors that occur when using @code{magit-git-insert},
+@code{magit-git-string}, @code{magit-git-lines}, or @code{magit-git-items}.  This does
+not actually raise an error.  Instead a message is shown in the echo
+area, and git's standard error is insert into a new section in the
+current repository's process buffer.
+@end defopt
+
+@defun magit-git-str &rest args
+This is a variant of @code{magit-git-string} that ignores the option
+@code{magit-git-debug}.  It is mainly intended to be used while handling
+errors in functions that do respect that option.  Using such a
+function while handing an error could cause yet another error and
+therefore lead to an infinite recursion.  You probably won't ever
+need to use this function.
+@end defun
+
+@node Calling Git for Effect
+@subsection Calling Git for Effect
+
+These functions are used to run git to produce some effect.  Most
+Magit commands that actually run git do so by using such a function.
+
+Because we do not need to consume git's output when using these
+functions, their output is instead logged into a per-repository
+buffer, which can be shown using @code{$} from a Magit buffer or @code{M-x
+magit-process} elsewhere.
+
+These functions can have an effect in two distinct ways.  Firstly,
+running git may change something, i.e., create or push a new commit.
+Secondly, that change may require that Magit buffers are refreshed to
+reflect the changed state of the repository.  But refreshing isn't
+always desirable, so only some of these functions do perform such a
+refresh after git has returned.
+
+Sometimes it is useful to run git asynchronously.  For example, when
+the user has just initiated a push, then there is no reason to make
+her wait until that has completed.  In other cases it makes sense to
+wait for git to complete before letting the user do something else.
+For example after staging a change it is useful to wait until after
+the refresh because that also automatically moves to the next change.
+
+@defun magit-call-git &rest args
+Calls git synchronously with ARGS@.
+@end defun
+
+@defun magit-call-process program &rest args
+Calls PROGRAM synchronously with ARGS@.
+@end defun
+
+@defun magit-run-git &rest args
+Calls git synchronously with ARGS and then refreshes.
+@end defun
+
+@defun magit-run-git-with-input &rest args
+Calls git synchronously with ARGS and sends it the content of the
+current buffer on standard input.
+
+If the current buffer's @code{default-directory} is on a remote
+filesystem, this function actually runs git asynchronously.  But
+then it waits for the process to return, so the function itself is
+synchronous.
+@end defun
+
+@defun magit-git &rest args
+Calls git synchronously with ARGS for side-effects only.  This
+function does not refresh the buffer.
+@end defun
+
+@defun magit-git-wash washer &rest args
+Execute Git with ARGS, inserting washed output at point.  Actually
+first insert the raw output at point.  If there is no output call
+@code{magit-cancel-section}.  Otherwise temporarily narrow the buffer to
+the inserted text, move to its beginning, and then call function
+WASHER with ARGS as its sole argument.
+@end defun
+
+And now for the asynchronous variants.
+
+@defun magit-run-git-async &rest args
+Start Git, prepare for refresh, and return the process object.
+ARGS is flattened and then used as arguments to Git.
+
+Display the command line arguments in the echo area.
+
+After Git returns some buffers are refreshed: the buffer that was
+current when this function was called (if it is a Magit buffer and
+still alive), as well as the respective Magit status buffer.
+Unmodified buffers visiting files that are tracked in the current
+repository are reverted if @code{magit-revert-buffers} is non-nil.
+@end defun
+
+@defun magit-run-git-with-editor &rest args
+Export GIT@math{_EDITOR} and start Git.  Also prepare for refresh and
+return the process object.  ARGS is flattened and then used as
+arguments to Git.
+
+Display the command line arguments in the echo area.
+
+After Git returns some buffers are refreshed: the buffer that was
+current when this function was called (if it is a Magit buffer and
+still alive), as well as the respective Magit status buffer.
+@end defun
+
+@defun magit-start-git input &rest args
+Start Git, prepare for refresh, and return the process object.
+
+If INPUT is non-nil, it has to be a buffer or the name of an
+existing buffer.  The buffer content becomes the processes
+standard input.
+
+Option @code{magit-git-executable} specifies the Git executable and option
+@code{magit-git-global-arguments} specifies constant arguments.  The
+remaining arguments ARGS specify arguments to Git.  They are
+flattened before use.
+
+After Git returns, some buffers are refreshed: the buffer that was
+current when this function was called (if it is a Magit buffer and
+still alive), as well as the respective Magit status buffer.
+Unmodified buffers visiting files that are tracked in the current
+repository are reverted if @code{magit-revert-buffers} is non-nil.
+@end defun
+
+@defun magit-start-process &rest args
+Start PROGRAM, prepare for refresh, and return the process object.
+
+If optional argument INPUT is non-nil, it has to be a buffer or
+the name of an existing buffer.  The buffer content becomes the
+processes standard input.
+
+The process is started using @code{start-file-process} and then setup to
+use the sentinel @code{magit-process-sentinel} and the filter
+@code{magit-process-filter}.  Information required by these functions is
+stored in the process object.  When this function returns the
+process has not started to run yet so it is possible to override the
+sentinel and filter.
+
+After the process returns, @code{magit-process-sentinel} refreshes the
+buffer that was current when @code{magit-start-process} was called (if it
+is a Magit buffer and still alive), as well as the respective Magit
+status buffer.  Unmodified buffers visiting files that are tracked
+in the current repository are reverted if @code{magit-revert-buffers} is
+non-nil.
+@end defun
+
+@defvar magit-this-process
+The child process which is about to start.  This can be used to
+change the filter and sentinel.
+@end defvar
+
+@defvar magit-process-raise-error
+When this is non-nil, then @code{magit-process-sentinel} raises an error if
+git exits with a non-zero exit status.  For debugging purposes.
+@end defvar
+
+@node Section Plumbing
+@section Section Plumbing
+
+@menu
+* Creating Sections::
+* Section Selection::
+* Matching Sections::
+@end menu
+
+@node Creating Sections
+@subsection Creating Sections
+
+@defmac magit-insert-section &rest args
+Insert a section at point.
+
+TYPE is the section type, a symbol.  Many commands that act on the
+current section behave differently depending on that type.  Also if
+a variable @code{magit-TYPE-section-map} exists, then use that as the
+text-property @code{keymap} of all text belonging to the section (but this
+may be overwritten in subsections).  TYPE can also have the form
+@code{(eval FORM)} in which case FORM is evaluated at runtime.
+
+Optional VALUE is the value of the section, usually a string that is
+required when acting on the section.
+
+When optional HIDE is non-nil collapse the section body by default,
+i.e., when first creating the section, but not when refreshing the
+buffer.  Otherwise, expand it by default.  This can be overwritten using
+@code{magit-section-set-visibility-hook}.  When a section is recreated
+during a refresh, then the visibility of predecessor is inherited
+and HIDE is ignored (but the hook is still honored).
+
+BODY is any number of forms that actually insert the section's
+heading and body.  Optional NAME, if specified, has to be a symbol,
+which is then bound to the struct of the section being inserted.
+
+Before BODY is evaluated the @code{start} of the section object is set to
+the value of @code{point} and after BODY was evaluated its @code{end} is set to
+the new value of @code{point}; BODY is responsible for moving @code{point}
+forward.
+
+If it turns out inside BODY that the section is empty, then
+@code{magit-cancel-section} can be used to abort and remove all traces of
+the partially inserted section.  This can happen when creating a
+section by washing Git's output and Git didn't actually output
+anything this time around.
+@end defmac
+
+@defun magit-insert-heading &rest args
+Insert the heading for the section currently being inserted.
+
+This function should only be used inside @code{magit-insert-section}.
+
+When called without any arguments, then just set the @code{content} slot of
+the object representing the section being inserted to a marker at
+@code{point}.  The section should only contain a single line when this
+function is used like this.
+
+When called with arguments ARGS, which have to be strings, then
+insert those strings at point.  The section should not contain any
+text before this happens and afterwards it should again only contain
+a single line.  If the @code{face} property is set anywhere inside any of
+these strings, then insert all of them unchanged.  Otherwise use the
+@code{magit-section-heading} face for all inserted text.
+
+The @code{content} property of the section struct is the end of the heading
+(which lasts from @code{start} to @code{content}) and the beginning of the body
+(which lasts from @code{content} to @code{end}).  If the value of @code{content} is nil,
+then the section has no heading and its body cannot be collapsed.
+If a section does have a heading then its height must be exactly one
+line, including a trailing newline character.  This isn't enforced;
+you are responsible for getting it right.  The only exception is
+that this function does insert a newline character if necessary.
+@end defun
+
+@defun magit-cancel-section
+Cancel the section currently being inserted.  This exits the
+innermost call to @code{magit-insert-section} and removes all traces of
+what has already happened inside that call.
+@end defun
+
+@defun magit-define-section-jumper sym title &optional value
+Define an interactive function to go to section SYM@.  TITLE is the
+displayed title of the section.
+@end defun
+
+@node Section Selection
+@subsection Section Selection
+
+@defun magit-current-section
+Return the section at point.
+@end defun
+
+@defun magit-region-sections &optional condition multiple
+Return a list of the selected sections.
+
+When the region is active and constitutes a valid section
+selection, then return a list of all selected sections.  This is
+the case when the region begins in the heading of a section and
+ends in the heading of the same section or in that of a sibling
+section.  If optional MULTIPLE is non-nil, then the region cannot
+begin and end in the same section.
+
+When the selection is not valid, then return nil.  In this case,
+most commands that can act on the selected sections will instead
+act on the section at point.
+
+When the region looks like it would in any other buffer then
+the selection is invalid.  When the selection is valid then the
+region uses the @code{magit-section-highlight} face.  This does not
+apply to diffs where things get a bit more complicated, but even
+here if the region looks like it usually does, then that's not
+a valid selection as far as this function is concerned.
+
+If optional CONDITION is non-nil, then the selection not only
+has to be valid; all selected sections additionally have to match
+CONDITION, or nil is returned.  See @code{magit-section-match} for the
+forms CONDITION can take.
+@end defun
+
+@defun magit-region-values &optional condition multiple
+Return a list of the values of the selected sections.
+
+Return the values that themselves would be returned by
+@code{magit-region-sections} (which see).
+@end defun
+
+@node Matching Sections
+@subsection Matching Sections
+
+@table @asis
+@item @kbd{M-x magit-describe-section-briefly}
+@findex magit-describe-section-briefly
+Show information about the section at point.  This command is
+intended for debugging purposes.
+@end table
+
+@defun magit-section-ident section
+Return an unique identifier for SECTION@.  The return value has the
+form @code{((TYPE . VALUE)...)}.
+@end defun
+
+@defun magit-get-section ident &optional root
+Return the section identified by IDENT@.  IDENT has to be a list as
+returned by @code{magit-section-ident}.
+@end defun
+
+@defun magit-section-match condition &optional section
+Return @code{t} if SECTION matches CONDITION@.
+SECTION defaults to the section at point.  If SECTION is not
+specified and there also is no section at point, then return
+@code{nil}.
+
+CONDITION can take the following forms:
+@itemize
+@item
+@code{(CONDITION...)}
+
+matches if any of the CONDITIONs matches.
+
+@item
+@code{[CLASS...]}
+
+matches if the section's class is the same
+as the first CLASS or a subclass of that;
+the section's parent class matches the
+second CLASS; and so on.
+
+@item
+@code{[* CLASS...]}
+
+matches sections that match @code{[CLASS...]} and
+also recursively all their child sections.
+
+@item
+@code{CLASS}
+
+matches if the section's class is the same
+as CLASS or a subclass of that; regardless
+of the classes of the parent sections.
+@end itemize
+
+Each CLASS should be a class symbol, identifying a class that
+derives from @code{magit-section}.  For backward compatibility CLASS
+can also be a "type symbol".  A section matches such a symbol
+if the value of its @code{type} slot is @code{eq}.  If a type symbol has
+an entry in @code{magit--section-type-alist}, then a section also
+matches that type if its class is a subclass of the class that
+corresponds to the type as per that alist.
+
+Note that it is not necessary to specify the complete section
+lineage as printed by @code{magit-describe-section-briefly}, unless
+of course you want to be that precise.
+@end defun
+
+@defun magit-section-value-if condition &optional section
+If the section at point matches CONDITION, then return its value.
+
+If optional SECTION is non-nil then test whether that matches
+instead.  If there is no section at point and SECTION is nil,
+then return nil.  If the section does not match, then return
+nil.
+
+See @code{magit-section-match} for the forms CONDITION can take.
+@end defun
+
+@defun magit-section-case &rest clauses
+Choose among clauses on the type of the section at point.
+
+Each clause looks like (CONDITION BODY@dots{}).  The type of the
+section is compared against each CONDITION; the BODY forms of the
+first match are evaluated sequentially and the value of the last
+form is returned.  Inside BODY the symbol @code{it} is bound to the
+section at point.  If no clause succeeds or if there is no
+section at point return nil.
+
+See @code{magit-section-match} for the forms CONDITION can take.
+Additionally a CONDITION of t is allowed in the final clause and
+matches if no other CONDITION match, even if there is no section at
+point.
+@end defun
+
+@defvar magit-root-section
+The root section in the current buffer.  All other sections are
+descendants of this section.  The value of this variable is set by
+@code{magit-insert-section} and you should never modify it.
+@end defvar
+
+For diff related sections a few additional tools exist.
+
+@defun magit-diff-type &optional section
+Return the diff type of SECTION@.
+
+The returned type is one of the symbols @code{staged}, @code{unstaged}, @code{committed},
+or @code{undefined}.  This type serves a similar purpose as the general
+type common to all sections (which is stored in the @code{type} slot of the
+corresponding @code{magit-section} struct) but takes additional information
+into account.  When the SECTION isn't related to diffs and the
+buffer containing it also isn't a diff-only buffer, then return nil.
+
+Currently the type can also be one of @code{tracked} and @code{untracked}, but
+these values are not handled explicitly in every place they should
+be.  A possible fix could be to just return nil here.
+
+The section has to be a @code{diff} or @code{hunk} section, or a section whose
+children are of type @code{diff}.  If optional SECTION is nil, return the
+diff type for the current section.  In buffers whose major mode is
+@code{magit-diff-mode} SECTION is ignored and the type is determined using
+other means.  In @code{magit-revision-mode} buffers the type is always
+@code{committed}.
+@end defun
+
+@defun magit-diff-scope &optional section strict
+Return the diff scope of SECTION or the selected section(s).
+
+A diff's "scope" describes what part of a diff is selected, it is a
+symbol, one of @code{region}, @code{hunk}, @code{hunks}, @code{file}, @code{files}, or @code{list}.  Do not
+confuse this with the diff "type", as returned by @code{magit-diff-type}.
+
+If optional SECTION is non-nil, then return the scope of that,
+ignoring the sections selected by the region.  Otherwise return the
+scope of the current section, or if the region is active and selects
+a valid group of diff related sections, the type of these sections,
+i.e., @code{hunks} or @code{files}.  If SECTION (or if the current section that
+is nil) is a @code{hunk} section and the region starts and ends inside
+the body of a that section, then the type is @code{region}.
+
+If optional STRICT is non-nil then return nil if the diff type of
+the section at point is @code{untracked} or the section at point is not
+actually a @code{diff} but a @code{diffstat} section.
+@end defun
+
+@node Refreshing Buffers
+@section Refreshing Buffers
+
+All commands that create a new Magit buffer or change what is being
+displayed in an existing buffer do so by calling @code{magit-mode-setup}.
+Among other things, that function sets the buffer local values of
+@code{default-directory} (to the top-level of the repository),
+@code{magit-refresh-function}, and @code{magit-refresh-args}.
+
+Buffers are refreshed by calling the function that is the local value
+of @code{magit-refresh-function} (a function named @code{magit-*-refresh-buffer},
+where @code{*} may be something like @code{diff}) with the value of
+@code{magit-refresh-args} as arguments.
+
+@defmac magit-mode-setup buffer switch-func mode refresh-func &optional refresh-args
+This function displays and selects BUFFER, turns on MODE, and
+refreshes a first time.
+
+This function displays and optionally selects BUFFER by calling
+@code{magit-mode-display-buffer} with BUFFER, MODE and SWITCH-FUNC as
+arguments.  Then it sets the local value of @code{magit-refresh-function}
+to REFRESH-FUNC and that of @code{magit-refresh-args} to REFRESH-ARGS@.
+Finally it creates the buffer content by calling REFRESH-FUNC with
+REFRESH-ARGS as arguments.
+
+All arguments are evaluated before switching to BUFFER@.
+@end defmac
+
+@defun magit-mode-display-buffer buffer mode &optional switch-function
+This function display BUFFER in some window and select it.  BUFFER
+may be a buffer or a string, the name of a buffer.  The buffer is
+returned.
+
+Unless BUFFER is already displayed in the selected frame, store the
+previous window configuration as a buffer local value, so that it
+can later be restored by @code{magit-mode-bury-buffer}.
+
+The buffer is displayed and selected using SWITCH-FUNCTION@.  If that
+is @code{nil} then @code{pop-to-buffer} is used if the current buffer's major mode
+derives from @code{magit-mode}.  Otherwise @code{switch-to-buffer} is used.
+@end defun
+
+@defvar magit-refresh-function
+The value of this buffer-local variable is the function used to
+refresh the current buffer.  It is called with @code{magit-refresh-args} as
+arguments.
+@end defvar
+
+@defvar magit-refresh-args
+The list of arguments used by @code{magit-refresh-function} to refresh the
+current buffer.  @code{magit-refresh-function} is called with these
+arguments.
+
+The value is usually set using @code{magit-mode-setup}, but in some cases
+it's also useful to provide commands that can change the value.  For
+example, the @code{magit-diff-refresh} transient can be used to change any
+of the arguments used to display the diff, without having to specify
+again which differences should be shown, but @code{magit-diff-more-context},
+@code{magit-diff-less-context} and @code{magit-diff-default-context} change just
+the @code{-U<N>} argument.  In both case this is done by changing the value
+of this variable and then calling this @code{magit-refresh-function}.
+@end defvar
+
+@node Conventions
+@section Conventions
+
+Also see @ref{Completion and Confirmation}.
+
+@menu
+* Theming Faces::
+@end menu
+
+@node Theming Faces
+@subsection Theming Faces
+
+The default theme uses blue for local branches, green for remote
+branches, and goldenrod (brownish yellow) for tags.  When creating a
+new theme, you should probably follow that example.  If your theme
+already uses other colors, then stick to that.
+
+In older releases these reference faces used to have a background
+color and a box around them.  The basic default faces no longer do so,
+to make Magit buffers much less noisy, and you should follow that
+example at least with regards to boxes.  (Boxes were used in the past
+to work around a conflict between the highlighting overlay and text
+property backgrounds.  That's no longer necessary because highlighting no
+longer causes other background colors to disappear.)  Alternatively
+you can keep the background color and/or box, but then have to take
+special care to adjust @code{magit-branch-current} accordingly.  By default
+it looks mostly like @code{magit-branch-local}, but with a box (by default
+the former is the only face that uses a box, exactly so that it sticks
+out).  If the former also uses a box, then you have to make sure that
+it differs in some other way from the latter.
+
+The most difficult faces to theme are those related to diffs,
+headings, highlighting, and the region.  There are faces that fall
+into all four groups - expect to spend some time getting this right.
+
+The @code{region} face in the default theme, in both the light and dark
+variants, as well as in many other themes, distributed with Emacs or
+by third-parties, is very ugly.  It is common to use a background
+color that really sticks out, which is ugly but if that were the only
+problem then it would be acceptable.  Unfortunately many themes also
+set the foreground color, which ensures that all text within the
+region is readable.  Without doing that there might be cases where
+some foreground color is too close to the region background color to
+still be readable.  But it also means that text within the region
+loses all syntax highlighting.
+
+I consider the work that went into getting the @code{region} face right to be
+a good indicator for the general quality of a theme.  My
+recommendation for the @code{region} face is this: use a background color
+slightly different from the background color of the @code{default} face, and
+do not set the foreground color at all.  So for a light theme you
+might use a light (possibly tinted) gray as the background color of
+@code{default} and a somewhat darker gray for the background of @code{region}.
+That should usually be enough to not collide with the foreground color
+of any other face.  But if some other faces also set a light gray as
+background color, then you should also make sure it doesn't collide
+with those (in some cases it might be acceptable though).
+
+Magit only uses the @code{region} face when the region is "invalid" by its
+own definition.  In a Magit buffer the region is used to either select
+multiple sibling sections, so that commands which support it act on
+all of these sections instead of just the current section, or to
+select lines within a single hunk section.  In all other cases, the
+section is considered invalid and Magit won't act on it.  But such
+invalid sections happen, either because the user has not moved point
+enough yet to make it valid or because she wants to use a non-magit
+command to act on the region, e.g., @code{kill-region}.
+
+So using the regular @code{region} face for invalid sections is a feature.  It
+tells the user that Magit won't be able to act on it.  It's acceptable
+if that face looks a bit odd and even (but less so) if it collides
+with the background colors of section headings and other things that
+have a background color.
+
+Magit highlights the current section.  If a section has subsections,
+then all of them are highlighted.  This is done using faces that have
+"highlight" in their names.  For most sections, @code{magit-section-highlight}
+is used for both the body and the heading.  Like the @code{region} face, it
+should only set the background color to something similar to that of
+@code{default}.  The highlight background color must be different from both
+the @code{region} background color and the @code{default} background color.
+
+For diff related sections Magit uses various faces to
+highlight different parts of the selected section(s).  Note that hunk
+headings, unlike all other section headings, by default have a
+background color, because it is useful to have very visible separators
+between hunks.  That face @code{magit-diff-hunk-heading}, should be different
+from both @code{magit-diff-hunk-heading-highlight} and
+@code{magit-section-highlight}, as well as from @code{magit-diff-context} and
+@code{magit-diff-context-highlight}.  By default we do that by changing the
+foreground color.  Changing the background color would lead to
+complications, and there are already enough we cannot get around.
+(Also note that it is generally a good idea for section headings to
+always be bold, but only for sections that have subsections).
+
+When there is a valid region selecting diff-related sibling sections,
+i.e., multiple files or hunks, then the bodies of all these sections
+use the respective highlight faces, but additionally the headings
+instead use one of the faces @code{magit-diff-file-heading-selection} or
+@code{magit-diff-hunk-heading-selection}.  These faces have to be different
+from the regular highlight variants to provide explicit visual
+indication that the region is active.
+
+When theming diff related faces, start by setting the option
+@code{magit-diff-refine-hunk} to @code{all}.  You might personally prefer to only
+refine the current hunk or not use hunk refinement at all, but some of
+the users of your theme want all hunks to be refined, so you have to
+cater to that.
+
+(Also turn on @code{magit-diff-highlight-indentation},
+@code{magit-diff-highlight-trailing}, and @code{magit-diff-paint-whitespace}; and
+insert some whitespace errors into the code you use for testing.)
+
+For added lines you have to adjust three faces:
+@code{magit-diff-added}, @code{magit-diff-added-highlight}, and
+@code{diff-refined-added}.  Make sure that the latter works well with both
+of the former, as well as @code{smerge-other} and @code{diff-added}.  Then do the
+same for the removed lines, context lines, lines added by us, and
+lines added by them.  Also make sure the respective added, removed,
+and context faces use approximately the same saturation for both the
+highlighted and unhighlighted variants.  Also make sure the file and
+diff headings work nicely with context lines (e.g., make them look
+different).  Line faces should set both the foreground and the
+background color.  For example, for added lines use two different
+greens.
+
+It's best if the foreground color of both the highlighted and the
+unhighlighted variants are the same, so you will need to have to find
+a color that works well on the highlight and unhighlighted background,
+the refine background, and the highlight context background.  When
+there is an hunk internal region, then the added- and removed-lines
+background color is used only within that region.  Outside the region
+the highlighted context background color is used.  This makes it
+easier to see what is being staged.  With an hunk internal region the
+hunk heading is shown using @code{magit-diff-hunk-heading-selection}, and so
+are the thin lines that are added around the lines that fall within
+the region.  The background color of that has to be distinct enough
+from the various other involved background colors.
+
+Nobody said this would be easy.  If your theme restricts itself to a
+certain set of colors, then you should make an exception here.
+Otherwise it would be impossible to make the diffs look good in each
+and every variation.  Actually you might want to just stick to the
+default definitions for these faces.  You have been warned.  Also
+please note that if you do not get this right, this will in some cases
+look to users like bugs in Magit - so please do it right or not at
+all.
+
+@node FAQ
+@appendix FAQ
+
+The next two nodes lists frequently asked questions.  For a list of
+frequently @strong{and recently} asked questions, i.e., questions that haven't
+made it into the manual yet, see
+@uref{https://github.com/magit/magit/wiki/FAQ}.
+
+Please also see @ref{Debugging Tools}.
+
+@menu
+* FAQ - How to @dots{}?::
+* FAQ - Issues and Errors::
+@end menu
+
+@node FAQ - How to @dots{}?
+@appendixsec FAQ - How to @dots{}?
+
+@menu
+* How to pronounce Magit?::
+* How to show git's output?::
+* How to install the gitman info manual?::
+* How to show diffs for gpg-encrypted files?::
+* How does branching and pushing work?::
+* Should I disable VC@?::
+@end menu
+
+@node How to pronounce Magit?
+@appendixsubsec How to pronounce Magit?
+
+Either @code{mu[m's] git} or @code{magi@{c => t@}} is fine.
+
+The slogan is "It's Magit! The magical Git client", so it makes sense
+to pronounce Magit like magic, while taking into account that C and T
+do not sound the same.
+
+The German "Magie" is not pronounced the same as the English "magic",
+so if you speak German then you can use the above rationale to justify
+using the former pronunciation; @code{Mag@{ie => it@}}.
+
+You can also choose to use the former pronunciation just because you
+like it better.
+
+Also see @uref{https://magit.vc/assets/videos/magic.mp4}.
+Also see @uref{https://emacs.stackexchange.com/questions/13696}.
+
+@node How to show git's output?
+@appendixsubsec How to show git's output?
+
+To show the output of recently run git commands, press @code{$} (or, if that
+isn't available, @code{M-x magit-process-buffer}).  This will show a buffer
+containing a section per git invocation; as always press @code{TAB} to expand
+or collapse them.
+
+By default, git's output is only inserted into the process buffer if it
+is run for side-effects.  When the output is consumed in some way,
+also inserting it into the process buffer would be too expensive.  For
+debugging purposes, it's possible to do so anyway by setting
+@code{magit-git-debug} to @code{t}.
+
+@node How to install the gitman info manual?
+@appendixsubsec How to install the gitman info manual?
+
+Git's manpages can be exported as an info manual called @code{gitman}.
+Magit's own info manual links to nodes in that manual instead of the
+actual manpages because Info doesn't support linking to manpages.
+
+Unfortunately some distributions do not install the @code{gitman} manual by
+default and you will have to install a separate documentation package
+to get it.
+
+Magit patches Info adding the ability to visit links to the @code{gitman}
+Info manual by instead viewing the respective manpage.  If you prefer
+that approach, then set the value of @code{magit-view-git-manual-method} to
+one of the supported packages @code{man} or @code{woman}, e.g.:
+
+@lisp
+(setq magit-view-git-manual-method 'man)
+@end lisp
+
+@node How to show diffs for gpg-encrypted files?
+@appendixsubsec How to show diffs for gpg-encrypted files?
+
+Git supports showing diffs for encrypted files, but has to be told to
+do so.  Since Magit just uses Git to get the diffs, configuring Git
+also affects the diffs displayed inside Magit.
+
+@example
+git config --global diff.gpg.textconv "gpg --no-tty --decrypt"
+echo "*.gpg filter=gpg diff=gpg" > .gitattributes
+@end example
+
+@node How does branching and pushing work?
+@appendixsubsec How does branching and pushing work?
+
+Please see @ref{Branching} and @uref{https://emacsair.me/2016/01/17/magit-2.4}
+
+@node Should I disable VC@?
+@appendixsubsec Should I disable VC@?
+
+If you don't use VC (the built-in version control interface) then
+you might be tempted to disable it, not least because we used to
+recommend that you do that.
+
+We no longer recommend that you disable VC@.  Doing so would break
+useful third-party packages (such as @code{diff-hl}), which depend on VC
+being enabled.
+
+If you choose to disable VC anyway, then you can do so by changing
+the value of @code{vc-handled-backends}.
+
+@node FAQ - Issues and Errors
+@appendixsec FAQ - Issues and Errors
+
+@menu
+* Magit is slow::
+* I changed several thousand files at once and now Magit is unusable::
+* I am having problems committing::
+* I am using MS Windows and cannot push with Magit::
+* I am using macOS and SOMETHING works in shell, but not in Magit: I am using macOS and SOMETHING works in shell but not in Magit. 
+* Expanding a file to show the diff causes it to disappear::
+* Point is wrong in the @code{COMMIT_EDITMSG} buffer::
+* The mode-line information isn't always up-to-date::
+* A branch and tag sharing the same name breaks SOMETHING::
+* My Git hooks work on the command-line but not inside Magit::
+* @code{git-commit-mode} isn't used when committing from the command-line::
+* Point ends up inside invisible text when jumping to a file-visiting buffer::
+* I am no longer able to save popup defaults::
+@end menu
+
+@node Magit is slow
+@appendixsubsec Magit is slow
+
+See @ref{Performance} and @ref{I changed several thousand files at once and now Magit is unusable}.
+
+@node I changed several thousand files at once and now Magit is unusable
+@appendixsubsec I changed several thousand files at once and now Magit is unusable
+
+Magit is currently not expected to work well under such conditions.
+It sure would be nice if it did.  Reaching satisfactory performance
+under such conditions will require some heavy refactoring.  This is no
+small task but I hope to eventually find the time to make it happen.
+
+But for now we recommend you use the command line to complete this one
+commit.  Also see @ref{Performance}.
+
+@node I am having problems committing
+@appendixsubsec I am having problems committing
+
+That likely means that Magit is having problems finding an appropriate
+emacsclient executable.  See @ref{Configuring With-Editor,,,with-editor,}
+and @ref{Debugging,,,with-editor,}.
+
+@node I am using MS Windows and cannot push with Magit
+@appendixsubsec I am using MS Windows and cannot push with Magit
+
+It's almost certain that Magit is only incidental to this issue.  It
+is much more likely that this is a configuration issue, even if you
+can push on the command line.
+
+Detailed setup instructions can be found at
+@uref{https://github.com/magit/magit/wiki/Pushing-with-Magit-from-Windows}.
+
+@node I am using macOS and SOMETHING works in shell but not in Magit
+@appendixsubsec I am using macOS and SOMETHING works in shell, but not in Magit
+
+This usually occurs because Emacs doesn't have the same environment
+variables as your shell.  Try installing and configuring
+@uref{https://github.com/purcell/exec-path-from-shell}.  By default it
+synchronizes @code{$PATH}, which helps Magit find the same @code{git} as the one you
+are using on the shell.
+
+If SOMETHING is "passphrase caching with gpg-agent for commit and/or
+tag signing", then you'll also need to synchronize @code{$GPG_AGENT_INFO}.
+
+@node Expanding a file to show the diff causes it to disappear
+@appendixsubsec Expanding a file to show the diff causes it to disappear
+
+This is probably caused by a customization of a @code{diff.*} Git variable.
+You probably set that variable for a reason, and should therefore only
+undo that setting in Magit by customizing @code{magit-git-global-arguments}.
+
+@node Point is wrong in the @code{COMMIT_EDITMSG} buffer
+@appendixsubsec Point is wrong in the @code{COMMIT_EDITMSG} buffer
+
+Neither Magit nor @code{git-commit.el} fiddle with point in the buffer used
+to write commit messages, so something else must be doing it.
+
+You have probably globally enabled a mode which restores point in
+file-visiting buffers.  It might be a bit surprising, but when you
+write a commit message, then you are actually editing a file.
+
+So you have to figure out which package is doing it.  @code{saveplace},
+@code{pointback}, and @code{session} are likely candidates.  These snippets might
+help:
+
+@lisp
+(setq session-name-disable-regexp "\\(?:\\`'\\.git/[A-Z_]+\\'\\)")
+
+(with-eval-after-load 'pointback
+  (lambda ()
+    (when (or git-commit-mode git-rebase-mode)
+      (pointback-mode -1))))
+@end lisp
+
+@node The mode-line information isn't always up-to-date
+@appendixsubsec The mode-line information isn't always up-to-date
+
+Magit is not responsible for the version control information that is
+being displayed in the mode-line and looks something like @code{Git-master}.
+The built-in "Version Control" package, also known as "VC", updates
+that information, and can be told to do so more often:
+
+@lisp
+(setq auto-revert-check-vc-info t)
+@end lisp
+
+But doing so isn't good for performance.  For more (overly optimistic)
+information see @ref{VC Mode Line,,,emacs,}.
+
+If you don't really care about seeing this information in the
+mode-line, but just don't want to see @emph{incorrect} information,
+then consider simply not displaying it in the mode-line:
+
+@lisp
+(setq-default mode-line-format
+              (delete '(vc-mode vc-mode) mode-line-format))
+@end lisp
+
+@node A branch and tag sharing the same name breaks SOMETHING
+@appendixsubsec A branch and tag sharing the same name breaks SOMETHING
+
+Or more generally, ambiguous refnames break SOMETHING@.
+
+Magit assumes that refs are named non-ambiguously across the
+"refs/heads/", "refs/tags/", and "refs/remotes/" namespaces (i.e., all
+the names remain unique when those prefixes are stripped).  We
+consider ambiguous refnames unsupported and recommend that you use a
+non-ambiguous naming scheme.  However, if you do work with a
+repository that has ambiguous refnames, please report any issues you
+encounter, so that we can investigate whether there is a simple fix.
+
+@node My Git hooks work on the command-line but not inside Magit
+@appendixsubsec My Git hooks work on the command-line but not inside Magit
+
+When Magit calls @code{git} it adds a few global arguments including
+@code{--literal-pathspecs} and the @code{git} process started by Magit then passes
+that setting on to other @code{git} process it starts itself.  It does so by
+setting the environment variable @code{GIT_LITERAL_PATHSPECS}, not by calling
+subprocesses with the @code{--literal-pathspecs} argument.  You can therefore
+override this setting in hook scripts using @code{unset
+GIT_LITERAL_PATHSPECS}.
+
+@node @code{git-commit-mode} isn't used when committing from the command-line
+@appendixsubsec @code{git-commit-mode} isn't used when committing from the command-line
+
+The reason for this is that @code{git-commit.el} has not been loaded yet
+and/or that the server has not been started yet.  These things have
+always already been taken care of when you commit from Magit because
+in order to do so, Magit has to be loaded and doing that involves
+loading @code{git-commit} and starting the server.
+
+If you want to commit from the command-line, then you have to take
+care of these things yourself. Your @code{init.el} file should contain:
+
+@lisp
+(require 'git-commit)
+(server-mode)
+@end lisp
+
+Instead of `(require 'git-commit)` you may also use:
+
+@lisp
+(load "/path/to/magit-autoloads.el")
+@end lisp
+
+You might want to do that because loading @code{git-commit} causes large
+parts of Magit to be loaded.
+
+There are also some variations of @code{(server-mode)} that you might want to
+try. Personally I use:
+
+@lisp
+(use-package server
+  :config (or (server-running-p) (server-mode)))
+@end lisp
+
+Now you can use:
+
+@example
+$ emacs&
+$ EDITOR=emacsclient git commit
+@end example
+
+However you cannot use:
+
+@example
+$ killall emacs
+$ EDITOR="emacsclient --alternate-editor emacs" git commit
+@end example
+
+This will actually end up using @code{emacs}, not @code{emacsclient}.  If you do
+this, then you can still edit the commit message but @code{git-commit-mode}
+won't be used and you have to exit @code{emacs} to finish the process.
+
+Tautology ahead.  If you want to be able to use @code{emacsclient} to connect
+to a running @code{emacs} instance, even though no @code{emacs} instance is running,
+then you cannot use @code{emacsclient} directly.
+
+Instead you have to create a script that does something like this:
+
+Try to use @code{emacsclient} (without using @code{--alternate-editor}).  If that
+succeeds, do nothing else.  Otherwise start @code{emacs &} (and @code{init.el} must
+call @code{server-start}) and try to use @code{emacsclient} again.
+
+@node Point ends up inside invisible text when jumping to a file-visiting buffer
+@appendixsubsec Point ends up inside invisible text when jumping to a file-visiting buffer
+
+This can happen when you type @code{RET} on a hunk to visit the respective
+file at the respective position.  One solution to this problem is to
+use @code{global-reveal-mode}.  It makes sure that text around point is
+always visible.  If that is too drastic for your taste, then you may
+instead use @code{magit-diff-visit-file-hook} to reveal the text, possibly
+using @code{reveal-post-command} or for Org buffers @code{org-reveal}.
+
+@node I am no longer able to save popup defaults
+@appendixsubsec I am no longer able to save popup defaults
+
+Magit used to use Magit-Popup to implement the transient popup menus.
+Now it used Transient instead, which is Magit-Popup's successor.
+
+In the older Magit-Popup menus, it was possible to save user settings
+(e.g., setting the gpg signing key for commits) by using @code{C-c C-c} in
+the popup buffer.  This would dismiss the popup, but save the settings
+as the defaults for future popups.
+
+When switching to Transient menus, this functionality is now available
+via @code{C-x C-s} instead; the @code{C-x} prefix has other options as well when
+using Transient, which will be displayed when it is typed.  See
+@uref{https://magit.vc/manual/transient/Saving-Values.html#Saving-Values} for
+more details.
+
+@node Debugging Tools
+@chapter Debugging Tools
+
+Magit and its dependencies provide a few debugging tools, and we
+appreciate it very much if you use those tools before reporting an
+issue.  Please include all relevant output when reporting an
+issue.
+
+@table @asis
+@item @kbd{M-x magit-version}
+@findex magit-version
+This command shows the currently used versions of Magit, Git, and
+Emacs in the echo area.  Non-interactively this just returns the
+Magit version.
+
+@item @kbd{M-x magit-emacs-Q-command}
+@findex magit-emacs-Q-command
+This command shows a debugging shell command in the echo area and
+adds it to the kill ring.  Paste that command into a shell and run
+it.
+
+This shell command starts @code{emacs} with only @code{magit} and its
+dependencies loaded.  Neither your configuration nor other installed
+packages are loaded.  This makes it easier to determine whether some
+issue lays with Magit or something else.
+
+If you run Magit from its Git repository, then you should be able to
+use @code{make emacs-Q} instead of the output of this command.
+
+@item @kbd{M-x magit-toggle-git-debug}
+@findex magit-toggle-git-debug
+This command toggles whether additional git errors are reported.
+
+Magit basically calls git for one of these two reasons: for
+side-effects or to do something with its standard output.
+
+When git is run for side-effects then its output, including error
+messages, go into the process buffer which is shown when using @code{$}.
+
+When git's output is consumed in some way, then it would be too
+expensive to also insert it into this buffer, but when this
+option is non-nil and git returns with a non-zero exit status,
+then at least its standard error is inserted into this buffer.
+
+This is only intended for debugging purposes.  Do not enable this
+permanently, that would negatively affect performance.  Also note
+that just because git exits with a non-zero exit status and prints
+an error message that usually doesn't mean that it is an error as
+far as Magit is concerned, which is another reason we usually hide
+these error messages.  Whether some error message is relevant in
+the context of some unexpected behavior has to be judged on a case
+by case basis.
+
+@item @kbd{M-x magit-toggle-verbose-refresh}
+@findex magit-toggle-verbose-refresh
+This command toggles whether Magit refreshes buffers verbosely.
+Enabling this helps figuring out which sections are bottlenecks.
+The additional output can be found in the @code{*Messages*} buffer.
+
+@item @kbd{M-x magit-debug-git-executable}
+@findex magit-debug-git-executable
+This command displays a buffer containing information about the
+available and used @code{git} executable(s), and can be useful when
+investigating @code{exec-path} issues.
+
+Also see @ref{Git Executable}.
+
+@item @kbd{M-x with-editor-debug}
+@findex with-editor-debug
+This command displays a buffer containing information about the
+available and used @code{emacsclient} executable(s), and can be useful
+when investigating why Magit (or rather @code{with-editor}) cannot find
+an appropriate @code{emacsclient} executable.
+
+Also see @ref{Debugging,,,with-editor,}.
+@end table
+
+@noindent
+Please also see @ref{FAQ}.
+
+@node Keystroke Index
+@appendix Keystroke Index
+
+@printindex ky
+
+@node Function and Command Index
+@appendix Function and Command Index
+
+@printindex fn
+
+@node Variable Index
+@appendix Variable Index
+
+@printindex vr
+
+@bye