Next: , Previous: , Up: Miscellaneous   [Contents][Index]


8.8 Minor Mode for Buffers Visiting Files

The minor-mode magit-file-mode enables certain Magit features in file-visiting buffers belonging to a Git repository. The globalized variant global-magit-file-mode enables the local mode in all such buffers. It is enabled by default. Currently the local mode only establishes a few key bindings, but this might be extended in the future.

User Option: global-magit-file-mode

Whether to establish certain Magit key bindings in all file-visiting buffers belonging to any Git repository. This is enabled by default. This globalized mode turns on the local minor-mode magit-file-mode in all suitable buffers.

Variable: magit-file-mode-map

This keymap is used by the local minor-mode magit-file-mode and establishes the key bindings described below.

Note that the default binding for magit-file-dispatch is very cumbersome to use and that we recommend that you add a better binding.

Instead of C-c M-g I would have preferred to use C-c g because (1) it is similar to C-x g (the recommended global binding for ~magit-status), (2) we cannot use C-c C-g because we have been recommending that that be bound to magit-dispatch for a long time, (3) we cannot use C-x C-g because that is a convenient way of aborting the incomplete key sequence C-x, and most importantly (4) it would make it much easier to type the next key (a suffix binding) because most of those are letters.

For example C-c g b is much easier to type than C-c M-g b. For suffix bindings that use uppercase letters, the default is just horrible—having to use e.g. C-c M-g B (Control+c Meta+g Shift+b) would drive anyone up the walls (or to Vim).

However C-c LETTER bindings are reserved for users (see (elisp)Key Binding Conventions). Packages are forbidden from using those. Doing so anyway is considered heresy. Therefore if you want a better binding, you have to add it yourself:

(define-key magit-file-mode-map
  (kbd "C-c g") 'magit-file-dispatch)

The key bindings shown below assume that you have not improved the binding for magit-file-dispatch.

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.

C-c M-g s     (magit-stage-file)

Stage all changes to the file being visited in the current buffer.

C-c M-g u     (magit-unstage-file)

Unstage all changes to the file being visited in the current buffer.

C-c M-g c     (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 Initiating a Commit.

C-c M-g D     (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 Diffing.

This is the same command that d is bound to in Magit buffers. If this command is invoked from a file-visiting buffer, then the initial value of the option (--) that limits the diff to certain file(s) is set to the visited file.

C-c M-g d     (magit-diff-buffer-file)

This command shows the diff for the file of blob that the current buffer visits.

User Option: magit-diff-buffer-file-locked

This option controls whether magit-diff-buffer-file uses a dedicated buffer. See Modes and Buffers.

C-c M-g L     (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 Logging.

This is the same command that l is bound to in Magit buffers. If this command is invoked from a file-visiting buffer, then the initial value of the option (--) that limits the log to certain file(s) is set to the visited file.

C-c M-g l     (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 --follow is part of magit-log-arguments. When the region is active, the log is restricted to the selected line range.

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

This option controls whether magit-log-buffer-file uses a dedicated buffer. See Modes and Buffers.

C-c M-g B     (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 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.

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.

C-c M-g p     (magit-blob-previous)

Visit the previous blob which modified the current file.

There are a few additional commands that operate on a single file but are not enabled in the file transient command by default:

Command: magit-file-rename

This command renames a file read from the user.

Command: magit-file-delete

This command deletes a file read from the user.

Command: magit-file-untrack

This command untracks a file read from the user.

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.

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 (transient)Enabling and Disabling Suffixes.


Next: , Previous: , Up: Miscellaneous   [Contents][Index]