branch: elpa/magit
commit 8b1f599de4c54957d7dfbd2bc0fed2d9e04760a0
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Provide set of recommended global key bindings
Also update related parts of the manual that were very outdated.
---
docs/magit.org | 323 +++++++++++++++++++++++++++--------------
docs/magit.texi | 441 +++++++++++++++++++++++++++++++++++++++++---------------
lisp/magit.el | 93 +++++++-----
3 files changed, 587 insertions(+), 270 deletions(-)
diff --git a/docs/magit.org b/docs/magit.org
index d58d3a8fae..2ac450c8c7 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -348,17 +348,25 @@ 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 ~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 ~d~. But 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. The global binding is ~C-x M-g~.
+stands for "diff", you would usually do so by just typing ~d~.
-In file visiting buffers ~C-c M-g~ brings up a similar menu featuring
-commands that act on just the visited file, see [[*Commands for Buffers
-Visiting Files]].
+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 ~C-x M-g~.
-Magit also provides a context menu and other mouse commands, see
-[[*Mouse Support]].
+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 ~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 ~C-c g~ and ~C-c f~ instead, but
+cannot use those key sequences by default because they are strickly
+reserved for bindings added by the user. See [[*Global Bindings]], if you
+want to explicitly opt-in to the recommended key bindings.
+
+Magit also provides context menus and other mouse commands, see [[*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.
@@ -1242,7 +1250,8 @@ used the package ~magit-popup~ and even earlier versions
library
Transient is documented in [[info:transient]].
-- Key: C-c C-c (magit-dispatch) ::
+- Key: C-x M-g (magit-dispatch) ::
+- Key: C-c g (magit-dispatch) ::
This transient prefix command binds most of Magit's other prefix
commands as suffix commands and displays them in a temporary buffer
@@ -1250,12 +1259,11 @@ Transient is documented in [[info:transient]].
suffixes of that command to be bound and displayed instead of those
of ~magit-dispatch~.
-This command is also, or especially, useful outside Magit buffers, so
-you should setup a global binding:
-
-#+begin_src emacs-lisp
- (global-set-key (kbd "C-x M-g") 'magit-dispatch)
-#+end_src
+ This command is also, or especially, useful outside Magit buffers,
+ so Magit by default binds it to ~C-c M-g~ in the global keymap.
+ ~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 [[*Global
+ Bindings]] to learn more default and recommended key bindings.
** Transient Arguments and Buffer Variables
@@ -4040,15 +4048,31 @@ argument.
Also see [[man:git-blame]]
-To start blaming invoke the ~magit-file-dispatch~ transient prefix
-command by pressing ~C-c M-g~.
-
-The blaming suffix commands can be invoked from the dispatch
-transient. However if you want to set an infix argument, then you
-have to enter the blaming sub-transient first.
-
-The key bindings shown below assume that you enter the dispatch
-transient using the default binding.
+To start blaming, invoke the ~magit-file-dispatch~ transient prefix
+command. When using the default key bindings, that can be done
+by pressing ~C-c M-g~. When using the recommended bindings, this
+command is instead bound to ~C-c f~. Also see [[*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.
+
+- Key: C-c f B (magit-blame) ::
+- Key: C-c f b (magit-blame-addition) ::
+- Key: C-c f B b ::
+- Key: C-c f r (magit-blame-removal) ::
+- Key: C-c f B r ::
+- Key: C-c f f (magit-blame-reverse) ::
+- Key: C-c f B f ::
+- Key: C-c f e (magit-blame-echo) ::
+- Key: C-c f B e ::
+- Key: C-c f q (magit-blame-quit) ::
+- Key: C-c f B q ::
+
+ 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 [[*Global Bindings]].
- Key: C-c M-g B (magit-blame) ::
@@ -4107,6 +4131,12 @@ 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.
+- Key: C-c M-g q (magit-blame-quit) ::
+- Key: C-c M-g B q ::
+
+ This command turns off Magit-Blame mode. If the buffer was created
+ during a recursive blame, then it also kills the buffer.
+
- Key: RET (magit-show-commit) ::
This command shows the commit that last touched the line at point.
@@ -7517,45 +7547,101 @@ before making changes that could cause the loss of
earlier changes.
** Commands for Buffers Visiting Files
-Magit defines a few global key bindings unless the user sets
-~magit-define-global-key-bindings~ to ~nil~. This includes binding ~C-c
-M-g~ to ~magit-file-dispatch~. ~C-c g~ would be a much better binding
-but the ~C-c <letter>~ namespace is reserved for users, meaning that
-packages are not allowed to use it. If you want to use ~C-c g~, then
-you have to add that binding yourself. Also see [[*Default Bindings]]
-and [[info:elisp#Key Binding Conventions]].
+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 stricktly reserved for bindings added by the user.
+Also see [[*Global Bindings]] and [[info:elisp#Key Binding Conventions]].
+
+To use the recommended bindings, add this to your init file and
+restart Emacs.
+
+#+begin_src emacs-lisp
+ (setq magit-define-global-key-bindings 'recommended)
+#+end_src
-If you want a better binding, you have to add it yourself:
+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.
#+begin_src emacs-lisp
- (global-set-key (kbd "C-c g") 'magit-file-dispatch)
+ (setq magit-define-global-key-bindings nil)
#+end_src
-The key bindings shown below assume that you have not improved the
-binding for ~magit-file-dispatch~.
+- Key: C-c f (magit-file-dispatch) ::
+- Key: C-c f s (magit-stage-file) ::
+- Key: C-c f s (magit-stage-buffer-file) ::
+- Key: C-c f u (magit-unstage-file) ::
+- Key: C-c f u (magit-unstage-buffer-file) ::
+- Key: C-c f , x (magit-file-untrack) ::
+- Key: C-c f , r (magit-file-rename) ::
+- Key: C-c f , k (magit-file-delete) ::
+- Key: C-c f , c (magit-file-checkout) ::
+- Key: C-c f D (magit-diff) ::
+- Key: C-c f d (magit-diff-buffer-file) ::
+- Key: C-c f L (magit-log) ::
+- Key: C-c f l (magit-log-buffer-file) ::
+- Key: C-c f t (magit-log-trace-definition) ::
+- Key: C-c f M (magit-log-merged) ::
+- Key: C-c f B (magit-blame) ::
+- Key: C-c f b (magit-blame-additions) ::
+- Key: C-c f r (magit-blame-removal) ::
+- Key: C-c f f (magit-blame-reverse) ::
+- Key: C-c f m (magit-blame-echo) ::
+- Key: C-c f q (magit-blame-quit) ::
+- Key: C-c f p (magit-blob-previous) ::
+- Key: C-c f n (magit-blob-next) ::
+- Key: C-c f v (magit-find-file) ::
+- Key: C-c f V (magit-blob-visit-file) ::
+- Key: C-c f g (magit-status-here) ::
+- Key: C-c f G (magit-display-repository-buffer) ::
+- Key: C-c f c (magit-commit) ::
+- Key: C-c f e (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.
- Key: C-c M-g (magit-file-dispatch) ::
This transient prefix command binds the following suffix commands
and displays them in a temporary buffer until a suffix is invoked.
- When invoked in a buffer that does not visit a file, then it falls
- back to regular ~magit-dispatch~.
-
- Key: C-c M-g s (magit-stage-file) ::
+- Key: C-c M-g s (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.
- Key: C-c M-g u (magit-unstage-file) ::
+- Key: C-c M-g u (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.
-- Key: C-c M-g c (magit-commit) ::
+- Key: C-c M-g , x (magit-file-untrack) ::
- 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 [[*Initiating a
- Commit]].
+ This command untracks a file read from the user, defaulting to the
+ visited file.
+
+- Key: C-c M-g , r (magit-file-rename) ::
+
+ This command renames a file read from the user, defaulting to the
+ visited file.
+
+- Key: C-c M-g , k (magit-file-delete) ::
+
+ This command deletes a file read from the user, defaulting to the
+ visited file.
+
+- Key: C-c M-g , c (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.
- Key: C-c M-g D (magit-diff) ::
@@ -7596,14 +7682,20 @@ binding for ~magit-file-dispatch~.
or when ~--follow~ is an active log argument. When the region is
active, the log is restricted to the selected line range.
+- User Option: magit-log-buffer-file-locked ::
+
+ This option controls whether ~magit-log-buffer-file~ uses a dedicated
+ buffer. See [[*Modes and Buffers]].
+
- Key: C-c M-g t (magit-log-trace-definition) ::
This command shows the log for the definition at point.
-- User Option: magit-log-buffer-file-locked ::
+- Key: C-c M-g M (magit-log-merged) ::
- This option controls whether ~magit-log-buffer-file~ uses a dedicated
- buffer. See [[*Modes and Buffers]].
+ 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.
- Key: C-c M-g B (magit-blame) ::
@@ -7614,48 +7706,59 @@ binding for ~magit-file-dispatch~.
For more information about this and the following commands also see
[[*Blaming]].
-In addition to the ~magit-blame~ sub-transient, the dispatch transient
-also binds several blaming suffix commands directly. See [[*Blaming]] for
-information about those commands and bindings.
+ In addition to the ~magit-blame~ sub-transient, the dispatch transient
+ also binds several blaming suffix commands directly. See [[*Blaming]]
+ for information about those commands and bindings.
-- Key: C-c M-g e (magit-edit-line-commit) ::
+- Key: C-c M-g p (magit-blob-previous) ::
- This command makes the commit editable that added the current line.
+ This command visits the previous blob which modified the current
+ file.
- With a prefix argument it makes the commit editable that removes the
- line, if any. The commit is determined using ~git blame~ and made
- editable using ~git rebase --interactive~ if it is reachable from
- ~HEAD~, or by checking out the commit (or a branch that points at it)
- otherwise.
+- Key: C-c M-g n (magit-blob-next) ::
-- Key: C-c M-g p (magit-blob-previous) ::
+ This command visits the next blob which modified the current file.
- Visit the previous blob which modified the current file.
+- Key: C-c M-g v (magit-find-file) ::
-There are a few additional commands that operate on a single file but
-are not enabled in the file transient command by default:
+ This command reads a revision and file and visits the respective
+ blob.
-- Command: magit-file-rename ::
+- Key: C-c M-g V (magit-blob-visit-file) ::
- This command renames a file read from the user.
+ 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.
-- Command: magit-file-delete ::
+- Key: C-c M-g g (magit-status-here) ::
- This command deletes a file read from the user.
+ This command displays the status of the current repository in a
+ buffer, like ~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).
-- Command: magit-file-untrack ::
+- Key: C-c M-g G (magit-display-repository-buffer) ::
- This command untracks a file read from the user.
+ This command reads and displays a Magit buffer belonging to the
+ current repository, without refreshing it.
-- Command: magit-file-checkout ::
+- Key: C-c M-g c (magit-commit) ::
- 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.
+ 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 [[*Initiating a
+ Commit]].
-To enable them invoke the transient (~C-c M-g~), enter "edit mode" (~C-x
-l~), set the "transient level" (~C-x l~ again), enter ~5~, and leave edit
-mode (~C-g~). Also see [[info:transient#Enabling and Disabling Suffixes]].
+- Key: C-c M-g e (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 ~git blame~ and made
+ editable using ~git rebase --interactive~ if it is reachable from
+ ~HEAD~, or by checking out the commit (or a branch that points at it)
+ otherwise.
** Minor Mode for Buffers Visiting Blobs
@@ -8027,55 +8130,55 @@ you notice a notable difference try using the latter as
[fn:mac1]
https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html
-*** Default Bindings
+*** Global Bindings
- User Option: magit-define-global-key-bindings ::
- This option controls whether some Magit commands are automatically
- bound in the global keymap even before Magit is used for the first
- time in the current session.
+ 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.
- If this variable is non-nil, which it is by default, then the
- following bindings may be added to the global keymap.
+ - If the value is ~nil~, no bindings are added.
- | ~C-x g~ | ~magit-status~ |
- | ~C-x M-g~ | ~magit-dispatch~ |
- | ~C-c M-g~ | ~magit-file-dispatch~ |
+ - If ~default~, maybe add:
- These bindings may be added when ~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.
+ | ~C-x g~ | ~magit-status~ |
+ | ~C-x M-g~ | ~magit-dispatch~ |
+ | ~C-c M-g~ | ~magit-file-dispatch~ |
- Adding the above bindings is delayed until ~after-init-hook~
- is called to allow users to set the variable anywhere in their
- init file (without having to make sure to do so before ~magit~
- is loaded or autoloaded) and to increase the likelihood that
- all the potentially conflicting user bindings have already
- been added.
+ - If ~recommended~, maybe add:
+
+ | ~C-x g~ | ~magit-status~ |
+ | ~C-c g~ | ~magit-dispatch~ |
+ | ~C-c f~ | ~magit-file-dispatch~ |
+
+ These bindings are strongly recommended, but we cannot use
+ them by default, because the ~C-c <LETTER>~ namespace is
+ strictly reserved for bindings added by the user (see
+ [[info:elisp#Key Binding Conventions]]).
+
+ The bindings in the chosen set may be added when
+ ~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 ~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 ~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 ~setq~ or the Custom interface.
Do not use the function ~customize-set-variable~ because doing
- that would cause Magit to be loaded immediately when that form
+ that would cause Magit to be loaded immediately, when that form
is evaluated (this differs from ~custom-set-variables~, which
doesn't load the libraries that define the customized variables).
- Setting this variable to nil has no effect if that is done after
- the key bindings have already been added.
-
- We recommend that you bind ~C-c g~ instead of ~C-c M-g~ to
- ~magit-file-dispatch~. The former is a much better binding
- but the ~C-c <letter>~ namespace is strictly reserved for
- users; preventing Magit from using it by default.
-
- #+BEGIN_SRC emacs-lisp
- (global-set-key (kbd "C-c g") 'magit-file-dispatch)
- #+END_SRC
-
- Also see [[*Commands for Buffers Visiting Files]] and [[info:elisp#Key
- Binding Conventions]].
+ Setting this variable has no effect if ~after-init-hook~ has
+ already been run.
* Plumbing
diff --git a/docs/magit.texi b/docs/magit.texi
index f54b1a7af1..987dd244e2 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -276,7 +276,7 @@ Essential Settings
* Safety::
* Performance::
-* Default Bindings::
+* Global Bindings::
Plumbing
@@ -681,16 +681,24 @@ 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}. But 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. The global binding is @code{C-x M-g}.
+stands for "diff", you would usually do so by just typing @code{d}.
-In file visiting buffers @code{C-c M-g} brings up a similar menu featuring
-commands that act on just the visited file, see @ref{Commands for Buffers
Visiting Files}.
+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}.
-Magit also provides a context menu and other mouse commands, see
-@ref{Mouse Support}.
+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 strickly
+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.
@@ -1671,22 +1679,22 @@ used the package @code{magit-popup} and even earlier
versions library
Transient is documented in @ref{Top,,,transient,}.
@table @asis
-@item @kbd{C-c C-c} (@code{magit-dispatch})
-@kindex C-c C-c
+@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}.
-@end table
-This command is also, or especially, useful outside Magit buffers, so
-you should setup a global binding:
-
-@lisp
-(global-set-key (kbd "C-x M-g") 'magit-dispatch)
-@end lisp
+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
@@ -5023,17 +5031,49 @@ the <a
href="http://git-scm.com/docs/git-blame";>git-blame(1)</a> manpage.
the git-blame(1) manpage.
@end iftex
-To start blaming invoke the @code{magit-file-dispatch} transient prefix
-command by pressing @code{C-c M-g}.
+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 from the dispatch
-transient. However if you want to set an infix argument, then you
-have to enter the blaming sub-transient first.
-
-The key bindings shown below assume that you enter the dispatch
-transient using the default binding.
+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
@@ -5104,6 +5144,14 @@ 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
@@ -9350,49 +9398,170 @@ Mode-line lighter for
@code{magit-wip-initial-backup-mode}.
@node Commands for Buffers Visiting Files
@section Commands for Buffers Visiting Files
-Magit defines a few global key bindings unless the user sets
-@code{magit-define-global-key-bindings} to @code{nil}. This includes binding
@code{C-c
-M-g} to @code{magit-file-dispatch}. @code{C-c g} would be a much better
binding
-but the @code{C-c <letter>} namespace is reserved for users, meaning that
-packages are not allowed to use it. If you want to use @code{C-c g}, then
-you have to add that binding yourself. Also see @ref{Default Bindings}
-and @ref{Key Binding Conventions,,,elisp,}.
+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 stricktly reserved for bindings added by the user.
+Also see @ref{Global Bindings} and @ref{Key Binding Conventions,,,elisp,}.
-If you want a better binding, you have to add it yourself:
+To use the recommended bindings, add this to your init file and
+restart Emacs.
@lisp
-(global-set-key (kbd "C-c g") 'magit-file-dispatch)
+(setq magit-define-global-key-bindings 'recommended)
@end lisp
-The key bindings shown below assume that you have not improved the
-binding for @code{magit-file-dispatch}.
+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.
-When invoked in a buffer that does not visit a file, then it falls
-back to regular @code{magit-dispatch}.
-
@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.
-
-@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}.
+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
@@ -9438,11 +9607,6 @@ 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.
-
-@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.
@end table
@defopt magit-log-buffer-file-locked
@@ -9451,6 +9615,18 @@ 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
@@ -9460,13 +9636,57 @@ temporary buffer until a suffix is invoked.
For more information about this and the following commands also see
@ref{Blaming}.
-@end table
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.
+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}.
-@table @asis
@item @kbd{C-c M-g e} (@code{magit-edit-line-commit})
@kindex C-c M-g e
@findex magit-edit-line-commit
@@ -9477,38 +9697,8 @@ 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.
-
-@item @kbd{C-c M-g p} (@code{magit-blob-previous})
-@kindex C-c M-g p
-@findex magit-blob-previous
-Visit the previous blob which modified the current file.
@end table
-There are a few additional commands that operate on a single file but
-are not enabled in the file transient command by default:
-
-@deffn Command magit-file-rename
-This command renames a file read from the user.
-@end deffn
-
-@deffn Command magit-file-delete
-This command deletes a file read from the user.
-@end deffn
-
-@deffn Command magit-file-untrack
-This command untracks a file read from the user.
-@end deffn
-
-@deffn Command 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.
-@end deffn
-
-To enable them invoke the transient (@code{C-c M-g}), enter "edit mode"
(@code{C-x
-l}), set the "transient level" (@code{C-x l} again), enter @code{5}, and leave
edit
-mode (@code{C-g}). Also see @ref{Enabling and Disabling
Suffixes,,,transient,}.
-
@node Minor Mode for Buffers Visiting Blobs
@section Minor Mode for Buffers Visiting Blobs
@@ -9675,7 +9865,7 @@ users might want to customize, for safety and/or
performance reasons.
@menu
* Safety::
* Performance::
-* Default Bindings::
+* Global Bindings::
@end menu
@node Safety
@@ -9919,16 +10109,20 @@ 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 Default Bindings
-@subsection Default Bindings
+@node Global Bindings
+@subsection Global Bindings
@defopt magit-define-global-key-bindings
-This option controls whether some Magit commands are automatically
-bound in the global keymap even before Magit is used for the first
-time in the current session.
+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.
-If this variable is non-nil, which it is by default, then the
-following bindings may be added to the global keymap.
+@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}
@@ -9939,39 +10133,46 @@ following bindings may be added to the global keymap.
@tab @code{magit-file-dispatch}
@end multitable
-These bindings 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.
+@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
-Adding the above bindings is delayed until @code{after-init-hook}
-is called 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.
+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
+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 to nil has no effect if that is done after
-the key bindings have already been added.
-
-We recommend that you bind @code{C-c g} instead of @code{C-c M-g} to
-@code{magit-file-dispatch}. The former is a much better binding
-but the @code{C-c <letter>} namespace is strictly reserved for
-users; preventing Magit from using it by default.
-
-@lisp
-(global-set-key (kbd "C-c g") 'magit-file-dispatch)
-@end lisp
-
-Also see @ref{Commands for Buffers Visiting Files} and @ref{Key Binding
Conventions,,,elisp,}.
+Setting this variable has no effect if @code{after-init-hook} has
+already been run.
@end defopt
@node Plumbing
diff --git a/lisp/magit.el b/lisp/magit.el
index bb785ae124..a8842259ba 100644
--- a/lisp/magit.el
+++ b/lisp/magit.el
@@ -249,62 +249,75 @@ and/or `magit-branch-remote-head'."
;;; Global Bindings
;;;###autoload
-(defcustom magit-define-global-key-bindings t
- "Whether to bind some Magit commands in the global keymap.
-
-If this variable is non-nil, then the following bindings may
-be added to the global keymap. The default is t.
-
-key binding
---- -------
-C-x g magit-status
-C-x M-g magit-dispatch
-C-c M-g magit-file-dispatch
-
-These bindings may be added when `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 the above bindings is delayed until `after-init-hook'
-is called to allow users to set the variable anywhere in their
-init file (without having to make sure to do so before `magit'
-is loaded or autoloaded) and to increase the likelihood that
-all the potentially conflicting user bindings have already
-been added.
+(defcustom magit-define-global-key-bindings 'default
+ "Which set of key bindings to add to the global keymap, if any.
+
+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.
+
+If the value is nil, no bindings are added.
+
+If `default', maybe add:
+
+ C-x g `magit-status'
+ C-x M-g `magit-dispatch'
+ C-c M-g `magit-file-dispatch'
+
+If `recommended', maybe add:
+
+ C-x g `magit-status'
+ C-c g `magit-dispatch'
+ C-c f `magit-file-dispatch'
+
+ These bindings are strongly recommended, but we cannot use
+ them by default, because the \"C-c <LETTER>\" namespace is
+ strictly reserved for bindings added by the user.
+
+The bindings in the chosen set may be added when
+`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 `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 `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 `setq' or the Custom interface.
Do not use the function `customize-set-variable' because doing
-that would cause Magit to be loaded immediately when that form
+that would cause Magit to be loaded immediately, when that form
is evaluated (this differs from `custom-set-variables', which
doesn't load the libraries that define the customized variables).
-Setting this variable to nil has no effect if that is done after
-the key bindings have already been added.
-
-We recommend that you bind \"C-c g\" instead of \"C-c M-g\" to
-`magit-file-dispatch'. The former is a much better binding
-but the \"C-c <letter>\" namespace is strictly reserved for
-users; preventing Magit from using it by default.
-
-Also see info node `(magit)Commands for Buffers Visiting Files'."
- :package-version '(magit . "3.0.0")
+Setting this variable has no effect if `after-init-hook' has
+already been run."
+ :package-version '(magit . "4.0.0")
:group 'magit-essentials
- :type 'boolean)
+ :type '(choice (const :tag "Add no binding" nil)
+ (const :tag "Use default bindings" default)
+ (const :tag "Use recommended bindings" recommended)))
;; This is autoloaded and thus is used before `compat' is
;; loaded, so we cannot use `keymap-lookup' and `keymap-set'.
;;;###autoload
(progn
(defun magit-maybe-define-global-key-bindings (&optional force)
+ "See variable `magit-define-global-key-bindings'."
(when magit-define-global-key-bindings
(let ((map (current-global-map)))
(pcase-dolist (`(,key . ,def)
- '(("C-x g" . magit-status)
- ("C-x M-g" . magit-dispatch)
- ("C-c M-g" . magit-file-dispatch)))
+ (cond ((eq magit-define-global-key-bindings
'recommended)
+ '(("C-x g" . magit-status)
+ ("C-c g" . magit-dispatch)
+ ("C-c f" . magit-file-dispatch)))
+ ('(("C-x g" . magit-status)
+ ("C-x M-g" . magit-dispatch)
+ ("C-c M-g" . magit-file-dispatch)))))
(when (or force
(not (or (lookup-key map (kbd key))
(where-is-internal def (make-sparse-keymap) t))))
