diff options
Diffstat (limited to '.config/emacs/lisp/magit/docs/magit.org')
| -rw-r--r-- | .config/emacs/lisp/magit/docs/magit.org | 9641 |
1 files changed, 0 insertions, 9641 deletions
diff --git a/.config/emacs/lisp/magit/docs/magit.org b/.config/emacs/lisp/magit/docs/magit.org deleted file mode 100644 index 62912c2..0000000 --- a/.config/emacs/lisp/magit/docs/magit.org +++ /dev/null @@ -1,9641 +0,0 @@ -#+title: Magit User Manual -:PREAMBLE: -#+author: Jonas Bernoulli -#+email: emacs.magit@jonas.bernoulli.dev -#+date: 2015-{{{year}}} - -#+texinfo_dir_category: Emacs -#+texinfo_dir_title: Magit: (magit). -#+texinfo_dir_desc: Using Git from Emacs with Magit. -#+subtitle: for version 4.5.0 - -#+setupfile: .orgconfig - -# Emacs on GNU ELPA build server is too old, so all "man:" links -# will be broken, but this at least allows us to generate the manual. -#+options: broken-links:mark - -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. - -#+texinfo: @noindent -This manual is for Magit version 4.5.0. - -#+texinfo: @insertcopying -:END: -* 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 (~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 ~s~ or ~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 ~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 [[https://github.com/emacs-evil/evil][Evil]], the "Extensible VI Layer for Emacs", -and [[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: ~add~, ~am~, ~bisect~, ~blame~, ~branch~, ~checkout~, ~cherry~, -~cherry-pick~, ~clean~, ~clone~, ~commit~, ~config~, ~describe~, ~diff~, ~fetch~, -~format-patch~, ~init~, ~log~, ~merge~, ~merge-tree~, ~mv~, ~notes~, ~pull~, ~rebase~, -~reflog~, ~remote~, ~request-pull~, ~reset~, ~revert~, ~rm~, ~show~, ~stash~, -~submodule~, ~subtree~, ~tag~, and ~worktree.~ Many more Magit porcelain -commands are implemented on top of Git plumbing commands. - -* Installation - -Magit can be installed using Emacs' package manager or manually from -its development repository. - -** 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 -[[info:emacs#Packages]]. Then add one of the archives to -~package-archives~: - -- To use Melpa: - -#+begin_src emacs-lisp - (require 'package) - (add-to-list 'package-archives - '("melpa" . "https://melpa.org/packages/") t) -#+end_src - -- To use Melpa-Stable: - -#+begin_src emacs-lisp - (require 'package) - (add-to-list 'package-archives - '("melpa-stable" . "https://stable.melpa.org/packages/") t) -#+end_src - -Once you have added your preferred archive, you need to update the -local package list using: - -#+begin_example - M-x package-refresh-contents RET -#+end_example - -Once you have done that, you can install Magit and its dependencies -using: - -#+begin_example - M-x package-install RET magit RET -#+end_example - -Now see [[*Post-Installation Tasks]]. - -** Installing from the Git Repository - -Magit depends on the ~compat~, ~cond-let~, ~llama~, ~seq~ (the built-in version -is enough when using Emacs >= 29.1), ~transient~ and ~with-editor~ libraries -which are available from Melpa and Melpa-Stable. Install them using -~M-x package-install RET <package> RET~. Of course you may also install -them manually from their repository. - -Then clone the Magit repository: - -#+begin_src shell-script - $ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit - $ cd ~/.emacs.d/site-lisp/magit -#+end_src - -Then compile the libraries and generate the info manuals: - -#+begin_src shell-script - $ make -#+end_src - -If you haven't installed ~compat~, ~cond-let~, ~llama~, ~seq~ -(only for Emacs 28), ~transient~ and ~with-editor~ from Melpa, or at -~/path/to/magit/../<package>~, then you have to tell ~make~ where to find -them. To do so create the file ~/path/to/magit/config.mk~ with the -following content before running ~make~: - -#+begin_src makefile - LOAD_PATH = -L ~/.emacs.d/site-lisp/magit/lisp - LOAD_PATH += -L ~/.emacs.d/site-lisp/compat - LOAD_PATH += -L ~/.emacs.d/site-lisp/cond-let - LOAD_PATH += -L ~/.emacs.d/site-lisp/llama - LOAD_PATH += -L ~/.emacs.d/site-lisp/seq - LOAD_PATH += -L ~/.emacs.d/site-lisp/transient/lisp - LOAD_PATH += -L ~/.emacs.d/site-lisp/with-editor/lisp -#+end_src - -Finally add this to your init file: - -#+begin_src emacs-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/docs/")) -#+end_src - -Of course if you installed the dependencies manually as well, then -you have to tell Emacs about them too, by prefixing the above with: - -#+begin_src emacs-lisp - (add-to-list 'load-path "~/.emacs.d/site-lisp/compat") - (add-to-list 'load-path "~/.emacs.d/site-lisp/cond-let") - (add-to-list 'load-path "~/.emacs.d/site-lisp/llama") - (add-to-list 'load-path "~/.emacs.d/site-lisp/seq") - (add-to-list 'load-path "~/.emacs.d/site-lisp/transient/lisp") - (add-to-list 'load-path "~/.emacs.d/site-lisp/with-editor") -#+end_src - -Note that you have to add the ~lisp~ subdirectory to the ~load-path~, not -the top-level of the repository, and that elements of ~load-path~ should -not end with a slash, while those of ~Info-directory-list~ should. - -Instead of requiring the feature ~magit~, you could load just the -autoload definitions, by loading the file ~magit-autoloads.el~. - -#+begin_src emacs-lisp - (load "/path/to/magit/lisp/magit-autoloads") -#+end_src - -Instead of running Magit directly from the repository by adding that -to the ~load-path~, you might want to instead install it in some other -directory using ~sudo make install~ and setting ~load-path~ accordingly. - -To update Magit use: - -#+begin_src shell-script - $ git pull - $ make -#+end_src - -At times it might be necessary to run ~make clean all~ instead. - -To view all available targets use ~make help~. - -Now see [[*Post-Installation Tasks]]. - -** 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 ~load-path~. - -#+begin_example - M-x magit-version RET -#+end_example - -should display something like - -#+begin_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 [[*Essential Settings]]. - -To be able to follow cross references to Git manpages found in this -manual, you might also have to manually install the ~gitman~ info manual, -or advice ~Info-follow-nearest-node~ to instead open the actual manpage. -See [[*How to install the gitman info manual?]]. - -If you are completely new to Magit then see [[*Getting Started]]. - -If you run into problems, then please see the [[*FAQ]]. Also see the -[[*Debugging Tools]]. - -And last but not least please consider making a donation, to ensure -that I can keep working on Magit. See https://magit.vc/donate. -for various donation options. - -* 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 ~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 ~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 ~C-x g~. (When the status buffer, or any Magit buffer for -that matter, is the current buffer, then you can also use just ~g~ to -refresh it). - -Move between sections using ~p~ and ~n~. Note that the bodies of some -sections are hidden. Type ~TAB~ to expand or collapse the section at -point. You can also use ~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 ~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 ~TAB~, move to -one of the hunks using ~n~, and unstage just that by typing ~u~. Note how -the staging (~s~) and unstaging (~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 ~C-n~), set the mark using ~C-SPC~ and move down -until some added and/or removed lines fall inside the region but not -all of them. Again type ~s~ to stage. - -It is also possible to un-/stage multiple files at once. Move to a -file section, type ~C-SPC~, move to the next file using ~n~, and then ~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 ~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 ~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 ~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 ~P~ to show all the available push commands -and arguments and then ~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 -~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 ~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~. - -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~. - -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 strictly -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. - -* Interface Concepts -** 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 *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 ~magit-mode~. - -- Key: M-x 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. - -*** Switching Buffers - -- Function: magit-display-buffer buffer &optional display-function :: - - This function is a wrapper around ~display-buffer~ and is used to - display any Magit buffer. It displays BUFFER in some window and, - unlike ~display-buffer~, also selects that window, provided - ~magit-display-buffer-noselect~ is ~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 ~nil~ and the function specified - by ~magit-display-buffer-function~ is used. - -- Variable: magit-display-buffer-noselect :: - - When this is non-~nil~, then ~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. - -- User Option: magit-display-buffer-function :: - - The function specified here is called by ~magit-display-buffer~ with - one argument, a buffer, to actually display that buffer. This - function should call ~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 ~display-buffer~, that function - itself can be used here, in which case the display actions have to - be specified by adding them to ~display-buffer-alist~ instead. - - To learn about display actions, see [[info:elisp#Choosing Window]]. - -- Function: magit-display-buffer-traditional buffer :: - - This function is the current default value of the option - ~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). - -- Function: 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 ~magit-diff-mode~ or - ~magit-process-mode~, it is displayed in another window. - -- Function: magit-display-buffer-fullframe-status-v1 :: - - This function fills the entire frame when displaying a status - buffer. Otherwise, it behaves like - ~magit-display-buffer-traditional~. - -- Function: magit-display-buffer-fullframe-status-topleft-v1 :: - - This function fills the entire frame when displaying a status - buffer. It behaves like ~magit-display-buffer-fullframe-status-v1~ - except that it displays buffers that derive from ~magit-diff-mode~ - or ~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 - ~magit-display-buffer-traditional~ were in use. - -- Function: 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 ~magit-process-mode~, - or (2) the buffer's mode derives from ~magit-diff-mode~, provided - that the mode of the current buffer derives from ~magit-log-mode~ or - ~magit-cherry-mode~. - -- User Option: magit-pre-display-buffer-hook :: - - This hook is run by ~magit-display-buffer~ before displaying the - buffer. - -- Function: magit-save-window-configuration :: - - This function saves the current window configuration. Later when - the buffer is buried, it may be restored by - ~magit-restore-window-configuration~. - -- User Option: magit-post-display-buffer-hook :: - - This hook is run by ~magit-display-buffer~ after displaying the - buffer. - -- Function: 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 ~magit-mode-quit-window~, to determine - whether the window should be deleted when its last Magit buffer is - buried. - -*** Naming Buffers - -- User Option: magit-generate-buffer-name-function :: - - The function used to generate the names of Magit buffers. - - Such a function should take the options ~magit-uniquify-buffer-names~ - as well as ~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 - ~magit-buffer-name-format~, then its own doc-string should describe - the additions. - -- Function: 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 ~default-directory~ is located. - - This function uses ~magit-buffer-name-format~ and supporting all of - the %-sequences mentioned the documentation of that option. It also - respects the option ~magit-uniquify-buffer-names~. - -- User Option: magit-buffer-name-format :: - - The format string used to name Magit buffers. - - At least the following %-sequences are supported: - - - ~%m~ - - The name of the major-mode, but with the ~-mode~ suffix removed. - - - ~%M~ - - Like ~%m~ but abbreviate ~magit-status-mode~ as ~magit~. - - - ~%v~ - - The value the buffer is locked to, in parentheses, or an empty - string if the buffer is not locked to a value. - - - ~%V~ - - Like ~%v~, but the string is prefixed with a space, unless it is an - empty string. - - - ~%t~ - - The top-level directory of the working tree of the repository, or - if ~magit-uniquify-buffer-names~ is non-~nil~ an abbreviation of that. - - - ~%x~ - - If ~magit-uniquify-buffer-names~ is ~nil~ "*", otherwise the empty - string. Due to limitations of the ~uniquify~ package, buffer names - must end with the path. - - The value should always contain ~%m~ or ~%M~, ~%v~ or ~%V~, and ~%t~. If - ~magit-uniquify-buffer-names~ is non-~nil~, then the value must end with - ~%t~ or ~%t%x~. See issue #2841. - -- User Option: 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 ~uniquify~ package; customize its options to - control how buffer names are uniquified. - -*** Quitting Windows - -- Key: q (magit-mode-bury-buffer) :: - - This command buries or kills the current Magit buffer. The function - specified by option ~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. - -- User Option: magit-bury-buffer-function :: - - The function used to actually bury or kill the current buffer. - - ~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 ~magit-mode-quit-window~. - -- Function: magit-restore-window-configuration kill-buffer :: - - Bury or kill the current buffer using ~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. - -- Function: magit-mode-quit-window kill-buffer :: - - Bury or kill the current buffer using ~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. - -*** 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: - -#+begin_src emacs-lisp - (with-eval-after-load 'magit-mode - (add-hook 'after-save-hook 'magit-after-save-refresh-status t)) -#+end_src - -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. - -- Key: g (magit-refresh) :: - - This command refreshes the current buffer if its major mode derives - from ~magit-mode~ as well as the corresponding status buffer. - - If the option ~magit-revert-buffers~ calls for it, then it also - reverts all unmodified buffers that visit files being tracked in the - current repository. - -- Key: G (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 - ~magit-revert-buffers~ is ~nil~. - -- User Option: 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. - -- User Option: 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. - -- Function: magit-after-save-refresh-status :: - - This function is intended to be added to ~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. - -*** 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 ~g~ (~magit-refresh~) to save and -refresh explicitly. - -- User Option: 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 ~dontask~ then this is done without user - intervention. If it is ~t~ then the user has to confirm each save. - -*** 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 ~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 ~M-x revert-buffer RET RET~ in -the visiting buffer before you could continue making changes. - -- User Option: 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. - -- User Option: 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 /instead of/ ~magit-auto-revert-mode~. - -- User Option: magit-auto-revert-immediately :: - - This option controls whether Magit reverts buffers immediately. - - If this is non-~nil~ and either ~global-auto-revert-mode~ or - ~magit-auto-revert-mode~ is enabled, then Magit immediately reverts - buffers by explicitly calling ~auto-revert-buffers~ after running Git - for side-effects. - - If ~auto-revert-use-notify~ is non-~nil~ (and file notifications are - actually supported), then ~magit-auto-revert-immediately~ does not - have to be non-~nil~, because the reverts happen immediately anyway. - - If ~magit-auto-revert-immediately~ and ~auto-revert-use-notify~ are both - ~nil~, then reverts happen after ~auto-revert-interval~ seconds of user - inactivity. That is not desirable. - -- User Option: auto-revert-use-notify :: - - This option controls whether file notification functions should be - used. Note that this variable unfortunately defaults to ~t~ even on - systems on which file notifications cannot be used. - -- User Option: magit-auto-revert-tracked-only :: - - This option controls whether ~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. - -- User Option: auto-revert-mode :: - - The global mode ~magit-auto-revert-mode~ works by turning on this - local mode in the appropriate buffers (but ~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. - -- User Option: auto-revert-stop-on-user-input :: - - This option controls whether the arrival of user input suspends the - automatic reverts for ~auto-revert-interval~ seconds. - -- User Option: auto-revert-interval :: - - This option controls how many seconds Emacs waits for before - resuming suspended reverts. - -- User Option: auto-revert-buffer-list-filter :: - - This option specifies an additional filter used by - ~auto-revert-buffers~ to determine whether a buffer should be reverted - or not. - - This option is provided by Magit, which also advises - ~auto-revert-buffers~ to respect it. Magit users who do not turn on - the local mode ~auto-revert-mode~ themselves, are best served by - setting the value to ~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 ~auto-revert-mode~ in buffers in which Magit - doesn't do that for them, should likely not use any filter. Users - who turn on ~global-auto-revert-mode~, do not have to worry about this - option, because it is disregarded if the global mode is enabled. - -- User Option: auto-revert-verbose :: - - This option controls whether Emacs reports when a buffer has been - reverted. - -The options with the ~auto-revert-~ prefix are located in the Custom -group named ~auto-revert~. The other, Magit-specific, options are -located in the ~magit~ group. - -**** Risk of Reverting Automatically -:PROPERTIES: -:TEXINFO-NODE: t -:END: - -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 ~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). - -** 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. - -*** Section Movement - -To move within a section use the usual keys (~C-p~, ~C-n~, ~C-b~, ~C-f~ etc), -whose global bindings are not shadowed. To move to another section use -the following commands. - -The section movement commands described here run the hook -~magit-section-movement-hook~. Note that they explicitly run that hook -and that arbitrary other movement, defined in Emacs and other packages, -do not run that hook. That hook, and hook functions that can be added -to it, or are part of its default value, are described below. - -- Key: p (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. - -- Key: n (magit-section-forward) :: - - Move to the beginning of the next visible section. - -- Key: M-p (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. - -- Key: M-n (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. - -- Key: ^ (magit-section-up) :: - - Move to the beginning of the parent of the current section. - -The above commands all call the hook ~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 -~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: - -#+begin_src emacs-lisp - (with-eval-after-load 'magit-diff - (remove-hook 'magit-section-movement-hook - 'magit-hunk-set-window-start)) -#+end_src - -- Variable: magit-section-movement-hook :: - - This hook is run by all of the above section movement commands, - after arriving at the destination. It is *not* run by arbitrary other - movement commands (such as ~next-line~), which are provided by Emacs - or third-party packages. - -- Function: magit-hunk-set-window-start :: - - This hook function ensures that the beginning of the current section - is visible, provided it is a ~hunk~ section. Otherwise, it does - nothing. - - Loading ~magit-diff~ adds this function to the hook. - -- Function: 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 - ~magit-section-movement-hook~, then you must remove the hunk-only - variant in turn. - -- Function: magit-log-maybe-show-more-commits :: - - This hook function only has an effect in log buffers, and ~point~ is - on the "show more" section. If that is the case, then it doubles - the number of commits that are being shown. - - Loading ~magit-log~ adds this function to the hook. - -- Function: 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 ~magit-log~ adds this function to the hook. - -- Function: 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. - -- Function: 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. - -- Function: 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. - -- Function: 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. - -- Function: 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. - -- User Option: magit-update-other-window-delay :: - - Delay before automatically updating the other window. - - When moving around in certain buffers using Magit's own section - movement commands (but not other movement commands), 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. - -*** Section Visibility - -Magit provides many commands for changing the visibility of sections, -but all you need to get started are the next two. - -- Key: TAB (magit-section-toggle) :: - - Toggle the visibility of the body of the current section. - -- Key: C-c TAB (magit-section-cycle) :: -- Key: C-<tab> (magit-section-cycle) :: - - Cycle the visibility of current section and its children. - - If this command is invoked using ~C-<tab>~ and that is globally bound - to ~tab-next~, then this command pivots to behave like that command, - and you must instead use ~C-c TAB~ to cycle section visibility. - - If you would like to keep using ~C-<tab>~ to cycle section visibility - but also want to use ~tab-bar-mode~, then you have to prevent that mode - from using this key and instead bind another key to ~tab-next~. Because - ~tab-bar-mode~ does not use a mode map but instead manipulates the - global map, this involves advising ~tab-bar--define-keys~. - -- Key: M-<tab> (magit-section-cycle-diffs) :: - - Cycle the visibility of diff-related sections in the current buffer. - -- Key: S-<tab> (magit-section-cycle-global) :: - - Cycle the visibility of all sections in the current buffer. - -- Key: 1 (magit-section-show-level-1) :: -- Key: 2 (magit-section-show-level-2) :: -- Key: 3 (magit-section-show-level-3) :: -- Key: 4 (magit-section-show-level-4) :: - - Show sections surrounding the current section up to level N. - -- Key: M-1 (magit-section-show-level-1-all) :: -- Key: M-2 (magit-section-show-level-2-all) :: -- Key: M-3 (magit-section-show-level-3-all) :: -- Key: M-4 (magit-section-show-level-4-all) :: - - Show all sections up to level N. - -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. - -- Command: magit-section-show :: - - Show the body of the current section. - -- Command: magit-section-hide :: - - Hide the body of the current section. - -- 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. - -- 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. - -- Command: magit-section-hide-children :: - - Recursively hide the bodies of children of the current section. - -- Command: magit-section-toggle-children :: - - Toggle visibility of bodies of children of the current section. - -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 -~magit-section-set-visibility-hook~. - -- User Option: 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 ~show~ or ~hide~, or a function that returns one of these - symbols. A function is called with the section as the only argument. - - Use the command ~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 ~magit-section-match~. - -- User Option: 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 ~magit-section-cached-visibility~ is - a member of ~magit-section-set-visibility-hook~. - -- Variable: 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 ~hide~ or ~show~, or to leave the visibility - undefined ~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 ~magit-insert-section--oldroot~ is non-~nil~, - then the buffer is being refreshed and these functions should - immediately return ~nil~. - -- User Option: magit-section-visibility-indicators :: - - This option controls whether and how to indicate that a section can - be expanded/collapsed. - - If ~nil~, then don't show any indicators. Otherwise the value has to - be a list with two elements. The first controls the indicators used - in graphical frames, the second the indicators in terminal frames. - For graphical frames all of the following forms are valid, while - terminal frames do not have fringes and thus do not support the first - form. - - - ~(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 - ~left-fringe-width~ in ~magit-mode-hook~, e.g.: - - #+BEGIN_SRC emacs-lisp - (add-hook 'magit-mode-hook - (lambda () (setq left-fringe-width 20))) - #+END_SRC - - - ~(EXPANDABLE-CHAR . COLLAPSIBLE-CHAR)~ - - In this case every section that can be expanded or collapsed - gets an indicator in the left margin. - - - ~(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. - -*** 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 ~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 ~magit-TYPE-sections-hook~ exists. This hook should be -changed using ~magit-add-section-hook~. Avoid using ~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". - -- Function: 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 - ~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. - -To remove a function from a section hook, use ~remove-hook~. - -*** Section Types and Values - -Each section has a type, for example ~hunk~, ~file~, and ~commit~. -Instances of certain section types also have a value. The value of a -section of type ~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. - -- Key: H (magit-describe-section) :: - - This command shows information about the section at point in a - separate buffer. - -- Command: magit-describe-section-briefly :: - - This command shows information about the section at point in the - echo area, as ~#<magit-section VALUE [TYPE PARENT-TYPE...] - BEGINNING-END>~. - -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 *might* be defined, named -~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. - -*** 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. - -- User Option: 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. - -** Transient Commands - -Many Magit commands are implemented as *transient* commands. First the -user invokes a *prefix* command, which causes its *infix* arguments and -*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 ~transient~. Earlier Magit releases -used the package ~magit-popup~ and even earlier versions library -~magit-key-mode~. - -Transient is documented in [[info:transient]]. - -- 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 - 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 ~magit-dispatch~. - - 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 - -The infix arguments of many of Magit's transient prefix commands cease -to have an effect once the ~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 -[[info:transient#Saving Values]]. It is also possible to cycle through -previously used sets of arguments using ~C-M-p~ and ~C-M-n~, see -[[info:transient#Using History]]. - -However the infix arguments of many other transient commands continue -to have an effect even after the ~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 -~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 ~D~ and ~L~. (~d~ and ~l~ on the other hand are -intended to change *what* diff or log is being displayed. It is -possible to also change *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 *changing* the arguments used in the current buffer, -they *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 ~magit-show-commit~ is usually invoked by typing ~RET~ while -point is on a commit in a log, but it can also be invoked from the -~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 ~RET~ in a -log to display the commit at point in a different buffer and then use -~D~ to change how the diff is displayed in that buffer. And then you -press ~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. - -- User Option: 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 ~magit-diff~ and ~magit-log~ transient prefix commands are affected - by this option. - -- User Option: 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. - -#+texinfo: @noindent -Valid values for both of the above options are: - - - ~always~: Always use the set of arguments that is currently active - in the respective buffer, provided that buffer exists of course. - - ~selected~ or ~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. - - ~current~: Use the set of arguments from the respective buffer, but - only if it is the current buffer. - - ~never~: Never use the set of arguments from the respective buffer. - -#+texinfo: @noindent -I am afraid it gets more complicated still: - -- The global diff and log arguments are set for each supported mode - individually. The diff arguments for example have different values - in ~magit-diff-mode~, ~magit-revision-mode~, ~magit-merge-preview-mode~ - and ~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. - -- When ~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. - -- Even though they are suffixes of the diff prefix ~magit-show-commit~ - and ~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. - -- The log prefix also features reflog commands, but these commands do - not use the log arguments. - -- If ~magit-show-refs~ is invoked from a ~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 ~magit-prefix-use-buffer-arguments~. If it is invoked - elsewhere without a prefix argument, then it acts as a direct - command and therefore respects ~magit-direct-use-buffer-arguments~. - -** Completion, Confirmation and the Selection -*** 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 ~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. - -- User Option: 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. - - - Applying changes: - - - ~discard~ Discarding one or more changes (i.e., hunks or the - complete diff for a file) loses that change, obviously. - - - ~reverse~ Reverting one or more changes can usually be undone by - reverting the reversion. - - - ~stage-all-changes~, ~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. - - - Files: - - - ~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. - - - ~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 ~magit-delete-by-moving-to-trash~. - - - ~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. - - - ~untrack~ Untracking a file can be undone by tracking it again. - - - ~rename~ Renaming a file can easily be undone. - - - Sequences: - - - ~reset-bisect~ Aborting (known to Git as "resetting") a bisect - operation loses all information collected so far. - - - ~abort-cherry-pick~ Aborting a cherry-pick throws away all - conflict resolutions which have already been carried out by the - user. - - - ~abort-revert~ Aborting a revert throws away all conflict - resolutions which have already been carried out by the user. - - - ~abort-rebase~ Aborting a rebase throws away all already modified - commits, but it's possible to restore those from the reflog. - - - ~abort-merge~ Aborting a merge throws away all conflict - resolutions which have already been carried out by the user. - - - ~merge-dirty~ Merging with a dirty worktree can make it hard to go - back to the state before the merge was initiated. - - - References: - - - ~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. - - - ~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 ~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. - - - ~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. - - - Publishing: - - - ~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. - - - 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 ~magit-published-branches~. - - - ~amend-published~ Affects most commands that amend to "HEAD". - - - ~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. - - - ~edit-published~ Affects the commands ~magit-edit-line-commit~ and - ~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. - - To disable confirmation completely, add all three symbols here or - set ~magit-published-branches~ to ~nil~. - - - Various: - - - ~stash-apply-3way~ When a stash cannot be applied using ~git stash - apply~, then Magit uses ~git apply~ instead, possibly using the - ~--3way~ argument, which isn't always perfectly safe. See also - ~magit-stash-apply~. - - - ~kill-process~ There seldom is a reason to kill a process. - - - 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 ~magit-wip-before-change-mode~ is enabled, then the following - actions can be undone fairly easily: ~discard~, ~reverse~, - ~stage-all-changes~, and ~unstage-all-changes~. If and only if - this mode is enabled, then ~safe-with-wip~ has the same effect as - adding all of these symbols individually. - -*** 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 ~RET~ or abort using ~C-g~. This is similar to a ~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 -~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. - -- User Option: magit-dwim-selection :: - -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 ~((COMMAND nil|PROMPT DEFAULT)...)~. - -- COMMAND is the command that should not prompt for a choice. - To have an effect, the command has to use the function - ~magit-completing-read~ or a utility function which in turn uses - that function. - -- If the command uses ~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 ~magit-completing-read~. - -- DEFAULT specifies how to use the default. If it is ~t~, then - the DEFAULT argument passed to ~magit-completing-read~ is used - without confirmation. If it is ~ask~, then the user is given - a chance to abort. DEFAULT can also be ~nil~, in which case the - entry has no effect. - -*** 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 *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 *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. - -- Variable: 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. - -*** 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 *body* of a -hunk section and end in the body of the *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. - -*** Support for Completion Frameworks - -The built-in option ~completing-read-function~ specifies the low-level -function used by ~completing-read~ to ask a user to select from a list -of choices. Its default value is ~completing-read-default~. -Alternative completion frameworks typically activate themselves by -substituting their own implementation. - -Mostly for historic reasons Magit provides a similar option named -~magit-completing-read-function~, which only controls the low-level -function used by ~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 -~ivy-mode~, then Magit will respect that, and if you enable ~helm-mode~, -then you are done too. - -- User Option: magit-completing-read-function :: - - The value of this variable is the low-level function used to perform - completion by code that uses ~magit-completing-read~ (as opposed to - the built-in ~completing-read~). - - The default value, ~magit-builtin-completing-read~, is suitable for - the standard completion mechanism, ~ivy-mode~, and ~helm-mode~ at least. - - The built-in ~completing-read~ and ~completing-read-default~ are *not* - suitable to be used here. ~magit-builtin-completing-read~ performs - some additional work, and any function used in its place has to do - the same. - -- Function: magit-builtin-completing-read prompt choices &optional predicate require-match initial-input hist def :: - - This function performs completion using the built-in ~completing-read~ - and does some additional magit-specific work. - -- Function: 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 ~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, ~this-command~ and ~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 ~completing-read~, except for the following: - - - COLLECTION must be a list of choices. A function is not - supported. - - - If REQUIRE-MATCH is ~nil~ and the user exits without a choice, then - ~nil~ is returned instead of an empty string. - - - If REQUIRE-MATCH is ~any~, then do not require a match but - do require non-empty input (or non-~nil~ DEFAULT, since that - is substituted for empty input). - - - If REQUIRE-MATCH is non-~nil~ and the users exits without a choice, - an user-error is raised. - - - FALLBACK specifies a secondary default that is only used if the - primary default DEF is ~nil~. The secondary default is not subject - to ~magit-dwim-selection~ — if DEF is ~nil~ but FALLBACK is not, then - this function always asks the user to choose a candidate, just as - if both defaults were ~nil~. - - - ~format-prompt~ is called on PROMPT and DEF (or FALLBACK if - DEF is ~nil~). This appends ": " to the prompt and may also - add the default to the prompt, using the format specified by - ~minibuffer-default-prompt-format~ and depending on - ~magit-completing-read-default-prompt-predicate~. - -*** Additional Completion Options - -- User Option: 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 ~--sort~ flag of ~git - for-each-ref~. By default, refs are sorted alphabetically by their - full name (e.g., "refs/heads/master"). - -** 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 ~context-menu-mode~. If you use an -older Emacs release, set ~magit-section-show-context-menu-for-emacs<28~. - -** Running Git -*** 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 -~magit-process-buffer~ command, when things don't go as expected. - -The output/errors for up to ~magit-process-log-max~ Git commands are -retained. - -- Key: $ (magit-process-buffer) :: - - This commands displays the process buffer for the current - repository. - -Inside that buffer, the usual key bindings for navigating and showing -sections are available. There is one additional command. - -- Key: k (magit-process-kill) :: - - This command kills the process represented by the section at point. - -- Key: M-x 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 ~$~. - - When git's output is consumed in some way, then it would be too - expensive to also insert it into this buffer, but with this command - that can be enabled temporarily. In that case, if git returns with - a non-zero exit status, then at least its standard error is inserted - into this buffer. - - Also note that just because git exits with a non-zero 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. - -*** Git Process Status - -When a Git process is running for side-effects, Magit displays an -indicator in the mode line, using the ~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 ~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, -set ~magit-process-display-mode-line-error~ to ~nil~. - -Process errors are displayed at the top of the status buffer and in -the echo area. In both places a hint is appended, which informs users -that they can see the full output in the process buffer and how to -display that buffer. However, once you are aware of that, you might -want to set ~magit-show-process-buffer-hint~ to ~nil~. - -*** 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. - -- Key: ! (magit-run) :: - - This transient prefix command binds the following suffix commands - and displays them in a temporary buffer until a suffix is invoked. - -- Key: ! ! (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. - -- Key: : (magit-git-command) :: -- Key: ! p :: - - This command reads a command from the user and executes it in - ~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. - -- Key: ! s (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. - -- Key: ! S (magit-shell-command) :: - - This command reads a command from the user and executes it in - ~default-directory~. With a prefix argument the command is executed - in the top-level directory of the current working tree instead. - -- User Option: 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. - -These suffix commands start external gui tools. - -- Key: ! k (magit-run-gitk) :: - - This command runs ~gitk~ in the current repository. - -- Key: ! a (magit-run-gitk-all) :: - - This command runs ~gitk --all~ in the current repository. - -- Key: ! b (magit-run-gitk-branches) :: - - This command runs ~gitk --branches~ in the current repository. - -- Key: ! g (magit-run-git-gui) :: - - This command runs ~git gui~ in the current repository. - -- Key: ! m (magit-git-mergetool) :: - - This command runs =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. - -*** Git Executable - -When Magit calls Git, then it may do so using the absolute path to the -~git~ executable, or using just its name. - -When running ~git~ locally and the ~system-type~ is ~windows-nt~ (any -Windows version) or ~darwin~ (macOS) then ~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 ~git~ binary, which are also -placed on ~$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 ~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. - -- User Option: magit-git-executable :: - - The ~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. - -- User Option: magit-remote-git-executable :: - - The ~git~ executable used by Magit on remote machines over Tramp. - Normally this should be just the string "git". Consider customizing - ~tramp-remote-path~ instead of this option. - -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 ~exec-path~ or ~tramp-remote-path~ is correct. - -Note that ~exec-path~ is set based on the value of the ~PATH~ environment -variable that is in effect when Emacs is started. If you set ~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 ~exec-path-from-shell~ package -can help; though honestly I consider that a kludge too. - -The command ~magit-debug-git-executable~ can be useful to find out where -Emacs is searching for ~git~. - -- Key: M-x magit-debug-git-executable :: - - This command displays a buffer with information about - ~magit-git-executable~ and ~magit-remote-git-executable~. - -- Key: M-x 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. - -*** Global Git Arguments - -- User Option: 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 ~git HERE... COMMAND REST~. For - valid arguments see [[man:git]] - - 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. - -* 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. - -** 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 ~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 ~C-x g~: - -#+begin_src emacs-lisp - (global-set-key (kbd "C-x g") 'magit-status) -#+end_src - -- Key: C-x g (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 ~magit-repository-directories~, and - the status for the selected repository is shown instead. - - - If that option specifies any existing repositories, then the user - is asked to select one of them. - - - 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. - - - Otherwise the user is offered to initialize the selected directory - as a new repository. After creating the repository its status - buffer is shown. - - These fallback behaviors can also be forced using one or more - prefix arguments: - - - 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 ~magit-init~. - - - 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 - ~magit-repository-directories~, then the behavior is the same as with - two prefix arguments. - -- User Option: magit-repository-directories :: - - List of directories that are Git repositories or contain Git - repositories. - - Each element has the form ~(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 - ~magit-list-repositories~. It also affects ~magit-status~ (which see) - in potentially surprising ways (see above). - -- Command: magit-status-quick :: - - This command is an alternative to ~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 ~magit-status~, - and additionally cause the buffer to be refresh. - - To use this command add this to your init file: - - #+BEGIN_SRC emacs-lisp - (global-set-key (kbd "C-x g") 'magit-status-quick). - #+END_SRC - - If you do that and then for once want to redisplay the buffer and - also immediately refresh it, then type ~C-x g~ followed by ~g~. - - A possible alternative command is ~magit-display-repository-buffer~. - It supports displaying any existing Magit buffer that belongs to the - current repository; not just the status buffer. - -*** Status Sections - -The contents of status buffers is controlled using the hook -~magit-status-sections-hook~. See [[*Section Hooks]] to learn about such -hooks and how to customize them. - -- User Option: magit-status-sections-hook :: - - This hook is run to insert sections into a status buffer. - - The functions described in this section, and the functions - ~magit-insert-status-headers~ and ~magit-insert-untracked-files~, - which are described in subsequent sections, are members of this - hook. - - Some additional functions that can be added to this hook, but are by - default added to another hooks, are listed in [[*References Buffer]]. - -- Function: magit-insert-status-headers :: - - Insert header sections appropriate for ~magit-status-mode~ buffers. - The sections are inserted by running the functions on the hook - ~magit-status-headers-hook~. See [[*Status Header Sections]]. - -- Function: 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. - -- Function: magit-insert-rebase-sequence :: - - Insert section for the on-going rebase sequence. - If no such sequence is in progress, do nothing. - -- Function: magit-insert-am-sequence :: - - Insert section for the on-going patch applying sequence. - If no such sequence is in progress, do nothing. - -- Function: magit-insert-sequencer-sequence :: - - Insert section for the on-going cherry-pick or revert sequence. - If no such sequence is in progress, do nothing. - -- Function: magit-insert-bisect-output :: - - While bisecting, insert section with output from ~git bisect~. - -- Function: magit-insert-bisect-rest :: - - While bisecting, insert section visualizing the bisect state. - -- Function: magit-insert-bisect-log :: - - While bisecting, insert section logging bisect progress. - -- Function: magit-insert-unstaged-changes :: - - Insert section showing unstaged changes. - -- Function: magit-insert-staged-changes :: - - Insert section showing staged changes. - -- Function: magit-insert-stashes &optional ref heading :: - - Insert the ~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:". - -- Function: magit-insert-unpulled-from-upstream :: - - Insert section showing commits that haven't been pulled from the - upstream branch yet. - -- Function: magit-insert-unpulled-from-pushremote :: - - Insert section showing commits that haven't been pulled from the - push-remote branch yet. - -- Function: magit-insert-unpushed-to-upstream-or-recent :: - - Insert section showing unpushed or other recent commits. - If an upstream is configured for the current branch and it is - behind of the current branch, then show the commits that have - not yet been pushed into the upstream branch. If no upstream is - configured or if the upstream is not behind of the current branch, - then show the last ~magit-log-section-commit-count~ commits. - -- Function: magit-insert-unpushed-to-upstream :: - - Insert section showing commits that haven't been pushed to the - upstream yet. - -- Function: magit-insert-unpushed-to-pushremote :: - - Insert section showing commits that haven't been pushed to the - push-remote yet. - -*** Status File List Sections - -These functions honor the buffer's file filter, which can be set using -~D - -~. - -- Function: magit-insert-untracked-files :: - - This function may insert a list of untracked files. Whether it - actually does so, depends on the option described next. - -- User Option: magit-status-show-untracked-files :: - - This option controls whether the above function inserts a list of - untracked files in the status buffer. - - - If ~nil~, do not list any untracked files. - - If ~t~, list untracked files, but if a directory does not contain any - tracked files, then only list that directory, not the contained - untracked files. - - If ~all~, then list each individual untracked files. This is can be - very slow and is discouraged. - - The corresponding values for the Git variable are "no", "normal" - and "all". - - To disable listing untracked files in a specific repository only, - add the following to ~.dir-locals.el~: - - #+begin_src emacs-lisp - ((magit-status-mode - (magit-status-show-untracked-files . "no"))) - #+end_src - - Alternatively (and mostly for historic reasons), it is possible to - use ~git config~ to set the repository-local value: - - #+begin_src shell-script - git config set --local status.showUntrackedFiles no - #+end_src - - This does *not* override the (if any) local value of this Lisp variable, - but it does override its global value. - - See the last section in the git-status(1) manpage, to speed up the part - of the work Git is responsible for. Turning that list into sections is - also not free, so Magit only lists ~magit-status-file-list-limit~ files. - -- User Option: magit-status-file-list-limit :: - - This option controls many files are listed at most in each section - that lists files in the status buffer. For performance reasons, it - is recommended that you do not increase this limit. - -While the above function is a member of ~magit-status-section-hook~ by -default, the following functions have to be explicitly added by the -user. Because that negatively affects performance, it is recommended -that you don't do that. - -- Function: magit-insert-tracked-files :: - - Insert a list of tracked files. - -- Function: magit-insert-ignored-files :: - - Insert a list of ignored files. - -- Function: magit-insert-skip-worktree-files :: - - Insert a list of skip-worktree files. - -- Function: magit-insert-assume-unchanged-files :: - - Insert a list of files that are assumed to be unchanged. - -*** Status Log Sections - -- Function: 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 ~magit-log-section-commit-count~ - commits. - -- Function: magit-insert-recent-commits :: - - Insert section showing the last ~magit-log-section-commit-count~ - commits. - -- User Option: magit-log-section-commit-count :: - - How many recent commits ~magit-insert-recent-commits~ and - ~magit-insert-unpulled-or-recent-commits~ (provided there are no - unpulled commits) show. - -- Function: magit-insert-unpulled-cherries :: - - Insert section showing unpulled commits. - Like ~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 "-". - -- Function: magit-insert-unpushed-cherries :: - - Insert section showing unpushed commits. - Like ~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 "-". - -*** Status Header Sections - -The contents of status buffers is controlled using the hook -~magit-status-sections-hook~ (see [[*Status Sections]]). - -By default ~magit-insert-status-headers~ is the first member of that -hook variable. - -- Function: magit-insert-status-headers :: - - Insert headers sections appropriate for ~magit-status-mode~ buffers. - The sections are inserted by running the functions on the hook - ~magit-status-headers-hook~. - -- User Option: magit-status-headers-hook :: - - Hook run to insert headers sections into the status buffer. - - This hook is run by ~magit-insert-status-headers~, which in turn has - to be a member of ~magit-status-sections-hook~ to be used at all. - -By default the following functions are members of the above hook: - -- Function: 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. - -- Function: magit-insert-diff-filter-header :: - - Insert a header line showing the effective diff filters. - -- Function: magit-insert-head-branch-header :: - - Insert a header line about the current branch or detached ~HEAD~. - -- Function: magit-insert-upstream-branch-header :: - - Insert a header line about the branch that is usually pulled into - the current branch. - -- Function: magit-insert-push-branch-header :: - - Insert a header line about the branch that the current branch is - usually pushed to. - -- Function: 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 ~HEAD~. - -The following functions can also be added to the above hook: - -- Function: magit-insert-repo-header :: - - Insert a header line showing the path to the repository top-level. - -- Function: 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. - -- Function: magit-insert-user-header :: - - Insert a header line about the current user. - -*** Status Module Sections - -The contents of status buffers is controlled using the hook -~magit-status-sections-hook~ (see [[*Status Sections]]). - -By default ~magit-insert-modules~ is /not/ a member of that hook -variable. - -- Function: magit-insert-modules :: - - Insert submodule sections. - - Hook ~magit-module-sections-hook~ controls which module sections are - inserted, and option ~magit-module-sections-nested~ controls whether - they are wrapped in an additional section. - -- User Option: magit-module-sections-hook :: - - Hook run by ~magit-insert-modules~. - -- User Option: magit-module-sections-nested :: - - This option controls whether ~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 ~magit-module-sections-hook~ - become top-level sections. - -- Function: magit-insert-modules-overview :: - - Insert sections for all submodules. For each section insert the - path, the branch, and the output of ~git describe --tags~, - or, failing that, the abbreviated HEAD commit hash. - - Press ~RET~ on such a submodule section to show its own status buffer. - Press ~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. - -- Function: 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. - -- Function: 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. - -- Function: 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. - -- Function: 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. - -*** Status Options - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -Also see the proceeding section for more options concerning status -buffers. - -** Repository List - -- Command: magit-list-repositories :: - - This command displays a list of repositories in a separate buffer. - - The option ~magit-repository-directories~ controls which repositories are - displayed. - -- User Option: magit-repolist-columns :: - - This option controls what columns are displayed by the command - ~magit-list-repositories~ and how they are displayed. - - Each element has the form ~(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 ~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 ~:right-align~, ~:pad-right~ and - ~:sort~. - - The ~:sort~ function has a weird interface described in the - docstring of ~tabulated-list--get-sort~. Alternatively ~<~ and - ~magit-repolist-version<~ can be used as those functions are - automatically replaced with functions that satisfy the interface. - Set ~:sort~ to ~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 ~:pad-right~ to 9. ~+~ is substituted for numbers higher than 9. - -#+texinfo: @noindent -The following functions can be added to the above option: - -- Function: magit-repolist-column-ident :: - - This function inserts the identification of the repository. Usually - this is just its basename. - -- Function: magit-repolist-column-path :: - - This function inserts the absolute path of the repository. - -- Function: magit-repolist-column-version :: - - This function inserts a description of the repository's ~HEAD~ revision. - -- Function: magit-repolist-column-branch :: - - This function inserts the name of the current branch. - -- Function: magit-repolist-column-upstream :: - - This function inserts the name of the upstream branch of the current - branch. - -- Function: magit-repolist-column-branches :: - - This function inserts the number of branches. - -- Function: magit-repolist-column-stashes :: - - This function inserts the number of stashes. - -- Function: magit-repolist-column-flag :: - - This function inserts a flag as specified by - ~magit-repolist-column-flag-alist~. - - By default this indicates whether there are uncommitted changes. - - - ~N~ if there is at least one untracked file. - - ~U~ if there is at least one unstaged file. - - ~S~ if there is at least one staged file. - - Only the first one of these that applies is shown. - -- Function: magit-repolist-column-flags :: - - This functions insert all flags as specified by - ~magit-repolist-column-flag-alist~. - - This is an alternative to function ~magit-repolist-column-flag~, - which only lists the first one found. - -- Function: magit-repolist-column-unpulled-from-upstream :: - - This function inserts the number of upstream commits not in the - current branch. - -- Function: magit-repolist-column-unpulled-from-pushremote :: - - This function inserts the number of commits in the push branch but - not the current branch. - -- Function: magit-repolist-column-unpushed-to-upstream :: - - This function inserts the number of commits in the current branch - but not its upstream. - -- Function: magit-repolist-column-unpushed-to-pushremote :: - - This function inserts the number of commits in the current branch - but not its push branch. - -#+texinfo: @noindent -The following commands are available in repolist buffers: - -- Key: RET (magit-repolist-status) :: - - This command shows the status for the repository at point. - -- Key: m (magit-repolist-mark) :: - - This command marks the repository at point. - -- Key: u (magit-repolist-unmark) :: - - This command unmarks the repository at point. - -- Key: f (magit-repolist-fetch) :: - - This command fetches all marked repositories. If no repositories - are marked, then it offers to fetch all displayed repositories. - -- Key: 5 (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. - -** Logging - -The status buffer contains logs for the unpushed and unpulled commits, -but that obviously isn't enough. The transient prefix command -~magit-log~, on ~l~, features several suffix commands, which show a -specific log in a separate log buffer. - -Like other transient prefix commands, ~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 ~magit-prefix-use-buffer-arguments~ -(see [[*Transient Arguments and Buffer Variables]]). - -For information about the various arguments, see [[man:git-log]] -The switch ~++order=VALUE~ is converted to one of ~--author-date-order~, -~--date-order~, or ~--topo-order~ before being passed to ~git log~. - -The log transient also features several reflog commands. See [[*Reflog]]. - -- Key: l (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. - -- Key: l l (magit-log-current) :: - - Show log for the current branch. When ~HEAD~ is detached or with a - prefix argument, show log for one or more revs read from the - minibuffer. - -- Key: l h (magit-log-head) :: - - Show log for ~HEAD~. - -- Key: l u (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 ~HEAD~ is detached, then show log for that, the - previously checked out branch and its upstream and push-target. - -- Key: l o (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. - -- Key: l L (magit-log-branches) :: - - Show log for all local branches and ~HEAD~. - -- Key: l b (magit-log-all-branches) :: - - Show log for all local and remote branches and ~HEAD~. - -- Key: l a (magit-log-all) :: - - Show log for all references and ~HEAD~. - -Two additional commands that show the log for the file or blob that is -being visited in the current buffer exists, see [[*Commands for Buffers -Visiting Files]]. The command ~magit-cherry~ also shows a log, see -[[*Cherries]]. - -*** Refreshing Logs - -The transient prefix command ~magit-log-refresh~, on ~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. - -- Key: L (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. - -- Key: L g (magit-log-refresh) :: - - This suffix command sets the local log arguments for the current - buffer. - -- Key: L s (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. - -- Key: L w (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. - -- Key: L L (magit-toggle-margin) :: - - Show or hide the margin. - -*** Log Buffer - -- Key: L (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 [[*Refreshing Logs]]. - -- Key: q (magit-log-bury-buffer) :: - - Bury the current buffer or the revision buffer in the same frame. - Like ~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. - -- Key: C-c C-b (magit-go-backward) :: - - Move backward in current buffer's history. - -- Key: C-c C-f (magit-go-forward) :: - - Move forward in current buffer's history. - -- Key: C-c C-n (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. - -- Key: j (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. - -- Key: SPC (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. - -- Key: DEL (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. - -- Key: = (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. - -- Key: + (magit-log-double-commit-limit) :: - - Double the number of commits the current log buffer is limited to. - -- Key: - (magit-log-half-commit-limit) :: - - Half the number of commits the current log buffer is limited to. - -- User Option: magit-log-auto-more :: - - Insert more log entries automatically when moving past the last - entry. Only considered when moving past the last entry with - ~magit-goto-*-section~ commands. - -- User Option: 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. - -- User Option: magit-log-show-color-graph-limit :: - - When showing more commits than specified by this option, then the - ~--color~ argument, if specified, is silently dropped. This is - necessary because the ~ansi-color~ library, which is used to turn - control sequences into faces, is just too slow. - -- User Option: magit-log-show-signatures-limit :: - - When showing more commits than specified by this option, then the - ~--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. - -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 ~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: - -#+begin_example - origin/feature - [green][blue-] - - instead of - - feature origin/feature - [blue-] [green-------] -#+end_example - -Also note that while the transient features the ~--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 ~magit-signature-*~ (which see). - -For a description of ~magit-log-margin~ see [[*Log Margin]]. - -*** 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 ~magit-INFIX-margin~, where INFIX -is the same as in the respective major-mode ~magit-INFIX-mode~. In -regular log buffers that would be ~magit-log-margin~. - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -You can change the STYLE and AUTHOR-WIDTH of all ~magit-INFIX-margin~ -options to the same values by customizing ~magit-log-margin~ *before* -~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 ~magit-log-margin~ to ~nil~, then that is used -in the default of all other options. But setting it to ~t~, i.e. -re-enforcing the default for that option, does not carry to other -options. - -- User Option: 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. - -- Key: L (magit-margin-settings) :: - - This transient prefix command binds the following suffix commands, - each of which changes the appearance of the margin in some way. - -In some buffers that support the margin, ~L~ is instead bound to -~magit-log-refresh~, but that transient features the same commands, and -then some other unrelated commands. - -- Key: L L (magit-toggle-margin) :: - - This command shows or hides the margin. - -- Key: L l (magit-cycle-margin-style) :: - - This command cycles the style used for the margin. - -- Key: L d (magit-toggle-margin-details) :: - - This command shows or hides details in the margin. - -*** Select from Log - -When the user has to select a recent commit that is reachable from -~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: - -- Key: C-c C-c (magit-log-select-pick) :: - - Select the commit at point and act on it. Call - ~magit-log-select-pick-function~ with the selected commit as - argument. - -- Key: C-c C-k (magit-log-select-quit) :: - - Abort selecting a commit, don't act on any commit. - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -*** Reflog - -Also see [[man:git-reflog]] - -These reflog commands are available from the log transient. See -[[*Logging]]. - -- Key: l r (magit-reflog-current) :: - - Display the reflog of the current branch. - -- Key: l O (magit-reflog-other) :: - - Display the reflog of a branch or another ref. - -- Key: l H (magit-reflog-head) :: - - Display the ~HEAD~ reflog. - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -*** Cherries - -Cherries are commits that haven't been applied upstream (yet), and are -usually visualized using a log. Each commit is prefixed with ~-~ if it -has an equivalent in the upstream and ~+~ if it does not, i.e., if it is -a cherry. - -The command ~magit-cherry~ shows cherries for a single branch, but the -references buffer (see [[*References Buffer]]) can show cherries for -multiple "upstreams" at once. - -Also see [[man:git-reflog]] - -- Key: Y (magit-cherry) :: - - Show commits that are in a certain branch but that have not been - merged in the upstream branch. - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -** Diffing - -The status buffer contains diffs for the staged and unstaged commits, -but that obviously isn't enough. The transient prefix command -~magit-diff~, on ~d~, features several suffix commands, which show a -specific diff in a separate diff buffer. - -Like other transient prefix commands, ~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 ~magit-prefix-use-buffer-arguments~ -(see [[*Transient Arguments and Buffer Variables]]). - -Also see [[man:git-diff]] - -- Key: d (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. - -- Key: d d (magit-diff-dwim) :: - - Show changes for the thing at point. - - For example, if point is on a commit, show the changes introduced by - that commit. Likewise if point is on the section titled "Unstaged - changes", then show those changes in a separate buffer. Generally - speaking, compare the thing at point with the most logical, trivial - and (in *any* situation) at least potentially useful other thing it - could be compared to. - - When the region selects commits, then compare the two commits at - either end. There are different ways two commits can be compared. - In the buffer showing the diff, you can control how the comparison, - is done, using "D r" and "D f". - - This function does not always show the changes that you might want - to view in any given situation. You can think of the changes being - shown as the smallest common denominator. There is no AI involved. - If this command never does what you want, then ignore it, and instead - use the commands that allow you to explicitly specify what you need. - -- Key: d r (magit-diff-range) :: - - Show differences between two commits. - - RANGE should be a range (A..B or A...B) but can also be a single - commit. If one side of the range is omitted, then it defaults to - ~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 "..." range). - -- Key: d w (magit-diff-working-tree) :: - - Show changes between the current working tree and the ~HEAD~ commit. - With a prefix argument show changes between the working tree and a - commit read from the minibuffer. - -- Key: d s (magit-diff-staged) :: - - Show changes between the index and the ~HEAD~ commit. With a prefix - argument show changes between the index and a commit read from the - minibuffer. - -- Key: d u (magit-diff-unstaged) :: - - Show changes between the working tree and the index. - -- Key: d p (magit-diff-paths) :: - - Show changes between any two files on disk. - -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: - -- Key: d c (magit-show-commit) :: - - Show the commit at point. If there is no commit at point or with a - prefix argument, prompt for a commit. - -- Key: d t (magit-stash-show) :: - - Show all diffs of a stash in a buffer. - -Two additional commands that show the diff for the file or blob that -is being visited in the current buffer exists, see [[*Commands for -Buffers Visiting Files]]. - -*** Refreshing Diffs - -The transient prefix command ~magit-diff-refresh~, on ~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 ~magit-merge-preview~ because the underlying Git command does -not support these arguments.) - -- Key: D (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. - -- Key: D g (magit-diff-refresh) :: - - This suffix command sets the local diff arguments for the current - buffer. - -- Key: D s (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. - -- Key: D w (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. - -- Key: D t (magit-diff-toggle-refine-hunk) :: - - This command toggles hunk refinement on or off. - -- Key: D r (magit-diff-switch-range-type) :: - - This command converts the diff range type from "revA..revB" to - "revB...revA", or vice versa. - -- Key: D f (magit-diff-flip-revs) :: - - This command swaps revisions in the diff range from "revA..revB" - to "revB..revA", or vice versa. - -- Key: D F (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. - -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. - -- Key: - (magit-diff-less-context) :: - - This command decreases the context for diff hunks by COUNT lines. - -- Key: + (magit-diff-more-context) :: - - This command increases the context for diff hunks by COUNT lines. - -- Key: 0 (magit-diff-default-context) :: - - This command resets the context for diff hunks to the default height. - -The following commands quickly change what diff is being displayed -without having to using one of the diff transient. - -- Key: C-c C-d (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. - -- Key: C-c C-b (magit-go-backward) :: - - This command moves backward in current buffer's history. - -- Key: C-c C-f (magit-go-forward) :: - - This command moves forward in current buffer's history. - -*** Commands Available in Diffs - -Some commands are only available if point is inside a diff. - -~magit-diff-visit-file~ and related commands visit the appropriate -version of the file that the diff at point is about. Likewise -~magit-diff-visit-worktree-file~ and related commands visit the worktree -version of the file that the diff at point is about. See [[*Visiting -Files and Blobs from a Diff]] for more information and the key bindings. - -- Key: C-c C-t (magit-diff-trace-definition) :: - - This command shows a log for the definition at point. - -- User Option: magit-log-trace-definition-function :: - - The function specified by this option is used by - ~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. - -- Key: C-c C-e (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 ~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 ~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 ~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 ~magit-rebase-edit-commit~ instead of this command. - -- Key: j (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. - -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. - -- Key: SPC (scroll-up) :: - - This command scrolls text upward. - -- Key: DEL (scroll-down) :: - - This command scrolls text downward. - -*** Diff Options - -- User Option: magit-diff-refine-hunk :: - - Whether to show word-granularity differences within diff hunks. - - - ~nil~ Never show fine differences. - - ~all~ Show fine differences for all displayed diff hunks. - - ~t~ Refine each hunk once it becomes the current section. - Keep the refinement when another section is selected. - Refreshing the buffer removes all refinement. This - variant is only provided for performance reasons. - -- User Option: magit-diff-refine-ignore-whitespace :: - - Whether to ignore whitespace changes in word-granularity - differences. - -- User Option: 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 ~magit-diff--tab-width-cache~. Set that to ~nil~ to invalidate - the cache. - - - ~nil~ Never adjust tab width. Use `tab-width's value from the Magit - buffer itself instead. - - - ~t~ If the corresponding file-visiting buffer exits, then use - ~tab-width~'s value from that buffer. Doing this is cheap, so this - value is used even if a corresponding cache entry exists. - - - ~always~ If there is no such buffer, then temporarily visit the file - to determine the value. - - - NUMBER Like ~always~, but don't visit files larger than NUMBER - bytes. - -- User Option: magit-diff-paint-whitespace :: - - Specify where to highlight whitespace errors. - - See ~magit-diff-highlight-trailing~, - ~magit-diff-highlight-indentation~. The symbol ~t~ means in all - diffs, ~status~ means only in the status buffer, and ~nil~ means - nowhere. - - - ~nil~ Never highlight whitespace errors. - - ~t~ Highlight whitespace errors everywhere. - - ~uncommitted~ Only highlight whitespace errors in diffs showing - uncommitted changes. For backward compatibility ~status~ is treated - as a synonym. - -- User Option: magit-diff-paint-whitespace-lines :: - - Specify in what kind of lines to highlight whitespace errors. - - - ~t~ Highlight only in added lines. - - ~both~ Highlight in added and removed lines. - - ~all~ Highlight in added, removed and context lines. - -- User Option: magit-diff-highlight-trailing :: - - Whether to highlight whitespace at the end of a line in diffs. Used - only when ~magit-diff-paint-whitespace~ is non-~nil~. - -- User Option: 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 ~magit-diff-paint-whitespace~ is also non-~nil~. - - The value is an alist of the form ~((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 ~tabs~, highlight indentation with tabs. If - INDENT is an integer, highlight indentation with at least that many - spaces. Otherwise, highlight neither. - -- User Option: magit-diff-hide-trailing-cr-characters :: - - Whether to hide ^M characters at the end of a line in diffs. - -- User Option: magit-diff-highlight-hunk-region-functions :: - - This option specifies the functions used to highlight the - hunk-internal region. - - ~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. - - ~magit-diff-highlight-hunk-region-using-overlays~ and - ~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 - 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 ~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. - -- User Option: 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 ~magit-diff-highlight-hunk-region-functions~. - -- User Option: magit-diff-extra-stat-arguments :: - - This option specifies additional arguments to be used alongside - ~--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: ~--stat-width~, ~--stat-name-width~, - ~--stat-graph-width~ and ~--compact-summary~. Also see [[man:git-diff]] - -- User Option: magit-format-file-function :: - - This function is used to format lines representing a file. It is - used for file headings in diffs, in diffstats and for lists of files - (such as the untracked files). Depending on the caller, it receives - either three or five arguments; the signature has to be ~(kind file - face &optional status orig)~. KIND is one of ~diff~, ~module~, ~stat~ and - ~list~. - -*** Revision Buffer - -- User Option: magit-revision-insert-related-refs :: - - Whether to show related branches in revision buffers. - - - ~nil~ Don't show any related branches. - - ~t~ Show related local branches. - - ~all~ Show related local and remote branches. - - ~mixed~ Show all containing branches and local merged branches. - -- User Option: magit-revision-show-gravatars :: - - Whether to show gravatar images in revision buffers. - - If ~nil~, then don't insert any gravatar images. If ~t~, then insert - both images. If ~author~ or ~committer~, then insert only the - respective image. - - If you have customized the option ~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~." - -- User Option: 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 - ~commit~ sections. There is a trade off to be made between - performance and reliability: - - - ~slow~ calls git for every word to be absolutely sure. - - ~quick~ skips words less than seven characters long. - - ~quicker~ additionally skips words that don't contain a number. - - ~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. - - If ~nil~, then no hashes are turned into sections, but you can still - visit the commit at point using "RET". - -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 -~magit-diff-toggle-file-filter~). - -- User Option: 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 ~--follow~. - - When this option is ~nil~, displaying a commit from a log ignores the - log's file filter if the log arguments include ~--follow~. Doing so - avoids showing an empty diff in revision buffers for commits before - a rename event. In such cases, the ~--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 ~--follow~ is present in the log arguments. - -If the revision buffer is not displayed from a log buffer, the file -restriction is determined as usual (see [[*Transient Arguments and -Buffer Variables]]). - -** Ediffing - -This section describes how to enter Ediff from Magit buffers. For -information on how to use Ediff itself, see info:ediff. - -- Key: e (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 ~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. - -- Key: E (magit-ediff) :: - - This transient prefix command binds the following suffix commands - and displays them in a temporary buffer until a suffix is invoked. - -- Key: E r (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 "..." range). - -- Key: E m (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 ~merge.conflictstyle~ is ~diff3~, you can - view the file's merge-base revision using ~/~ 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. - -- Key: E M (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 ~merge.conflictstyle~ is ~diff3~, you can - view the file's merge-base revision using ~/~ in the Ediff control - buffer. - - First the file in the worktree is moved aside, appending the suffix - =.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 ~magit-ediff-resolve-rest~ might be more - suitable. - - The advantage that this command has over ~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. - -- Key: E t (magit-git-mergetool) :: - - This command does not actually use Ediff. While it serves the same - purpose as =magit-ediff-resolve-rest=, it uses =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. - -- Key: E s (magit-ediff-stage) :: - - Stage and unstage changes to a file using Ediff, defaulting to the - file at point. - -- Key: E u (magit-ediff-show-unstaged) :: - - Show unstaged changes to a file using Ediff. - -- Key: E i (magit-ediff-show-staged) :: - - Show staged changes to a file using Ediff. - -- Key: E w (magit-ediff-show-working-tree) :: - - Show changes in a file between ~HEAD~ and working tree using Ediff. - -- Key: E c (magit-ediff-show-commit) :: - - Show changes to a file introduced by a commit using Ediff. - -- Key: E z (magit-ediff-show-stash) :: - - Show changes to a file introduced by a stash using Ediff. - -- User Option: magit-ediff-dwim-resolve-function :: - - This option controls which function ~magit-ediff-dwim~ uses to resolve - conflicts. One of ~magit-ediff-resolve-rest~, ~magit-ediff-resolve-all~ - or ~magit-git-mergetool~; which are all discussed above. - -- User Option: magit-ediff-dwim-show-on-hunks :: - - This option controls what command ~magit-ediff-dwim~ calls when - point is on uncommitted hunks. When ~nil~, always run - ~magit-ediff-stage~. Otherwise, use ~magit-ediff-show-staged~ and - ~magit-ediff-show-unstaged~ to show staged and unstaged changes, - respectively. - -- User Option: magit-ediff-show-stash-with-index :: - - This option controls whether ~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. - -- User Option: 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 ~ediff-quit-hook~ but takes the needs of Magit into - account. The regular ~ediff-quit-hook~ is ignored by Ediff sessions - that were created using a Magit command. - -** References Buffer - -- Key: y (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. - -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 ~magit-refs-show-commit-count~ (see -below). These commands specify a different branch or commit against -which all the other references are compared. - -- Key: y y (magit-show-refs-head) :: - - This command lists branches and tags in a dedicated buffer. Each - reference is being compared with ~HEAD~. - -- Key: y c (magit-show-refs-current) :: - - This command lists branches and tags in a dedicated buffer. Each - reference is being compared with the current branch or ~HEAD~ if it - is detached. - -- Key: y o (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. - -- Key: y r (magit-refs-set-show-commit-count) :: - - This command changes for which refs the commit count is shown. - -- User Option: magit-refs-show-commit-count :: - - Whether to show commit counts in Magit-Refs mode buffers. - - - ~all~ Show counts for branches and tags. - - ~branch~ Show counts for branches only. - - ~nil~ Never show counts. - - The default is ~nil~ because anything else can be very expensive. - -- User Option: 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 ~magit-dimmed~. - - If this is non-~nil~, then spaces are placed on both sides of all - commit counts. - -- User Option: 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. - -- User Option: 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.) - -- User Option: 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 ~*~ or ~@~. - For each other reference, this column optionally shows how many - commits it is ahead of the focused branch and ~<~, or if it isn't - ahead then the commits it is behind and ~>~, or if it isn't behind - either, then a ~=~. - - This column may also display only ~*~ or ~@~ for the focused branch, in - which case this option is ignored. Use ~L v~ to change the verbosity - of this column. - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -- User Option: 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. - -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: - -- ~%a~ Number of commits this ref has over the one we compare to. -- ~%b~ Number of commits the ref we compare to has over this one. -- ~%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. -- ~%C~ For the ref which all other refs are compared this is "@", if it - is the current branch, or "#" otherwise. For all other refs " ". -- ~%h~ Hash of this ref's tip. -- ~%m~ Commit summary of the tip of this ref. -- ~%n~ Name of this ref. -- ~%u~ Upstream of this local branch. -- ~%U~ Upstream of this local branch and additional local vs. upstream - information. - -# new list -- User Option: 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 ~magit-refs-sections-hook~ instead. - - This alist controls which tags and branches are omitted from being - displayed in ~magit-refs-mode~ buffers. If it is ~nil~, then all refs - are displayed (subject to ~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. - -- Key: RET (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 ~magit-show-commit~ as described above, - except if point is on a reference in a ~magit-refs-mode~ buffer, in - which case the behavior may be different, but only if you have - customized the option ~magit-visit-ref-behavior~. - -- User Option: magit-visit-ref-behavior :: - - This option controls how ~magit-visit-ref~ behaves in ~magit-refs-mode~ - buffers. - - By default ~magit-visit-ref~ behaves like ~magit-show-commit~, in all - buffers, including ~magit-refs-mode~ buffers. When the type of the - section at point is ~commit~ then "RET" is bound to ~magit-show-commit~, - and when the type is either ~branch~ or ~tag~ then it is bound to - ~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 ~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 ~M-x magit-show-commit~ to get it back. - - ~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. - - - ~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 ~HEAD~. - - Instead of adding this symbol, consider pressing "C-u y o RET". - - - ~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. - - - ~checkout-any~ - - Check out the reference at point. If that reference is a tag - or a remote branch, then this results in a detached ~HEAD~. - - Instead of adding this symbol, consider pressing "b b RET", - like you would do in other buffers. - - - ~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. - -*** References Sections - -The contents of references buffers is controlled using the hook -~magit-refs-sections-hook~. See [[*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. - -- User Option: magit-refs-sections-hook :: - - Hook run to insert sections into a references buffer. - -- Function: magit-insert-local-branches :: - - Insert sections showing all local branches. - -- Function: magit-insert-remote-branches :: - - Insert sections showing all remote-tracking branches. - -- Function: magit-insert-tags :: - - Insert sections showing all tags. - -** Bisecting - -Also see [[man:git-bisect]] - -- Key: B (magit-bisect) :: - - This transient prefix command binds the following suffix commands - and displays them in a temporary buffer until a suffix is invoked. - -When bisecting is not in progress, then the transient features the -following suffix commands. - -- Key: B B (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. - -- Key: B s (magit-bisect-run) :: - - Bisect automatically by running commands after each step. - -When bisecting in progress, then the transient instead features the -following suffix commands. - -- Key: B b (magit-bisect-bad) :: - - Mark the current commit as bad. Use this after you have asserted - that the commit does contain the bug in question. - -- Key: B g (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. - -- Key: B m (magit-bisect-mark) :: - - Mark the current commit with one of the bisect terms. This command - provides an alternative to ~magit-bisect-bad~ and - ~magit-bisect-good~ and is useful when using terms other than "bad" - and "good". This suffix is disabled by default. - -- Key: B k (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. - -- Key: B r (magit-bisect-reset) :: - - After bisecting, cleanup bisection state and return to original - ~HEAD~. - -By default the status buffer shows information about the ongoing -bisect session. - -- User Option: magit-bisect-show-graph :: - - This option controls whether a graph is displayed for the log of - commits that still have to be bisected. - -** 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 *groups* of such commands and the several *variants* within each -group. - -Also see [[*Commands for Buffers Visiting Files]]. - -*** 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. - -- 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. - -- 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. - -- 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. - -*** Visiting Files and Blobs from a Diff - -These commands can only be used when point is inside a diff. -Elsewhere use ~magit-find-file~. - -- Key: RET (magit-diff-visit-file) :: - - This command visits the appropriate version of the file at point. - - Display the buffer in the selected window. With a prefix argument, - OTHER-WINDOW, instead display the buffer in another window. - - In the visited file or blob, go to the location corresponding to the - location in the diff. - - If point is on an added or context line, visit the blob corresponding - to our side (i.e., the new/right side). If point is on a removed line, - visit the blob corresponding to their side (i.e., the old/left side). - - This applies to diffs of staged and unstaged changes as well. For - staged changes the two sides are blobs from the index and the `HEAD' - commit. For unstaged changes the two sides are the actual file in - the worktree and the blob from the index. - - To visit the file in the worktree, regardless of what the current - diff is about, use ~magit-diff-visit-worktree-file~, described next. - -- Key: C-<return> (magit-diff-visit-worktree-file) :: - - This command visits the worktree version of the appropriate file. - The location of point inside the diff determines which file is being - visited. Unlike ~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. - -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. - -- Command: magit-diff-visit-file-other-window :: -- Command: magit-diff-visit-file-other-frame :: -- Command: magit-diff-visit-worktree-file-other-window :: -- Command: magit-diff-visit-worktree-file-other-frame :: - - These commands behave like the respective commands described above, - except that they display the blob or file in another window or frame. - -- User Option: magit-diff-visit-prefer-worktree :: - - This option controls whether ~magit-diff-visit-file~ always visits the - respective file in the worktree, when invoked anywhere from within a - hunk of staged or unstaged changes. - - By default ~magit-diff-visit-file~ does not do that. Instead it - behaves for staged and unstaged changes as it does for committed - changes, by visiting a blob from the old/left or new/right side, - depending on whether point is on a removed line or not. - - For staged changes the old side is the blob from HEAD and the right - side is the blog from the index. For unstaged changes the left side - is the blob from the index (if there are any changes in the index - for that file, else the blob from HEAD), and the right side is the - file in the worktree. - - Being able to jump to HEAD or the index from a removed line is very - useful, because it allows you to, e.g., use blame to investigate why - some line, which you have already removed, was added in the first - place. - - But if you want to make further changes to already staged changes, - you of course instead need to go to the respective file in the - worktree. The command ~magit-diff-visit-worktree-file~ was created - for that purpose, and it is strongly recommend that you make use of - that command, even if you initially find it inconvenient having to - remember to use ~C-<return>~ instead of ~RET~ in this case. - - While discouraged, you can alternatively set this option to ~t~, - which causes ~magit-diff-visit-file~ itself to go to the file in the - worktree, even when invoked from within a hunk of staged changes. - If you do that, you lose the ability to instantly go to lines you - have already removed. - -- User Option: magit-diff-visit-previous-blob :: - - This option controls whether ~magit-diff-visit-file~ visits the - previous blob when invoked with point on a removed line. - - When this is ~t~ (the default) and point is on a removed line, then - ~magit-diff-visit-file~ visits the blob from the old/left commit, - which still has that line, instead of going to the new/right blob, - which removes that line. - - Setting this to ~nil~, causes ~magit-diff-visit-file~ to always go to - the new/right blob, even when point is on a removed line. This is - very strongly discouraged. Instead place the cursor anywhere else - within the hunk but on a removed line, if you want to visit the new - side. That way you don't lose the ability to visit the old side. - -** Blaming - -Also see [[man:git-blame]] - -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) :: - - 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. - -Note that not all of the following suffixes are available at all -times. For example if ~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. - -- Key: C-c M-g b (magit-blame-addition) :: -- Key: C-c M-g B b :: - - 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 - ~magit-find-file~), where REVISION is a parent of the revision that - added the current line or chunk of lines. - -- Key: C-c M-g r (magit-blame-removal) :: -- Key: C-c M-g B r :: - - 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 ~magit-blame-addition~, this command can be used recursively. - -- Key: C-c M-g f (magit-blame-reverse) :: -- Key: C-c M-g B f :: - - 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 ~magit-blame-addition~, this command can be used recursively. - -- Key: C-c M-g e (magit-blame-echo) :: -- Key: C-c M-g B e :: - - This command is like ~magit-blame-addition~ except that it doesn't - turn on ~read-only-mode~ and that it initially uses the visualization - style specified by option ~magit-blame-echo-style~. - -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. - -- 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. - -- Key: SPC (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. - -- Key: DEL (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. - -The following key bindings are available when both Magit-Blame mode -and Read-Only mode are enabled. - -- Key: b (magit-blame) :: - - See above. - -- Key: n (magit-blame-next-chunk) :: - - This command moves to the next chunk. - -- Key: N (magit-blame-next-chunk-same-commit) :: - - This command moves to the next chunk from the same commit. - -- Key: p (magit-blame-previous-chunk) :: - - This command moves to the previous chunk. - -- Key: P (magit-blame-previous-chunk-same-commit) :: - - This command moves to the previous chunk from the same commit. - -- Key: q (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. - -- Key: M-w (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 ~kill-ring-save~ would. - -- Key: c (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 ~magit-blame-styles~. - -Blaming is also controlled using the following options. - -- User Option: magit-blame-styles :: - - This option defines a list of styles used to visualize blame - information. For now see its doc-string to learn more. - -- User Option: magit-blame-echo-style :: - - This option specifies the blame visualization style used by the - command ~magit-blame-echo~. This must be a symbol that is used as the - identifier for one of the styles defined in ~magit-blame-styles~. - -- User Option: magit-blame-time-format :: - - This option specifies the format string used to display times when - showing blame information. - -- User Option: magit-blame-read-only :: - - This option controls whether blaming a buffer also makes temporarily - read-only. - -- User Option: 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. - -- User Option: magit-blame-goto-chunk-hook :: - - This hook is run when moving between chunks. - -* Manipulating -** Creating Repository - -- Key: I (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. - -** Cloning Repository - -To clone a remote or local repository use ~C~, which is bound to the -command ~magit-clone~. This command either act as a transient prefix -command, which binds several infix arguments and suffix commands, or -it can invoke ~git clone~ directly, depending on whether a prefix -argument is used and on the value of ~magit-clone-always-transient~. - -- User Option: magit-clone-always-transient :: - - This option controls whether the command ~magit-clone~ always acts as - a transient prefix command, regardless of whether a prefix argument - is used or not. If ~t~, then that command always acts as a transient - prefix. If ~nil~, then a prefix argument has to be used for it to act - as a transient. - -- Key: C (magit-clone) :: - - This command either acts as a transient prefix command as described - above or does the same thing as ~transient-clone-regular~ as described - below. - - If it acts as a transient prefix, then it binds the following suffix - commands and several infix arguments. - -- Key: C C (magit-clone-regular) :: - - This command creates a regular clone of an existing repository. - The repository and the target directory are read from the user. - -- Key: C s (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. - -- Key: C > (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 - ~magit-sparse-checkout~ transient (see [[*Sparse checkouts]]). - -- Key: C b (magit-clone-bare) :: - - This command creates a bare clone of an existing repository. - The repository and the target directory are read from the user. - -- Key: C m (magit-clone-mirror) :: - - This command creates a mirror of an existing repository. - The repository and the target directory are read from the user. - -The following suffixes are disabled by default. See -[[info:transient#Enabling and Disabling Suffixes]] for how to enable them. - -- Key: C d (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. - -- Key: C e (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. - -- User Option: magit-clone-set-remote-head :: - - This option controls whether cloning causes the reference - ~refs/remotes/<remote>/HEAD~ to be created in the clone. The default - is to delete the reference after running ~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 ~HEAD~ - of the remote changes. Setting this option to ~t~ preserves Git's - default behavior of creating the reference. - -- User Option: magit-clone-set-remote.pushDefault :: - - This option controls whether the value of the Git variable - ~remote.pushDefault~ is set after cloning. - - - If ~t~, then it is always set without asking. - - If ~ask~, then the users are asked every time they clone a - repository. - - If ~nil~, then it is never set. - -- User Option: magit-clone-default-directory :: - - This option control the default directory name used when reading the - destination for a cloning operation. - - - If ~nil~ (the default), then the value of ~default-directory~ is used. - - If a directory, then that is used. - - If a function, then that is called with the remote url as the only - argument and the returned value is used. - -- User Option: 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 ~(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 ~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. - -- User Option: magit-clone-url-format :: - - The format specified by this option is used when turning repository - names into urls. ~%h~ is the hostname and ~%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 - ~(HOSTNAME . FORMAT)~ mapping hostnames to formats. When an alist - is used, the ~t~ key represents the default format. - - Example of a single format string: - - #+BEGIN_SRC emacs-lisp - (setq magit-clone-url-format - "git@%h:%n.git") - #+END_SRC - - Example of by-hostname format strings: - - #+BEGIN_SRC emacs-lisp - (setq magit-clone-url-format - '(("git.example.com" . "git@%h:~%n") - (nil . "git@%h:%n.git"))) - #+END_SRC - -- User Option: magit-post-clone-hook :: - - Hook run after the Git process has successfully finished cloning the - repository. When the hook is called, ~default-directory~ is - let-bound to the directory where the repository has been cloned. - -** 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 ~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 ~s~ or ~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 [[*Ediffing]]. - -- Key: s (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. - -- Key: S (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. - -- Key: u (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. - -- Key: U (magit-unstage-all) :: - - Remove all changes from the staging area. - -- User Option: magit-unstage-committed :: - - This option controls whether ~magit-unstage~ "unstages" committed - changes by reversing them in the index but not the working tree. - The alternative is to raise an error. - -- Key: M-x 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 ~u~ (~magit-unstage~) is - pressed on a committed change. - - This allows extracting a change from ~HEAD~, while leaving it in the - working tree, so that it can later be committed using a separate - commit. A typical workflow would be: - - 0. Optionally make sure that there are no uncommitted changes. - 1. Visit the ~HEAD~ commit and navigate to the change that should - not have been included in that commit. - 2. Type ~u~ (~magit-unstage~) to reverse it in the index. - This assumes that ~magit-unstage-committed~ is non-~nil~. - 3. Type ~c e~ to extend ~HEAD~ with the staged changes, - including those that were already staged before. - 4. Optionally stage the remaining changes using ~s~ or ~S~ and then - type ~c c~ to create a new commit. - -- Key: M-x 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 ~HEAD~. - -*** 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. - -- Key: M-x 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. - -- Key: M-x 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. - -** 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 ~git apply~, which is why they are called -"apply variants". - -- Stage. Apply a change from the working tree to the index. The change - also remains in the working tree. - -- Unstage. Remove a change from the index. The change remains in the - working tree. - -- 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. - -- Reverse. Reverse a change in the working tree. Both committed and - staged changes can be reversed. Unstaged changes cannot be - reversed. Discard them instead. - -- 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. - -The previous section described the staging and unstaging commands. -What follows are the commands which implement the remaining apply -variants. - -- Key: a (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. - -- Key: k (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. - -- Key: v (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. - -With a prefix argument all apply variants attempt a 3-way merge when -appropriate (i.e., when ~git apply~ is used internally). - -** Committing - -When the user initiates a commit, Magit calls ~git commit~ without the -~--message~ argument, so Git has to get the message from the user. To -do so, it creates a file such as ~.git/COMMIT_EDITMSG~ and then opens -that file in the editor specified by ~$EDITOR~ (or ~$GIT_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 the commit message. - -*** Initiating a Commit - -Also see [[man:git-commit]] - -- Key: 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. - -**** Creating a new commit - -- Key: c c (magit-commit-create) :: - - Create a new commit. - -**** Editing the last commit - -These commands modify the last (a.k.a., "HEAD") commit. The commit is -modified (a.k.a., replaced) immediately. Similar commands exist for -modifying other (non-HEAD) commits. Those commands are described in -the following two sections. For each command in this section, we -mention the respective non-HEAD commands, to make the relation -explicit. - -The command descriptions below mention the specific arguments they use -when calling ~git commit~. The arguments specified in the menu are -appended to those arguments. - -- Key: c e (magit-commit-extend) :: - - This command amends the staged changes to the last commit, without - editing its commit message. - - This command calls ~git commit --amend --no-edit~. - - With a prefix argument the committer date is not updated; without an - argument it is updated. - - The option ~magit-commit-extend-override-date~ can be used to inverse - the meaning of the prefix argument. Non-interactively, the optional - OVERRIDE-DATE argument controls this behavior, and the option is of - no relevance. - -- Key: c a (magit-commit-amend) :: - - This command amends the staged changes to the last commit, and pops - up a buffer to let the user edit its commit message. - - This command calls ~git commit --amend --edit~. - -- Key: c w (magit-commit-reword) :: - - This command pops up a buffer to let the user edit the message of - the latest commit. The commit tree remains unchanged and staged - changes remain staged. - - This command calls ~git commit --amend --only --edit~. - - With a prefix argument the committer date is not updated; without an - argument it is updated. - - The option ~magit-commit-reword-override-date~ can be used to inverse - the meaning of the prefix argument. Non-interactively, the optional - OVERRIDE-DATE argument controls this behavior, and the option is of - no relevance. - -**** Editing any reachable commit - -These commands create a new commit, which targets an existing commit, -from the staged changes and/or using a new commit message. Any commit -that is reachable from HEAD, including HEAD itself, can be the target. - -The new commit is intended to be eventually squashed into the targeted -commit, but this is *not* done immediately. The squashing is done at a -later time, when you explicitly call ~magit-rebase-autosquash~, or use -~--autosquash~ with another rebase command. - -Some of these commands require that you immediately write a new commit -message, or that you immediately edit an existing message. - -The new commits are called "squash" and "fixup" commits. The -difference is that when a "squash" commit is squashed into its -targeted commit, the user gets a chance to modify the message to be -used for the final commit; while for "fixup" commits the existing -message of the targeted commit is used as-is and the message of the -"fixup" commit is discarded. - -If point is on a reachable commit, then all of these commands target -that commit, without requiring confirmation. If point is on some -reachable commit, but you want to target another commit, use a prefix -argument, to select a commit in a log buffer dedicated to that task. -The meaning of the prefix argument can be inverted by customizing -~magit-commit-squash-confirm~. - -The command descriptions below mention the specific arguments they use -when calling ~git commit~. The arguments specified in the menu are -appended to those arguments. - -The next two commands also exist in "instant" variants, which are -described in the next section. Those variants behave the same as the -variants described here, except that they immediately initiate an -~--autosquash~ rebase. - -- Key: c f (magit-commit-fixup) :: - - This command creates a new fixup commit from the staged changes, - targeting the reachable commit at point, if any. Otherwise the - user is prompted for a commit. - - Use this variant if you want to correct some minor defect in the - targeted commit, which does not require changes to the existing - message of the targeted commit. - - This command calls ~git commit --fixup=COMMIT --no-edit~. - -- Key: c s (magit-commit-squash) :: - - This command creates a new squash commit from the staged changes, - targeting the reachable commit at point, if any. Otherwise the - user is prompted for a commit. - - Use this variant if you want a chance to make changes to the final - commit message, but not until the two commits are being squashed - into the final combined commit. - - This command calls ~git commit --squash=COMMIT --no-edit~. - -- Key: c A (magit-commit-alter) :: - - This command creates a new fixup commit from the staged changes, - targeting the reachable commit at point, if any. Otherwise the - user is prompted for a commit. - - Use this variant if you want to write the final commit message now, - but (as for all variants in this section) do not want to immediately - squash the fixup and targeted commits into a final combined commit. - - This command calls ~git commit --fixup=amend:COMMIT --edit~. - -- Key: c n (magit-commit-augment) :: - - This command creates a new squash commit from the staged changes, - targeting the reachable commit at point, if any. Otherwise the - user is prompted for a commit. - - Use this variant if you want to describe the new changes now, but - want to delay writing the final message, which describes the changes - in the combined commit, until you actually combine the squash and - target commits into the final commit. You can think of the new - message, which you write here, as a "note", to be integrated once - once you write the final commit message. - - This command calls ~git commit --squash=COMMIT --edit~. - -- Key: c W (magit-commit-revise) :: - - This command pops up a buffer containing the commit message of the - reachable commit at point, if any. Otherwise the user is prompted - for a commit to target. - - Use this variant if you want to correct the message of the targeted - commit, but want to delay performing the ~--autosquash~ rebase, which - actually changes that commit. - - This command calls ~git commit --fixup=reword:COMMIT --edit~. - -**** Editing any reachable commit and rebasing immediately - -These commands create a new commit, which targets an existing commit, -from the staged changes. Any commit that is reachable from HEAD, -including HEAD itself, can be the target. - -The new commit is immediately squashed into its target commit, using -an ~--autosquash~ rebase. - -The command descriptions below mention the specific arguments they use -when calling ~git commit~. The arguments specified in the menu are -appended to those arguments when calling ~git commit~. - -- Key: c F (magit-commit-instant-fixup) :: - - This command creates a fixup commit, targeting the reachable commit - at point, if any. Otherwise the user is prompted for a commit. Then - it instantly performs a rebase, to squash the new commit into the - targeted commit. - - The original commit message of the targeted commit is left untouched. - - This command calls ~git commit --fixup=COMMIT --no-edit~ - and then ~git rebase --autosquash MERGE-BASE~. - -- Key: c S (magit-commit-instant-squash) :: - - This command creates a squash commit, targeting the reachable commit - at point, if any. Otherwise the user is prompted for a commit. Then - it instantly performs a rebase, to squash the new commit into the - targeted commit. - - During the rebase phase the user is asked to author the final commit - message, based on the original message of the targeted commit. - - This command calls ~git commit --squash=COMMIT --no-edit~ - and then ~git rebase --autosquash MERGE-BASE~. - -**** Options used by commit commands -***** Used by all or most commit commands - -- User Option: magit-commit-show-diff :: - - Whether the relevant diff is automatically shown when committing. - -- User Option: magit-commit-ask-to-stage :: - - Whether to ask to stage all unstaged changes when committing and - nothing is staged. - -- User Option: magit-post-commit-hook :: - - Hook run after creating a commit without the user editing a message. - - This hook is run by ~magit-refresh~ if ~this-command~ is a member - of ~magit-post-commit-hook-commands~. This only includes commands - named ~magit-commit-*~ that do *not* require that the user edits - the commit message in a buffer. - - Also see ~git-commit-post-finish-hook~. - -- User Option: 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 https://github.com/magit/magit/issues/4132. - -***** Used by all squash and fixup commands - -- User Option: 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 - ~magit-commit-squash~ and ~magit-commit-fixup~. The "instant" variants - always require confirmation because making an error while using - those is harder to recover from. - -***** Used by specific commit commands - -- User Option: magit-commit-extend-override-date :: - - Whether using ~magit-commit-extend~ changes the committer date. - -- User Option: magit-commit-reword-override-date :: - - Whether using ~magit-commit-reword~ changes the committer date. - -*** 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 ~git~ -is waiting for the editor, in our case ~emacsclient~, to save the commit -message in a file (in most cases ~.git/COMMIT_EDITMSG~) and then return. -If the editor returns with a non-zero exit status then ~git~ does not -create the commit. So the most important commands are those for -finishing and aborting the commit. - -- Key: C-c C-c (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. - -- Key: C-c C-k (with-editor-cancel) :: - - Cancel the current editing session by returning with exit code 1. - Git then cancels the commit, but leaves the file untouched. - -In addition to being used by ~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. - -- Key: C-c M-s (git-commit-save-message) :: - - Save the current buffer content to the commit message ring. - -- Key: M-p (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. - -- Key: M-n (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. - -By default the diff for the changes that are about to be committed are -automatically shown when invoking the commit. To prevent that, remove -~magit-commit-diff~ from ~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. - -- Key: C-c C-d (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. - -**** Using the Revision Stack - -- Key: C-c C-w (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 ~magit-revision-stack~ and inserts it into the current buffer - according to ~magit-pop-revision-stack-format~. Revisions can be put - on the stack using ~magit-copy-section-value~ and - ~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. - -- User Option: magit-pop-revision-stack-format :: - - This option controls how the command ~magit-pop-revision-stack~ - inserts a revision into the current buffer. - - The entries on the stack have the format ~(HASH TOPLEVEL)~ and this - option has the format ~(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 ~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). - -**** Commit Pseudo Headers - -Some projects use pseudo headers in commit messages. Magit colorizes -such headers and provides some commands to insert such headers. - -- User Option: git-commit-known-pseudo-headers :: - - A list of Git pseudo headers to be highlighted. - -- Key: C-c C-i (git-commit-insert-pseudo-header) :: - - Insert a commit message pseudo header. - -- Key: C-c C-a (git-commit-ack) :: - - Insert a header acknowledging that you have looked at the commit. - -- Key: C-c C-r (git-commit-review) :: - - Insert a header acknowledging that you have reviewed the commit. - -- Key: C-c C-s (git-commit-signoff) :: - - Insert a header to sign off the commit. - -- Key: C-c C-t (git-commit-test) :: - - Insert a header acknowledging that you have tested the commit. - -- Key: C-c C-o (git-commit-cc) :: - - Insert a header mentioning someone who might be interested. - -- Key: C-c C-p (git-commit-reported) :: - - Insert a header mentioning the person who reported the issue being - fixed by the commit. - -- Key: C-c M-i (git-commit-suggested) :: - - Insert a header mentioning the person who suggested the change. - -**** Commit Mode and Hooks - -~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. - -- User Option: git-commit-major-mode :: - - The value of this option is the major mode used to edit Git commit - messages. - -Because ~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 ~git-commit-setup~, which among other things runs -the hook ~git-commit-setup-hook~. - -- User Option: git-commit-setup-hook :: - - Hook run at the end of ~git-commit-setup~. - -#+texinfo: @noindent -The following functions are suitable for this hook: - -- Function: git-commit-save-message :: - - Save the current buffer content to the commit message ring. - -- Function: git-commit-setup-changelog-support :: - - After this function is called, ChangeLog entries are treated as - paragraphs. - -- Function: git-commit-turn-on-auto-fill :: - - Turn on ~auto-fill-mode~. - -- Function: git-commit-turn-on-flyspell :: - - Turn on Flyspell mode. Also prevent comments from being checked and - finally check current non-comment text. - -- Function: git-commit-propertize-diff :: - - Propertize the diff shown inside the commit message buffer. Git - inserts such diffs into the commit message template when the - ~--verbose~ argument is used. ~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. - -- Function: bug-reference-mode :: - - Hyperlink bug references in the buffer. - -- Function: with-editor-usage-message :: - - Show usage information in the echo area. - -- User Option: git-commit-post-finish-hook :: - - Hook run after the user finished writing a commit message. - - This hook is only run after pressing ~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 ~magit-rebase-continue~ this - hook is never run because doing so would lead to a race condition. - - This hook is only run if ~magit~ is available. - - Also see ~magit-post-commit-hook~. - -**** 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. - -- User Option: 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. - -- User Option: 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 ~git-commit-check-style-conventions~. - -- Function: 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. - -- User Option: 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; ~non-empty-second-line~ and - ~overlong-summary-line~. - -** Branching -*** 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 ~origin/master~. For the ~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 /eventually/ end up in a -remote branch such as ~origin/master~ or ~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 ~my-feature~ is usually pushed to ~my-fork/my-feature~ or if you -are a contributor ~origin/my-feature~. After the new feature has been -reviewed, the maintainer merges the feature into ~master~. And finally -~master~ (not ~my-feature~ itself) is pushed to ~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 ~branch.<name>.pushRemote~ and ~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, ~p~ is bound to a command which acts on the -push-remote, ~u~ is bound to a command which acts on the upstream, and ~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 ~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 -[[*Pushing]]). - -*** Branch Commands - -The transient prefix command ~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 -commands. - -- Key: b (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. - -- User Option: magit-branch-direct-configure :: - - This option controls whether the transient command ~magit-branch~ can - be used to directly change the values of Git variables. This defaults - to ~t~ (to avoid changing key bindings). When set to ~nil~, then no - variables are displayed by that transient command, and its suffix - command ~magit-branch-configure~ has to be used instead to view and - change branch related variables. - -- Key: b C (magit-branch-configure) :: -- Key: f C :: -- Key: F C :: -- Key: P C :: - - 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 ~magit-branch~ and on the ~magit-branch-direct-configure~ - option. If ~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. - -The variables are described in [[*Branch Git Variables]]. - -- Key: b b (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 ~HEAD~ becomes detached. Checkout fails if the working tree - or the staging area contain changes. - -- Key: b n (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 ~magit-branch-prefer-remote-upstream~. - -- Key: b c (magit-branch-and-checkout) :: - - This command creates a new branch like ~magit-branch-create~, but then - also checks it out. - - Also see option ~magit-branch-prefer-remote-upstream~. - -- Key: b l (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. - - - If the user selects an existing local branch, then that is checked - out. - - - 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. - - - If the user enters a new branch name, then it creates and checks - that out, after also reading the starting-point from the user. - - 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 ~magit-branch-adjust-remote-upstream-alist~. - -- Key: b s (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 - begun on the old branch (likely but not necessarily "master"). - - If the current branch is a member of the value of option - ~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 ~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 ~HEAD~ are moved to the new - branch. If FROM is not reachable from ~HEAD~ or is reachable from the - source branch's upstream, then an error is raised. - -- Key: b S (magit-branch-spinout) :: - - This command behaves like ~magit-branch-spinoff~, except that it does - not change the current branch. If there are any uncommitted changes, - then it behaves exactly like ~magit-branch-spinoff~. - -- Key: b x (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. - -- Key: b k (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 ~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. - -- Key: b m (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. - -- User Option: 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 ~t~, - and I recommend you leave it at that. - -- User Option: 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 ~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.: - - #+BEGIN_SRC text - feature --upstream--> origin/master - #+END_SRC - - instead of - - #+BEGIN_SRC text - feature --upstream--> master --upstream--> origin/master - #+END_SRC - - Which you prefer is a matter of personal preference. If you do - prefer the former, then you should add branches such as ~master~, - ~next~, and ~maint~ to the value of this options. - -- User Option: 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 ~((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 *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: - - #+BEGIN_SRC emacs-lisp - (("origin/master" . ("master" "next" "maint"))) - #+END_SRC - - Or if the names of all your ephemeral branches contain a slash, - at least in some repositories, then a good value could be: - - #+BEGIN_SRC emacs-lisp - (("origin/master" . "/")) - #+END_SRC - - Of course you can also fine-tune: - - #+BEGIN_SRC emacs-lisp - (("origin/maint" . "\\`hotfix/") - ("origin/master" . "\\`feature/")) - #+END_SRC - - UPSTREAM can be a local branch: - - #+BEGIN_SRC emacs-lisp - (("master" . ("master" "next" "maint"))) - #+END_SRC - -Because the main branch is no longer almost always named "master" -you should also account for other common names: - - #+BEGIN_SRC emacs-lisp - (("main" . ("main" "master" "next" "maint")) - ("master" . ("main" "master" "next" "maint"))) - #+END_SRC - -- Command: magit-branch-orphan :: - - This command creates and checks out a new orphan branch with - contents from a given revision. - -- Command: magit-branch-or-checkout :: - - This command is a hybrid between ~magit-checkout~ and - ~magit-branch-and-checkout~ and is intended as a replacement for the - former in ~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 ~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 ~magit-branch-and-checkout~ does. - - To use this command instead of ~magit-checkout~ add this to your init - file: - - #+BEGIN_SRC emacs-lisp - (transient-replace-suffix 'magit-branch 'magit-checkout - '("b" "dwim" magit-branch-or-checkout)) - #+END_SRC - -*** Branch Git Variables - -These variables can be set from the transient prefix command -~magit-branch-configure~. By default they can also be set from -~magit-branch~. See [[*Branch Commands]]. - -- Variable: branch.NAME.merge :: - - Together with ~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 /branch/. - -- Variable: branch.NAME.remote :: - - Together with ~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 /remote/. - -- Variable: branch.NAME.rebase :: - - This variable controls whether pulling into the branch named NAME is - done by rebasing or by merging the fetched branch. - - - When ~true~ then pulling is done by rebasing. - - When ~false~ then pulling is done by merging. - - When undefined then the value of ~pull.rebase~ is used. The default - of that variable is ~false~. - -- Variable: 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 /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 ~remote.pushDefault~ is defined, - then the value of the latter is used. By default ~remote.pushDefault~ - is undefined. - -- Variable: 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. - -The following variables specify defaults which are used if the above -branch-specific variables are not set. - -- Variable: pull.rebase :: - - This variable specifies whether pulling is done by rebasing or by - merging. It can be overwritten using ~branch.NAME.rebase~. - - - When ~true~ then pulling is done by rebasing. - - When ~false~ (the default) then pulling is done by merging. - - 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 ~true~, and ~branch.master.rebase~ to - ~false~. - -- Variable: remote.pushDefault :: - - This variable specifies what remote the local branches are usually - pushed to. This can be overwritten per branch using - ~branch.NAME.pushRemote~. - -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. - -- Variable: branch.autoSetupMerge :: - - This variable specifies under what circumstances creating a branch - NAME should result in the variables ~branch.NAME.merge~ and - ~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. - - - When ~always~ then the variables are set regardless of whether the - starting point is a local or a remote branch. - - When ~true~ (the default) then the variables are set when the starting - point is a remote branch, but not when it is a local branch. - - When ~false~ then the variables are never set. - -- Variable: branch.autoSetupRebase :: - - This variable specifies whether creating a branch NAME should result - in the variable ~branch.NAME.rebase~ being set to ~true~. - - - When ~always~ then the variable is set regardless of whether the - starting point is a local or a remote branch. - - When ~local~ then the variable are set when the starting point is a - local branch, but not when it is a remote branch. - - When ~remote~ then the variable are set when the starting point is a - remote branch, but not when it is a local branch. - - When ~never~ (the default) then the variable is never set. - -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.: - -#+begin_src shell-script - git config --global remote.autoSetupMerge always -#+end_src - -For more information about these variables you should also see -man:git-config Also see [[man:git-branch]], [[man:git-checkout]] and [[*Pushing]]. - -- User Option: 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 ~magit-read-upstream-branch~ or - ~magit-read-starting-point~, which includes all commands that change - the upstream and many which create new branches. - -*** Auxiliary Branch Commands - -These commands are not available from the transient ~magit-branch~ by -default. - -- 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. - -- Command: magit-branch-unshelve :: - - This command unshelves a branch that was previously shelved using - ~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. - -** Merging - -Also see [[man:git-merge]] For information on how to resolve -merge conflicts see the next section. - -- Key: m (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. - -When no merge is in progress, then the transient features the -following suffix commands. - -- Key: m m (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. - -- Key: m e (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 ~C-c C-c~. - -- Key: m n (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. - -- Key: m a (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 ~magit-branch-pull-request~ was used to create the merged - branch, then the respective remote branch is also removed. - -- Key: m d (magit-merge-dissolve) :: - - 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 ~magit-branch-pull-request~ was used to create the merged - branch, then the respective remote branch is also removed. - -- Key: m s (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. - -- Key: m p (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. - -When a merge is in progress, then the transient instead features the -following suffix commands. - -- Key: m m (magit-merge) :: - - After the user resolved conflicts, this command proceeds with the - merge. If some conflicts weren't resolved, then this command fails. - -- Key: m a (magit-merge-abort) :: - - This command aborts the current merge operation. - -** 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 ~<~, ~|~, ~=~ and ~>~, and are followed by information about the source -of the respective versions, e.g.: - -#+begin_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: - -#+begin_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: - -#+begin_src shell-script - git config --global merge.conflictStyle diff3 -#+end_src - -The above conflict might then have looked like this: - -#+begin_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 -(info:ediff), and Emerge (info:emacs#Emerge). 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 ~RET~ while point is on such a file section shows a buffer -visiting that file, turns on ~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 ~C-c ^ C-h~ and press ~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 ~C-c ^ m~ (~smerge-keep-mine~) to keep the ~HEAD~ -version or ~C-c ^ o~ (~smerge-keep-other~) to keep the version that -follows "|||||||". Then use ~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 ~k~ (~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 ~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 ~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 [[*Ediffing]]. Explaining how to use -Ediff is beyond the scope of this manual, instead see info: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. - -** Rebasing - -Also see [[man:git-rebase]] For information on how to resolve -conflicts that occur during rebases see the preceding section. - -- Key: r (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. - -When no rebase is in progress, then the transient features the -following suffix commands. - -Using one of these commands /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 [[*Information About In-Progress Rebase]]. - -For information about the upstream and the push-remote, see [[*The Two -Remotes]]. - -- Key: r p (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. - -- Key: r u (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. - -- Key: r e (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. - -- Key: r s (magit-rebase-subset) :: - - This command starts a non-interactive rebase sequence to transfer - commits from START to ~HEAD~ onto NEWBASE. START has to be selected - from a list of recent commits. - -By default Magit uses the ~--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 ~--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 ~master~, then you could use ~r-iu~. But we recommend -that you instead do that in two steps. First use ~ri~ to cleanup the -feature branch, and then in a second step ~ru~ to rebase it onto ~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 ~--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. - -- Key: r i (magit-rebase-interactive) :: - - This command starts an interactive rebase sequence. - -- Key: r f (magit-rebase-autosquash) :: - - This command combines squash and fixup commits with their intended - targets. - - By default only commits that are not reachable from the upstream - branch are potentially squashed into. If no upstream is configured - or with a prefix argument, the user is prompted for the first commit - to potentially squash into. - -- Key: r m (magit-rebase-edit-commit) :: - - This command starts an interactive rebase sequence that lets the - user edit a single older commit. - -- Key: r w (magit-rebase-reword-commit) :: - - This command starts an interactive rebase sequence that lets the - user reword a single older commit. - -- Key: r k (magit-rebase-remove-commit) :: - - This command removes a single older commit using rebase. - -When a rebase is in progress, then the transient instead features -the following suffix commands. - -- Key: r r (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. - -- Key: r s (magit-rebase-skip) :: - - This command skips the current commit and restarts the current - rebase operation. - -- Key: r e (magit-rebase-edit) :: - - This command lets the user edit the todo list of the current rebase - operation. - -- Key: r a (magit-rebase-abort) :: - - This command aborts the current rebase operation, restoring the - original branch. - -*** Editing Rebase Sequences - -- Key: C-c C-c (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. - -- Key: C-c C-k (with-editor-cancel) :: - - Cancel the current editing session by returning with exit code 1. - Git then forgoes starting the rebase sequence. - -- Key: RET (git-rebase-show-commit) :: - - Show the commit on the current line in another buffer and select - that buffer. - -- Key: SPC (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. - -- Key: DEL (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. - -- Key: p (git-rebase-backward-line) :: - - Move to previous line. - -- Key: n (forward-line) :: - - Move to next line. - -- Key: M-p (git-rebase-move-line-up) :: - - Move the current commit (or command) up. - -- Key: M-n (git-rebase-move-line-down) :: - - Move the current commit (or command) down. - -- Key: r (git-rebase-reword) :: - - Edit message of commit on current line. - -- Key: e (git-rebase-edit) :: - - Stop at the commit on the current line. - -- Key: s (git-rebase-squash) :: - - This command folds the commit on the current line into the previous - commit, giving the user a change to manually merge the two messages. - -- Key: S (git-rebase-squish) :: - - This command folds the commit on the current line into the previous - commit, discarding the message of the previous commit but giving the - user a change to edit the final message, based on the message of the - current commit. - - This action's indicator, shown in the list of commits, is ~fixup -c~ - (with a lower-case c). - -- Key: f (git-rebase-fixup) :: - - This command folds the commit on the current line into the previous - commit, using only the message of the previous commit as-is and - discarding the message of the current commit. - -- Key: F (git-rebase-alter) :: - - This command folds the commit on the current into the previous - commit, discarding the message of the previous commit and instead - using the message of the current commit as-is. - - This is like ~git-rebase-alter~, except that it uses the other - message. This is also like ~git-rebase-squish~, except that it lets - the user edit the message. - - This action's indicator, shown in the list of commits, is ~fixup -C~ - (with a upper-case C). - -- Key: k (git-rebase-kill-line) :: - - Comment the current action line, or if it is already commented, then - uncomment it. - -- Key: c (git-rebase-pick) :: - - Use commit on current line. - -- Key: x (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. - -- Key: b (git-rebase-break) :: - - Insert a break action before the current line, instructing Git to - return control to the user. - -- Key: y (git-rebase-insert) :: - - Read an arbitrary commit and insert it below current line. - -- Key: C-x u (git-rebase-undo) :: - - Undo some previous changes. Like ~undo~ but works in read-only - buffers. - -- User Option: git-rebase-auto-advance :: - - Whether to move to next line after changing a line. - -- User Option: git-rebase-show-instructions :: - - Whether to show usage instructions inside the rebase buffer. - -- User Option: git-rebase-confirm-cancel :: - - Whether confirmation is required to cancel. - -When a rebase is performed with the ~--rebase-merges~ option, the -sequence will include a few other types of actions and the following -commands become relevant. - -- Key: l (git-rebase-label) :: - - This commands inserts a label action or edits the one at point. - -- Key: t (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. - -- Key: MM (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 ~-c~ or ~-C~ is not - supported; an editor will always be invoked for the merge. - -- Key: Mt (git-rebase-merge-toggle-editmsg) :: - - This command toggles between the ~-C~ and ~-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. - -*** 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 ~HEAD~. -The commits above it have not been applied yet, while the ~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: - -- Commits that use the same foreground color as the ~default~ face have - not been applied yet. - -- 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). - -- Gray commits have already been applied. - -- The blue commit is the ~HEAD~ commit. - -- The green commit is the commit the rebase sequence stopped at. If - this is the same commit as ~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 *and* a blue - commit at the same time, if you create one or more new commits after - rebase stops at a commit. - -- Red commits have been dropped. They are shown for reference only, - e.g., to make it easier to diff. - -Of course these colors are subject to the color-theme in use. - -The following words are used: - -- Commits prefixed with ~pick~, ~reword~, ~edit~, ~squash~, and ~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 [[*Editing Rebase - Sequences]]. When the ~--rebase-merges~ option was specified, - ~reset~, ~label~, and ~merge~ lines may also be present. - -- Commits prefixed with ~done~ and ~onto~ have already been applied. - It is possible for such a commit to be the ~HEAD~, in which case it - is blue. Otherwise it is grey. - - - The commit prefixed with ~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. - - - Commits prefixed with ~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. - -- 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 [fn:patch-id] 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: - - - When a commit is prefixed with ~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 ~HEAD~, and it also isn't one of the commits that - will be applied when resuming the session. - - - When a commit is prefixed with ~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 ~HEAD~). So it is shown in yellow, like the other - commits that still have to be applied. - - - When a commit is prefixed with ~stop~ or a /blue/ or /green/ ~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. - - - When a commit is prefixed with ~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. - - - When a commit is prefixed with a /blue/ or /green/ ~same~, then that - indicates that while its tree or hash changed, its patch-id did - not. If it is blue, then it is the ~HEAD~ commit (as always for - blue). When it is green, then it no longer is ~HEAD~ because - other commit have been created since (but before continuing the - rebase). - - - When a commit is prefixed with ~goal~, a /yellow/ ~same,~ or ~work~, then - that indicates that rebase applied that commit but that you then - reset ~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. - - - When a commit is prefixed with ~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. - - - When a commit is prefixed with a yellow ~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. - - - When a commit is prefixed with ~work~, then that indicates that - you reset ~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. - - - When a commit is prefixed with ~poof~ or ~gone~, then that indicates - that rebase applied that commit but that you then reset ~HEAD~ to an - earlier commit (likely to split it up into multiple commits), and - that there are no uncommitted changes. - - - When a commit is prefixed with ~poof~, then that indicates that it - is no longer reachable from ~HEAD~, but that it has been replaced - with one or more commits, which together have the exact same - effect. - - - When a commit is prefixed with ~gone~, then that indicates that it - is no longer reachable from ~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. - -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. - -[fn:patch-id] The patch-id is a hash of the /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?". - -** Cherry Picking - -Also see [[man:git-cherry-pick]] - -- Key: A (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. - -When no cherry-pick or revert is in progress, then the transient -features the following suffix commands. - -- Key: A A (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. - -- Key: A a (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 ~a~ at the top-level. - -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 ~git-update-ref~ or if necessary ~git-rebase~. Both applying -commits as well as removing them using ~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. - -- Key: A h (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. - -- Key: A d (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. ~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. - -- Key: A n (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. - -- Key: A s (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. - -When a cherry-pick or revert is in progress, then the transient -instead features the following suffix commands. - -- Key: A A (magit-sequence-continue) :: - - Resume the current cherry-pick or revert sequence. - -- Key: A s (magit-sequence-skip) :: - - Skip the stopped at commit during a cherry-pick or revert sequence. - -- Key: A a (magit-sequence-abort) :: - - Abort the current cherry-pick or revert sequence. This discards all - changes made since the sequence started. - -*** Reverting - -- Key: V (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. - -When no cherry-pick or revert is in progress, then the transient -features the following suffix commands. - -- Key: V V (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. - -- Key: V v (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. - -When a cherry-pick or revert is in progress, then the transient -instead features the following suffix commands. - -- Key: V V (magit-sequence-continue) :: - - Resume the current cherry-pick or revert sequence. - -- Key: V s (magit-sequence-skip) :: - - Skip the stopped at commit during a cherry-pick or revert sequence. - -- Key: V a (magit-sequence-abort) :: - - Abort the current cherry-pick or revert sequence. This discards all - changes made since the sequence started. - -** Resetting - -Also see [[man:git-reset]] - -- Key: x (magit-reset-quickly) :: - - Reset the ~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. - -- Key: X m (magit-reset-mixed) :: - - Reset the ~HEAD~ and index to some commit read from the user and - defaulting to the commit at point. The working tree is kept as-is. - -- Key: X s (magit-reset-soft) :: - - Reset the ~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. - -- Key: X h (magit-reset-hard) :: - - Reset the ~HEAD~, index, and working tree to some commit read from the - user and defaulting to the commit at point. - -- Key: X k (magit-reset-keep) :: - - Reset the ~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. - -- Key: X i (magit-reset-index) :: - - Reset the index to some commit read from the user and defaulting to - the commit at point. Keep the ~HEAD~ and working tree as-is, so if - the commit refers to the ~HEAD~, then this effectively unstages all - changes. - -- Key: X w (magit-reset-worktree) :: - - Reset the working tree to some commit read from the user and - defaulting to the commit at point. Keep the ~HEAD~ and index as-is. - -- Key: X f (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. - -** Stashing - -Also see [[man:git-stash]] - -- Key: z (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. - -- Key: z z (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 ~--include-untracked~ while two prefix arguments are - equivalent to ~--all~. - -- Key: z i (magit-stash-index) :: - - Create a stash of the index only. Unstaged and untracked changes - are not stashed. - -- Key: z w (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 ~--include-untracked~ while two prefix - arguments are equivalent to ~--all~. - -- Key: z x (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 ~--include-untracked~ while two - prefix arguments are equivalent to ~--all~. - -- Key: z Z (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 ~--include-untracked~ while two prefix arguments are - equivalent to ~--all~. - -- Key: z I (magit-snapshot-index) :: - - Create a snapshot of the index only. Unstaged and untracked changes - are not stashed. - -- Key: z W (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 ~--include-untracked~ while two - prefix arguments are equivalent to ~--all~-. - -- Key: z a (magit-stash-apply) :: - - Apply a stash to the working tree. - - When using a Git release before v2.38.0, simply run ~git stash apply~ - or with a prefix argument ~git stash apply --index~. - - When using Git v2.38.0 or later, behave more intelligently: - - First try ~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. - - If ~git stash~ fails, then potentially fall back to using ~git apply~. - If the stash does not touch any unstaged files, then pass ~--3way~ to - that command. Otherwise ask the user whether to use that argument - or ~--reject~. Customize ~magit-no-confirm~ if you want to fall back - to using ~--3way~, without being prompted. - -- Key: z p (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. - - When using a Git release before v2.38.0, simply run ~git stash pop~ - or with a prefix argument ~git stash pop --index~. - - When using Git v2.38.0 or later, behave more intelligently: - - First try ~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. - - If ~git stash~ fails, then potentially fall back to using ~git apply~. - If the stash does not touch any unstaged files, then pass ~--3way~ to - that command. Otherwise ask the user whether to use that argument - or ~--reject~. Customize ~magit-no-confirm~ if you want to fall back - to using ~--3way~, without being prompted. - -- Key: z k (magit-stash-drop) :: - - Remove a stash from the stash list. When the region is active, offer - to drop all contained stashes. - -- Key: z v (magit-stash-show) :: - - Show all diffs of a stash in a buffer. - -- Key: z b (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. - -- Key: z B (magit-stash-branch-here) :: - - Create and checkout a new branch from an existing stash. Use the - current branch or ~HEAD~ as the starting-point of the new branch. - Then apply the stash, dropping it if it applies cleanly. - -- Key: z f (magit-stash-format-patch) :: - - Create a patch from STASH. - -- Key: k (magit-stash-clear) :: - - Remove all stashes saved in REF's reflog by deleting REF. - -- Key: z l (magit-stash-list) :: - - List all stashes in a buffer. - -- User Option: 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 ~(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)~. - - - If INIT is non-~nil~, then the margin is shown initially. - - STYLE controls how to format the author or committer date. It can - be one of ~age~ (to show the age of the commit), ~age-abbreviated~ (to - abbreviate the time unit to a character), or a string (suitable - for ~format-time-string~) to show the actual date. Option - ~magit-log-margin-show-committer-date~ controls which date is being - displayed. - - WIDTH controls the width of the margin. This exists for forward - compatibility and currently the value should not be changed. - - AUTHOR controls whether the name of the author is also shown by - default. - - 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. - -* Transferring -** Remotes -*** Remote Commands - -The transient prefix command ~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 [[man:git-remote]] - -- Key: M (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. - -- User Option: magit-remote-direct-configure :: - - This option controls whether remote-related Git variables are - accessible directly from the transient ~magit-remote~. - - If ~t~ (the default) and a local branch is checked out, then - ~magit-remote~ features the variables for the upstream remote of that - branch, or if ~HEAD~ is detached, for ~origin~, provided that exists. - - If ~nil~, then ~magit-remote-configure~ has to be used to do so. - -- Key: M C (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 ~magit-remote~ and on the ~magit-remote-direct-configure~ - option. If ~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. - -The variables are described in [[*Remote Git Variables]]. - -- Key: M a (magit-remote-add) :: - - This command add a remote and fetches it. The remote name and url - are read in the minibuffer. - -- Key: M r (magit-remote-rename) :: - - This command renames a remote. Both the old and the new names are - read in the minibuffer. - -- Key: M u (magit-remote-set-url) :: - - This command changes the url of a remote. Both the remote and the - new url are read in the minibuffer. - -- Key: M k (magit-remote-remove) :: - - This command deletes a remote, read in the minibuffer. - -- Key: M p (magit-remote-prune) :: - - This command removes stale remote-tracking branches for a remote - read in the minibuffer. - -- Key: M P (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. - -- User Option: magit-remote-add-set-remote.pushDefault :: - - This option controls whether the user is asked whether they want to - set ~remote.pushDefault~ after adding a remote. - - If ~ask~, then users is always ask. If ~ask-if-unset~, then the user is - only if the variable isn't set already. If ~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. - -*** Remote Git Variables - -These variables can be set from the transient prefix command -~magit-remote-configure~. By default they can also be set from -~magit-remote~. See [[*Remote Commands]]. - -- Variable: remote.NAME.url :: - - This variable specifies the url of the remote named NAME. It can - have multiple values. - -- Variable: remote.NAME.fetch :: - - The refspec used when fetching from the remote named NAME. It can - have multiple values. - -- Variable: remote.NAME.pushurl :: - - This variable specifies the url used for pushing to the remote - named NAME. If it is not specified, then ~remote.NAME.url~ is used - instead. It can have multiple values. - -- Variable: remote.NAME.push :: - - The refspec used when pushing to the remote named NAME. It can - have multiple values. - -- Variable: remote.NAME.tagOpts :: - - This variable specifies what tags are fetched by default. If the - value is ~--no-tags~ then no tags are fetched. If the value is - ~--tags~, then all tags are fetched. If this variable has no value, - then only tags are fetched that are reachable from fetched branches. - -** Fetching - -Also see [[man:git-fetch]] For information about the upstream and the -push-remote, see [[*The Two Remotes]]. - -- Key: f (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. - -- Key: f p (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. - -- Key: f u (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 ~magit-fetch~ transient prefix and invoking it directly - results in an error. - -- Key: f e (magit-fetch-other) :: - - This command fetch from a repository read from the minibuffer. - -- Key: f o (magit-fetch-branch) :: - - This command fetches a branch from a remote, both of which are read - from the minibuffer. - -- Key: f r (magit-fetch-refspec) :: - - This command fetches from a remote using an explicit refspec, both - of which are read from the minibuffer. - -- Key: f a (magit-fetch-all) :: - - This command fetches from all remotes. - -- Key: f m (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. - -- User Option: magit-pull-or-fetch :: - - By default fetch and pull commands are available from separate - transient prefix command. Setting this to ~t~ adds some (but not all) - of the above suffix commands to the ~magit-pull~ transient. - - If you do that, then you might also want to change the key binding - for these prefix commands, e.g.: - - #+BEGIN_SRC emacs-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_SRC - -** Pulling - -Also see [[man:git-pull]] For information about the upstream and the -push-remote, see [[*The Two Remotes]]. - -- Key: F (magit-pull) :: - - This transient prefix command binds the following suffix commands - and displays them in a temporary buffer until a suffix is invoked. - -- Key: F p (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. - -- Key: F u (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. - -- Key: F e (magit-pull-branch) :: - - This command pulls from a branch read in the minibuffer. - -** Pushing - -Also see [[man:git-push]] For information about the upstream and the -push-remote, see [[*The Two Remotes]]. - -- Key: P (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. - -- Key: P p (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. - -- Key: P u (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. - -- Key: P e (magit-push-current) :: - - This command pushes the current branch to a branch read in the - minibuffer. - -- Key: P o (magit-push-other) :: - - This command pushes an arbitrary branch or commit somewhere. Both - the source and the target are read in the minibuffer. - -- Key: P r (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. - -- Key: P m (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. - -- Key: P t (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. - -- Key: P T (magit-push-tag) :: - - This command pushes a tag to another repository. - -One of the infix arguments, ~--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 -~--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 ~push.useForceIfIncludes~ to ~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. - -- Command: magit-push-implicitly args :: - - This command pushes somewhere without using an explicit refspec. - - This command simply runs ~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: ~push.default~, - ~remote.pushDefault~, ~branch.<branch>.pushRemote~, - ~branch.<branch>.remote~, ~branch.<branch>.merge~, and - ~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: - - #+BEGIN_SRC emacs-lisp - (transient-insert-suffix 'magit-push \"p\" - '(\"i\" magit-push-implicitly))" - #+END_SRC - -- 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 ~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: ~push.default~, - ~remote.pushDefault~, ~branch.<branch>.pushRemote~, - ~branch.<branch>.remote~, ~branch.<branch>.merge~, and - ~remote.<remote>.push~. - -** Plain Patches - -- Key: W (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. - -- Key: W c (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. - -- Key: w a (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. - -- Key: W s (magit-patch-save) :: - - This command creates a patch from the current diff. - - Inside ~magit-diff-mode~ or ~magit-revision-mode~ buffers, ~C-x C-w~ is - also bound to this command. - -It is also possible to save a plain patch file by using ~C-x C-w~ inside -a ~magit-diff-mode~ or ~magit-revision-mode~ buffer. - -** Maildir Patches - -Also see [[man:git-am]] and [[man:git-apply]] - -- Key: w (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. - -- Key: w w (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. - -- Key: w m (magit-am-apply-maildir) :: - - This command applies patches from a maildir. - -- Key: w a (magit-patch-apply) :: - - This command applies a plain patch. For a longer description see - [[*Plain Patches]]. This command is only available from the ~magit-am~ - transient for historic reasons. - -When an "am" operation is in progress, then the transient instead -features the following suffix commands. - -- Key: w w (magit-am-continue) :: - - This command resumes the current patch applying sequence. - -- Key: w s (magit-am-skip) :: - - This command skips the stopped at patch during a patch applying - sequence. - -- Key: w a (magit-am-abort) :: - - This command aborts the current patch applying sequence. This - discards all changes made since the sequence started. - -* Miscellaneous -** Tagging - -Also see [[man:git-tag]] - -- Key: t (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. - -- Key: t t (magit-tag-create) :: - - This command creates a new tag with the given NAME at REV. With a - prefix argument it creates an annotated tag. - -- Key: t r (magit-tag-release) :: - - This commands creates a release tag. It assumes that release tags - match ~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., - ~v1.2.3-custom.1~), you can set the ~magit-release-tag-regexp~ and - ~magit-tag-version-regexp-alist~ variables. - - If ~--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". - -- Key: t k (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. - -- Key: t p (magit-tag-prune) :: - - This command offers to delete tags missing locally from REMOTE, and - vice versa. - -** Notes - -Also see [[man:git-notes]] - -- Key: T (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. - -- Key: T T (magit-notes-edit) :: - - Edit the note attached to a commit, defaulting to the commit at - point. - - By default use the value of Git variable ~core.notesRef~ or - "refs/notes/commits" if that is undefined. - -- Key: T r (magit-notes-remove) :: - - Remove the note attached to a commit, defaulting to the commit at - point. - - By default use the value of Git variable ~core.notesRef~ or - "refs/notes/commits" if that is undefined. - -- Key: T p (magit-notes-prune) :: - - Remove notes about unreachable commits. - -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_MERGE_WORKTREE". - -- Key: T m (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 - ~core.notesRef~ or "refs/notes/commits" if that is undefined. - -When a notes merge is in progress then the transient features the -following suffix commands, instead of those listed above. - -- Key: T c (magit-notes-merge-commit) :: - - Commit the current notes ref merge, after manually resolving - conflicts. - -- Key: T a (magit-notes-merge-abort) :: - - Abort the current notes ref merge. - -The following variables control what notes reference ~magit-notes-*~, -~git notes~ and ~git show~ act on and display. Both the local and global -values are displayed and can be modified. - -- Variable: core.notesRef :: - - This variable specifies the notes ref that is displayed by default - and which commands act on by default. - -- Variable: notes.displayRef :: - - This variable specifies additional notes ref to be displayed in - addition to the ref specified by ~core.notesRef~. It can have - multiple values and may end with ~*~ to display all refs in the - ~refs/notes/~ namespace (or ~**~ if some names contain slashes). - -** Submodules - -Also see [[man:git-submodule]] - -*** Listing Submodules - -The command ~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 ~magit-insert-modules~ to the hook -~magit-status-sections-hook~ as described in [[*Status Module Sections]]. - -- 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 ~RET~ on the section titled "Modules". - -- User Option: magit-submodule-list-columns :: - - This option controls what columns are displayed by the command - ~magit-list-submodules~ and how they are displayed. - - Each element has the form ~(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 ~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 ~:right-align~, ~:pad-right~ and - ~:sort~. - - The ~:sort~ function has a weird interface described in the - docstring of ~tabulated-list--get-sort~. Alternatively ~<~ and - ~magit-repolist-version<~ can be used as those functions are - automatically replaced with functions that satisfy the interface. - Set ~:sort~ to ~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 ~:pad-right~ to 9. ~+~ is substituted for numbers higher than 9. - -*** Submodule Transient - -- Key: o (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. - -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. - -- Key: o a (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. - -- Key: o r (magit-submodule-register) :: - - This command registers the selected modules by copying their urls - from ".gitmodules" to "$GIT_DIR/config". These values can then be - edited before running ~magit-submodule-populate~. If you don't need - to edit any urls, then use the latter directly. - -- Key: o p (magit-submodule-populate) :: - - This command creates the working directory or directories of the - selected modules, checking out the recorded commits. - -- Key: o u (magit-submodule-update) :: - - This command updates the selected modules checking out the recorded - commits. - -- Key: o s (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. - -- Key: o d (magit-submodule-unpopulate) :: - - This command removes the working directory of the selected modules. - -- Key: o l (magit-list-submodules) :: - - This command displays a list of the current repository's modules. - -- Key: o f (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 ~git fetch~ does not - support not doing that. - -** Subtree - -Also see [[man:git-subtree]] - -- Key: O (magit-subtree) :: - - This transient prefix command binds the two sub-transients; one for - importing a subtree and one for exporting a subtree. - -- Key: O i (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 ~--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. - -- Key: O i a (magit-subtree-add) :: - - This command adds COMMIT from REPOSITORY as a new subtree at PREFIX. - -- Key: O i c (magit-subtree-add-commit) :: - - This command add COMMIT as a new subtree at PREFIX. - -- Key: O i m (magit-subtree-merge) :: - - This command merges COMMIT into the PREFIX subtree. - -- Key: O i f (magit-subtree-pull) :: - - This command pulls COMMIT from REPOSITORY into the PREFIX subtree. - -- Key: O e (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 ~--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. - -- Key: O e p (magit-subtree-push) :: - - This command extract the history of the subtree PREFIX and pushes it - to REF on REPOSITORY. - -- Key: O e s (magit-subtree-split) :: - - This command extracts the history of the subtree PREFIX. - -** Worktree - -Also see [[man:git-worktree]] - -- Key: Z (magit-worktree) :: - - This transient prefix command binds the following suffix commands - and displays them in a temporary buffer until a suffix is invoked. - -- Key: Z b (magit-worktree-checkout) :: - - Checkout BRANCH in a new worktree at PATH. - -- Key: Z c (magit-worktree-branch) :: - - Create a new BRANCH and check it out in a new worktree at PATH. - -- Key: Z m (magit-worktree-move) :: - - Move an existing worktree to a new PATH. - -- Key: Z k (magit-worktree-delete) :: - - Delete a worktree, defaulting to the worktree at point. - The primary worktree cannot be deleted. - -- Key: Z g (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. - -If you want the status buffer to list worktrees, add the function -~magit-insert-worktrees~ to ~magit-status-sections-hook~ as described -in [[*Status Sections]]. If there is only one worktree, this function -inserts nothing. - -** Sparse checkouts - -Sparse checkouts provide a way to restrict the working tree to a -subset of directories. See [[man:git-sparse-checkout]] - -*Warning*: Git introduced the ~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. - -- Key: > (magit-sparse-checkout) :: - - This transient prefix command binds the following suffix commands - and displays them in a temporary buffer until a suffix is invoked. - -- Key: > e (magit-sparse-checkout-enable) :: - - This command initializes a sparse checkout that includes only the - files in the top-level directory. - - Note that ~magit-sparse-checkout-set~ and - ~magit-sparse-checkout-add~ automatically initialize a sparse - checkout if necessary. However, you may want to call - ~magit-sparse-checkout-enable~ explicitly to re-initialize a sparse - checkout after calling ~magit-sparse-checkout-disable~, to pass - additional arguments to ~git sparse-checkout init~, or to execute - the initialization asynchronously. - -- Key: > s (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. - -- Key: > a (magit-sparse-checkout-add) :: - - This command is like ~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. - -- Key: > r (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. - -- Key: > d (magit-sparse-checkout-disable) :: - - This command restores the full checkout. To return to the previous - sparse checkout, call ~magit-sparse-checkout-enable~. - -A sparse checkout can also be initiated when cloning a repository by -using the ~magit-clone-sparse~ command in the ~magit-clone~ transient -(see [[*Cloning Repository]]). - -If you want the status buffer to indicate when a sparse checkout is -enabled, add the function ~magit-sparse-checkout-insert-header~ to -~magit-status-headers-hook~. - -** Bundle - -Also see [[man:git-bundle]] - -- Command: magit-bundle :: - - This transient prefix command binds several suffix commands for - running ~git bundle~ subcommands and displays them in a temporary - buffer until a suffix is invoked. - -** Common Commands - -- Command: magit-switch-to-repository-buffer :: -+ Command: magit-switch-to-repository-buffer-other-window :: -+ Command: magit-switch-to-repository-buffer-other-frame :: -+ 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 ~magit-display-buffer~ to do so and thus - respects ~magit-display-buffer-function~. - -These are some of the commands that can be used in all buffers whose -major-modes derive from ~magit-mode~. There are other common commands -beside the ones below, but these didn't fit well anywhere else. - -- Key: C-w (magit-copy-section-value) :: - - This command saves the value of the current section to the - ~kill-ring~, and, provided that the current section is a commit, - branch, or tag section, it also pushes the (referenced) revision to - the ~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 ~kill-ring~ - instead of the reference name. - - When the region is active, this command saves that to the - ~kill-ring~, like ~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. - -- Key: M-w (magit-copy-buffer-revision) :: - - This command saves the revision being displayed in the current buffer - to the ~kill-ring~ and also pushes it to the ~magit-revision-stack~. It - is mainly intended for use in ~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. - -Outside of Magit ~M-w~ and ~C-w~ are usually bound to ~kill-ring-save~ and -~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 ~kill-ring-save~ instead of as described above. - -** Wip Modes - -Git keeps *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 *not* keep track of *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 *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: ~refs/wip/index/<branchref>~ and -~refs/wip/wtree/<branchref>~, where ~<branchref>~ is the full ref of the -current branch, e.g., ~refs/heads/master~. When the ~HEAD~ is detached -then ~HEAD~ is used in place of ~<branchref>~. - -Checking out another branch (or detaching ~HEAD~) causes the use of -different wip refs for subsequent changes. - -- User Option: 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. - -To view the log for a branch and its wip refs use the commands -~magit-wip-log~ and ~magit-wip-log-current~. You should use ~--graph~ when -using these commands. - -- 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 ~magit-wip-merge-branch~ is ~nil~. - -- 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 ~magit-wip-merge-branch~ is ~nil~. - -- Key: X w (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 ~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). - -Note that even if you enable ~magit-wip-mode~ this won't give you -perfect protection. The most likely scenario for losing changes -despite the use of ~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. - -- Key: M-x 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. - -- User Option: magit-wip-namespace :: - - The namespace used for work-in-progress refs. It has to end with - a slash. The wip refs are named ~<namespace>index/<branchref>~ and - ~<namespace>wtree/<branchref>~. When snapshots are created while - the ~HEAD~ is detached then ~HEAD~ is used in place of ~<branchref>~. - -- User Option: magit-wip-mode-lighter :: - - Mode-line lighter for ~magit-wip--mode~. - -*** Wip Graph - -- User Option: 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. - - If ~immediately~, then use ~git-commit-post-finish-hook~ to - create the merge commit. This is discouraged because it can - lead to a race condition, e.g., during rebases. - -When ~magit-wip-merge-branch~ is ~t~, then the history looks like this: - -#+begin_example - ,*--*--*--*--*--* refs/wip/index/refs/heads/master - / / / -A-----B-----C refs/heads/master -#+end_example - -When ~magit-wip-merge-branch~ is ~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 (~xxO~ commits -below are such boundary commits). - -Starting with - -#+begin_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 - -#+begin_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. - -** 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 [[*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 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 - (setq magit-define-global-key-bindings nil) -#+end_src - -- 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. - -- 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 , x (magit-file-untrack) :: - - 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) :: - - 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. - -- Key: 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]]. - -- Key: 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. - -- Key: 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 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. - -- Key: C-c M-g M (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. - -- Key: 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. - -- Key: C-c M-g p (magit-blob-previous) :: - - This command visits the previous blob which modified the current - file. - -- Key: C-c M-g n (magit-blob-next) :: - - This command visits the next blob which modified the current file. - -- Key: C-c M-g v (magit-find-file) :: - - This command reads a revision and file and visits the respective - blob. - -- Key: C-c M-g V (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. - -- Key: C-c M-g g (magit-status-here) :: - - 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). - - Before doing so, save all file-visiting buffers belonging to the - current repository without prompting. - -- Key: C-c M-g G (magit-display-repository-buffer) :: - - This command reads and displays a Magit buffer belonging to the - current repository, without refreshing it. - -- Key: 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]]. - -- 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 - -The ~magit-blob-mode~ enables certain Magit features in blob-visiting -buffers. Such buffers can be created using ~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. - -- Key: p (magit-blob-previous) :: - - This command visits the previous blob that modified the current - file. - -- Key: n (magit-blob-next) :: - - This command visit the next blob that modified the current file. - -- Key: q (magit-bury-or-kill-buffer) :: - - This command buries the current buffer, if that is being displayed - in multiple windows and/or when a prefix argument is used. If - neither is the case, it instead kills the current buffer. - -You might want to bind ~u~ to another command. Suitable commands -include ~bury-buffer~, ~magit-bury-buffer~ and ~magit-kill-this-buffer~. - -* 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. - -- 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 - ~("-c" "some.variable=compatible-value")~ to - ~magit-git-global-arguments~. - -- Certain settings like ~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 ~--prune~ argument in ~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 - ~--prune~ arguments being displayed in a way that seems to indicate - that no pruning will happen. - -I intend to address these and similar issues in a future release. - -** 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 -~/path/to/repo/.git/config~ instead of ~$HOME/.gitconfig~ or -~/etc/gitconfig~. See [[man:git-config]] - -Similarly, Emacs options can be set for one repository only by editing -~/path/to/repo/.dir-locals.el~. See [[info:emacs#Directory Variables]]. -For example to disable automatic refreshes of file-visiting buffers in -just one huge repository use this: - -- ~/path/to/huge/repo/.dir-locals.el~ - - #+BEGIN_SRC emacs-lisp - ((nil . ((magit-refresh-buffers . nil)))) - #+END_SRC - -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: - -- ~/path/to/tag/invested/repo/.dir-locals.el~ - - #+BEGIN_SRC emacs-lisp - ((magit-status-mode - . ((eval . (magit-disable-section-inserter 'magit-insert-tags-header))))) - #+END_SRC - -# new list -- Function: magit-disable-section-inserter fn :: - - This function disables the section inserter FN in the current - repository. It is only intended for use in ~.dir-locals.el~ and - ~.dir-locals-2.el~. - -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: - -- ~/path/to/huge/repo/.git/config~ - - #+BEGIN_SRC conf - [include] - path = /path/to/huge-gitconfig - #+END_SRC - -- ~/path/to/huge-gitconfig~ - - #+BEGIN_SRC conf - [status] - showUntrackedFiles = no - #+END_SRC - -- ~$HOME/.emacs.d/init.el~ - - #+BEGIN_SRC emacs-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_SRC - -** Essential Settings - -The next three sections list and discuss several variables that many -users might want to customize, for safety and/or performance reasons. - -*** Safety - -This section discusses various variables that you might want to -change (or *not* change) for safety reasons. - -Git keeps *committed* changes around long enough for users to recover -changes they have accidentally been deleted. It does not do the same -for *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 *tracked* files to work-in-progress references after or -before certain actions. See [[*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 ~magit-no-confirm~ (see [[*Completion and -Confirmation]]). If you enable the various wip modes then you should -add ~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 ~magit-delete-by-moving-to-trash~ -controls whether the system trash is used, which is the case by default. -Nevertheless, ~trash~ isn't a member of ~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 [[*Risk of Reverting -Automatically]]. - -*** Performance - -After Magit has run ~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. - -#+begin_src emacs-lisp - (setq magit-refresh-status-buffer nil) -#+end_src - -You should also check whether any third-party packages have added -anything to ~magit-refresh-buffer-hook~, ~magit-pre-refresh-hook~, and -~magit-post-refresh-hook~. If so, then check whether those additions -impact performance significantly. - -Magit can be told to refresh buffers verbosely using ~M-x -magit-toggle-verbose-refresh~. Enabling this helps figuring out which -sections are bottlenecks. Each line printed to the ~*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 ~auto-revert-mode~ from the built-in library -~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. - -#+begin_src emacs-lisp - (setq auto-revert-buffer-list-filter - 'magit-auto-revert-repository-buffer-p) -#+end_src - -For alternative approaches see [[*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 -[[*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 -~magit-insert-tags-headers~, as explained at the mentioned node. - -**** Log Performance -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -When showing logs, Magit limits the number of commits initially shown -in the hope that this avoids unnecessary work. When ~--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 (https://www.spinics.net/lists/git/msg232230.html): "~--graph~ wants -to compute the whole history and the max-count only affects the output -phase after ~--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 ~-<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 -~--graph~ can slow things down. - -Using ~--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 ~--color~ is not enabled by default anymore. -Consider leaving it at that. - -**** Diff Performance -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -If diffs are slow, then consider turning off some optional diff -features by setting all or some of the following variables to ~nil~: -~magit-diff-highlight-indentation~, ~magit-diff-highlight-trailing~, -~magit-diff-paint-whitespace~, ~magit-diff-highlight-hunk-body~, and -~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 ~magit-revision-mode~ takes considerably more time than -looking at the same commit in ~magit-diff-mode~, then consider setting -~magit-revision-insert-related-refs~ to ~nil~. - -When you are often confronted with diffs that contain deleted files, -then you might want to enable the ~--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 [[info:transient#Enabling and Disabling -Suffixes]]. Once you have done that you should enable it and save that -setting, see [[info:transient#Saving Values]]. You should do this in both -the diff (~d~) and the diff refresh (~D~) transient popups. - -**** Refs Buffer Performance -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -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: - -#+begin_src emacs-lisp - (remove-hook 'magit-refs-sections-hook 'magit-insert-tags) -#+end_src - -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 ~f-pa~. - -**** Committing Performance -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -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: - -#+begin_src emacs-lisp - (remove-hook 'server-switch-hook 'magit-commit-diff) - (remove-hook 'with-editor-filter-visit-hook 'magit-commit-diff) -#+end_src - -Then you can type ~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 ~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. - -**** Microsoft Windows Performance - -In order to update the status buffer, ~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. - -#+begin_src shell-script - 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_src - -You should also check whether an anti-virus program is affecting -performance. - -**** MacOS Performance - -Before Emacs 26.1 child processes were created using ~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 ~git~ processes that made quite a -difference. - -So make sure that you are using at least Emacs 26.1, in which case the -faster ~vfork~ will be used. (The creation of child processes still -takes about twice as long on Darwin compared to Linux.) See [fn:mac1] -for more information. - -Additionally, ~git~ installed from a package manager like ~brew~ or ~nix~ -seems to be slower than the native executable. Profile the ~git~ -executable you're running against the one at ~/usr/bin/git~, and if -you notice a notable difference try using the latter as -~magit-git-executable~. - -[fn:mac1] https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html - -*** Global Bindings - -- User Option: 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. - - - 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 (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 - is evaluated (this differs from ~custom-set-variables~, which - doesn't load the libraries that define the customized variables). - - Setting this variable has no effect if ~after-init-hook~ has - already been run. - -* 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 [[info:with-editor]] for -information about ~with-editor~. ~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 -https://github.com/magit/magit/wiki/Plugin-Dispatch-Key-Registry. - -** Calling Git - -Magit provides many specialized functions for calling Git. All of -these functions are defined in either ~magit-git.el~ or ~magit-process.el~ -and have one of the prefixes ~magit-run-~, ~magit-call-~, ~magit-start-~, -or ~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 ~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. - -*** 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. - -- Function: magit-git-exit-code &rest args :: - - Executes git with ARGS and returns its exit code. - -- Function: magit-git-success &rest args :: - - Executes git with ARGS and returns ~t~ if the exit code is ~0~, ~nil~ - otherwise. - -- Function: magit-git-failure &rest args :: - - Executes git with ARGS and returns ~t~ if the exit code is ~1~, ~nil~ - otherwise. - -- Function: magit-git-true &rest args :: - - Executes git with ARGS and returns ~t~ if the first line printed by - git is the string "true", ~nil~ otherwise. - -- Function: magit-git-false &rest args :: - - Executes git with ARGS and returns ~t~ if the first line printed by - git is the string "false", ~nil~ otherwise. - -- Function: magit-git-insert &rest args :: - - Executes git with ARGS and inserts its output at point. - -- Function: 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 ~nil~. - -- Function: 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. - -- Function: 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 ~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. - -- Function: 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 - ~call-process~, except that file handlers are supported. Enables - Cygwin's "noglob" option during the call and ensures unix eol - conversion. - -- Function: magit-process-file process &optional infile buffer display &rest args :: - - Processes files synchronously in a separate process. Identical to - ~process-file~ but temporarily enables Cygwin's "noglob" option during - the call and ensures unix eol conversion. - -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. - -- User Option: magit-git-debug :: - - Whether to report errors that occur when using ~magit-git-insert~, - ~magit-git-string~, ~magit-git-lines~, or ~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. - -- Function: magit-git-str &rest args :: - - This is a variant of ~magit-git-string~ that ignores the option - ~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. - -*** 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 ~$~ from a Magit buffer or ~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. - -The synchronous functions return the exit code, while the asynchronous -functions return the process object. - -- Function: magit-call-git &rest args :: - - Calls git synchronously with ARGS. - -- Function: magit-call-process program &rest args :: - - Calls PROGRAM synchronously with ARGS. - -- Function: magit-run-git &rest args :: - - Calls git synchronously with ARGS and then refreshes. - -- Function: 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 ~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. - -- Function: magit-git &rest args :: - - Calls git synchronously with ARGS for side-effects only. This - function does not refresh the buffer. - -- Function: 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 - ~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. - -And now for the asynchronous variants. - -- Function: 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 ~magit-revert-buffers~ is non-~nil~. - -- Function: magit-run-git-with-editor &rest args :: - - Export GIT_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. - -- Function: 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 ~magit-git-executable~ specifies the Git executable and option - ~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 ~magit-revert-buffers~ is non-~nil~. - -- Function: 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 ~start-file-process~ and then setup to - use the sentinel ~magit-process-sentinel~ and the filter - ~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, ~magit-process-sentinel~ refreshes the - buffer that was current when ~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 ~magit-revert-buffers~ is - non-~nil~. - -- Variable: magit-this-process :: - - The child process which is about to start. This can be used to - change the filter and sentinel. - -- Variable: magit-process-raise-error :: - - When this is non-~nil~, then ~magit-process-sentinel~ raises an error if - git exits with a non-zero exit status. For debugging purposes. - -** Section Plumbing -*** Creating Sections - -- Macro: 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 ~magit-TYPE-section-map~ exists, then use that as the - text-property ~keymap~ of all text belonging to the section (but this - may be overwritten in subsections). TYPE can also have the form - ~(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 - ~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 ~start~ of the section object is set to - the value of ~point~ and after BODY was evaluated its ~end~ is set to - the new value of ~point~; BODY is responsible for moving ~point~ - forward. - - If it turns out inside BODY that the section is empty, then - ~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. - -- Function: magit-insert-heading &rest args :: - - Insert the heading for the section currently being inserted. - - This function should only be used inside ~magit-insert-section~. - - When called without any arguments, then just set the ~content~ slot of - the object representing the section being inserted to a marker at - ~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 ~face~ property is set anywhere inside any of - these strings, then insert all of them unchanged. Otherwise use the - ~magit-section-heading~ face for all inserted text. - - The ~content~ property of the section struct is the end of the heading - (which lasts from ~start~ to ~content~) and the beginning of the body - (which lasts from ~content~ to ~end~). If the value of ~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. - -- Function: magit-cancel-section :: - - Cancel the section currently being inserted. This exits the - innermost call to ~magit-insert-section~ and removes all traces of - what has already happened inside that call. - -- Function: 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. - -*** Section Selection - -- Function: magit-current-section :: - - Return the section at point. - -- Function: 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 ~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 ~magit-section-match~ for the - forms CONDITION can take. - -- Function: 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 - ~magit-region-sections~ (which see). - -*** Matching Sections - -- Key: M-x magit-describe-section-briefly :: - - Show information about the section at point. This command is - intended for debugging purposes. - -- Function: magit-section-ident section :: - - Return an unique identifier for SECTION. The return value has the - form ~((TYPE . VALUE)...)~. - -- Function: magit-get-section ident &optional root :: - - Return the section identified by IDENT. IDENT has to be a list as - returned by ~magit-section-ident~. - -- Function: magit-section-match condition &optional section :: - - Return ~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 - ~nil~. - - CONDITION can take the following forms: - - ~(CONDITION...)~ - - matches if any of the CONDITIONs matches. - - - ~[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. - - - ~[* CLASS...]~ - - matches sections that match ~[CLASS...]~ and - also recursively all their child sections. - - - ~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. - - Each CLASS should be a class symbol, identifying a class that - derives from ~magit-section~. For backward compatibility CLASS - can also be a "type symbol". A section matches such a symbol - if the value of its ~type~ slot is ~eq~. If a type symbol has - an entry in ~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 ~magit-describe-section-briefly~, unless - of course you want to be that precise. - -- Function: 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 ~magit-section-match~ for the forms CONDITION can take. - -- Function: magit-section-case &rest clauses :: - - Choose among clauses on the type of the section at point. - - Each clause looks like (CONDITION BODY...). 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 ~it~ is bound to the - section at point. If no clause succeeds or if there is no - section at point return ~nil~. - - See ~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. - -- Variable: 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 - ~magit-insert-section~ and you should never modify it. - -For diff related sections a few additional tools exist. - -- Function: magit-diff-type &optional section :: - - Return the diff type of SECTION. - - The returned type is one of the symbols ~staged~, ~unstaged~, ~committed~, - or ~undefined~. This type serves a similar purpose as the general - type common to all sections (which is stored in the ~type~ slot of the - corresponding ~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 ~tracked~ and ~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 ~diff~ or ~hunk~ section, or a section whose - children are of type ~diff~. If optional SECTION is ~nil~, return the - diff type for the current section. In buffers whose major mode is - ~magit-diff-mode~ SECTION is ignored and the type is determined using - other means. In ~magit-revision-mode~ buffers the type is always - ~committed~. - -- Function: 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 ~region~, ~hunk~, ~hunks~, ~file~, ~files~, or ~list~. Do not - confuse this with the diff "type", as returned by ~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., ~hunks~ or ~files~. If SECTION (or if the current section that - is ~nil~) is a ~hunk~ section and the region starts and ends inside - the body of a that section, then the type is ~region~. - - If optional STRICT is non-~nil~ then return ~nil~ if the diff type of - the section at point is ~untracked~ or the section at point is not - actually a ~diff~ but a ~diffstat~ 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 ~magit-mode-setup~. -Among other things, that function sets the buffer local values of -~default-directory~ (to the top-level of the repository), -~magit-refresh-function~, and ~magit-refresh-args~. - -Buffers are refreshed by calling the function that is the local value -of ~magit-refresh-function~ (a function named ~magit-*-refresh-buffer~, -where ~*~ may be something like ~diff~) with the value of -~magit-refresh-args~ as arguments. - -- Macro: 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 - ~magit-mode-display-buffer~ with BUFFER, MODE and SWITCH-FUNC as - arguments. Then it sets the local value of ~magit-refresh-function~ - to REFRESH-FUNC and that of ~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. - -- Function: 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 ~magit-mode-bury-buffer~. - - The buffer is displayed and selected using SWITCH-FUNCTION. If that - is ~nil~ then ~pop-to-buffer~ is used if the current buffer's major mode - derives from ~magit-mode~. Otherwise ~switch-to-buffer~ is used. - -- Variable: magit-refresh-function :: - - The value of this buffer-local variable is the function used to - refresh the current buffer. It is called with ~magit-refresh-args~ as - arguments. - -- Variable: magit-refresh-args :: - - The list of arguments used by ~magit-refresh-function~ to refresh the - current buffer. ~magit-refresh-function~ is called with these - arguments. - - The value is usually set using ~magit-mode-setup~, but in some cases - it's also useful to provide commands that can change the value. For - example, the ~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 ~magit-diff-more-context~, - ~magit-diff-less-context~ and ~magit-diff-default-context~ change just - the ~-U<N>~ argument. In both case this is done by changing the value - of this variable and then calling this ~magit-refresh-function~. - -** Conventions - -Also see [[*Completion and Confirmation]]. - -*** 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 ~magit-branch-current~ accordingly. By default -it looks mostly like ~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 ~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 ~region~ face right to be -a good indicator for the general quality of a theme. My -recommendation for the ~region~ face is this: use a background color -slightly different from the background color of the ~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 -~default~ and a somewhat darker gray for the background of ~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 ~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., ~kill-region~. - -So using the regular ~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, ~magit-section-highlight~ -is used for both the body and the heading. Like the ~region~ face, it -should only set the background color to something similar to that of -~default~. The highlight background color must be different from both -the ~region~ background color and the ~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 ~magit-diff-hunk-heading~, should be different -from both ~magit-diff-hunk-heading-highlight~ and -~magit-section-highlight~, as well as from ~magit-diff-context~ and -~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 ~magit-diff-file-heading-selection~ or -~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 -~magit-diff-refine-hunk~ to ~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 ~magit-diff-highlight-indentation~, -~magit-diff-highlight-trailing~, and ~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: -~magit-diff-added~, ~magit-diff-added-highlight~, and -~diff-refined-added~. Make sure that the latter works well with both -of the former, as well as ~smerge-other~ and ~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 ~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. - -* FAQ -:PROPERTIES: -:APPENDIX: t -:END: - -The next two nodes lists frequently asked questions. For a list of -frequently *and recently* asked questions, i.e., questions that haven't -made it into the manual yet, see -https://github.com/magit/magit/wiki/FAQ. - -Please also see [[*Debugging Tools]]. - -** FAQ - How to ...? -*** How to pronounce Magit? - -Either ~mu[m's] git~ or ~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; ~Mag{ie => it}~. - -You can also choose to use the former pronunciation just because you -like it better. - -Also see https://magit.vc/assets/videos/magic.mp4. -Also see https://emacs.stackexchange.com/questions/13696. - -*** How to show git's output? - -To show the output of recently run git commands, press ~$~ (or, if that -isn't available, use ~M-x magit-process-buffer~). This shows a buffer -containing a section per git invocation; as always press ~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, using ~M-x -magit-toggle-git-debug~. - -*** How to install the gitman info manual? - -Git's manpages can be exported as an info manual called ~gitman~. -Magit's own info manual links to nodes in that manual instead of the -actual manpages, simply because Info doesn't support linking to -manpages. - -Unfortunately some distributions do not install the ~gitman~ manual by -default and you would have to install a separate documentation package -to get it. - -Magit patches info, adding the ability to visit links to the ~gitman~ -info manual, by instead viewing the respective manpage. If you prefer -that approach, then set the value of ~magit-view-git-manual-method~ to -one of the supported Emacs packages ~man~ or ~woman~, e.g.: - -#+begin_src emacs-lisp - (setq magit-view-git-manual-method 'man) -#+end_src - -*** 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. - -#+begin_src shell-script - git config --global diff.gpg.textconv "gpg --no-tty --decrypt" - echo "*.gpg filter=gpg diff=gpg" > .gitattributes -#+end_src - -*** How does branching and pushing work? - -Please see [[*Branching]] and https://emacsair.me/2016/01/18/magit-2.4 - -*** 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 ~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 ~vc-handled-backends~. - -** FAQ - Issues and Errors -*** Magit is slow - -See [[*Performance]] and [[*I changed several thousand files at once and -now Magit is unusable]]. - -*** 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 [[*Performance]]. - -*** I am having problems committing - -That likely means that Magit is having problems finding an appropriate -~emacsclient~ executable. See [[info:with-editor#Configuring With-Editor]] -and [[info:with-editor#Debugging]]. - -*** 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 -https://github.com/magit/magit/wiki/Pushing-with-Magit-from-Windows. - -*** 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 -https://github.com/purcell/exec-path-from-shell. By default it -synchronizes ~$PATH~, which helps Magit find the same ~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 ~$GPG_AGENT_INFO~. - -*** Expanding a file to show the diff causes it to disappear - -This is probably caused by a customization of a ~diff.*~ Git variable. -You probably set that variable for a reason, and should therefore only -undo that setting in Magit by customizing ~magit-git-global-arguments~. - -*** Point is wrong in the ~COMMIT_EDITMSG~ buffer - -Neither Magit nor ~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. ~saveplace~, -~pointback~, and ~session~ are likely candidates. These snippets might -help: - -#+begin_src emacs-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_src - -*** 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 ~Git-master~. -The built-in "Version Control" package, also known as "VC", updates -that information, and can be told to do so more often: - -#+begin_src emacs-lisp - (setq auto-revert-check-vc-info t) -#+end_src - -But doing so isn't good for performance. For more (overly optimistic) -information see [[info:emacs#VC Mode Line]]. - -If you don't really care about seeing this information in the -mode-line, but just don't want to see /incorrect/ information, -then consider simply not displaying it in the mode-line: - -#+begin_src emacs-lisp - (setq-default mode-line-format - (delete '(vc-mode vc-mode) mode-line-format)) -#+end_src - -*** 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. - -*** My Git hooks work on the command-line but not inside Magit - -When Magit calls ~git~ it adds a few global arguments including -~--literal-pathspecs~ and the ~git~ process started by Magit then passes -that setting on to other ~git~ process it starts itself. It does so by -setting the environment variable ~GIT_LITERAL_PATHSPECS~, not by calling -subprocesses with the ~--literal-pathspecs~ argument. You can therefore -override this setting in hook scripts using ~unset -GIT_LITERAL_PATHSPECS~. - -*** ~git-commit-mode~ isn't used when committing from the command-line - -The reason for this is that ~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 ~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 ~init.el~ file should contain: - -#+begin_src emacs-lisp - (require 'git-commit) - (server-mode) -#+end_src - -Instead of `(require 'git-commit)` you may also use: - -#+begin_src emacs-lisp - (load "/path/to/magit-autoloads.el") -#+end_src - -You might want to do that because loading ~git-commit~ causes large -parts of Magit to be loaded. - -There are also some variations of ~(server-mode)~ that you might want to -try. Personally I use: - -#+begin_src emacs-lisp - (use-package server - :config (or (server-running-p) (server-mode))) -#+end_src - -Now you can use: - -#+begin_src shell-script - $ emacs& - $ EDITOR=emacsclient git commit -#+end_src - -However you cannot use: - -#+begin_src shell-script - $ killall emacs - $ EDITOR="emacsclient --alternate-editor emacs" git commit -#+end_src - -This will actually end up using ~emacs~, not ~emacsclient~. If you do -this, then you can still edit the commit message but ~git-commit-mode~ -won't be used and you have to exit ~emacs~ to finish the process. - -Tautology ahead. If you want to be able to use ~emacsclient~ to connect -to a running ~emacs~ instance, even though no ~emacs~ instance is running, -then you cannot use ~emacsclient~ directly. - -Instead you have to create a script that does something like this: - -Try to use ~emacsclient~ (without using ~--alternate-editor~). If that -succeeds, do nothing else. Otherwise start ~emacs &~ (and ~init.el~ must -call ~server-start~) and try to use ~emacsclient~ again. - -*** Point ends up inside invisible text when jumping to a file-visiting buffer - -This can happen when you type ~RET~ on a hunk to visit the respective -file at the respective position. One solution to this problem is to -use ~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 ~magit-diff-visit-file-hook~ to reveal the text, possibly -using ~reveal-post-command~ or for Org buffers ~org-reveal~. - -*** 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 ~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 ~C-x C-s~ instead; the ~C-x~ prefix has other options as well when -using Transient, which will be displayed when it is typed. See -https://docs.magit.vc/transient/Saving-Values.html#Saving-Values for -more details. - -* 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. - -- Key: M-x 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. - -- Key: M-x 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 ~emacs~ with only ~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 ~make emacs-Q~ instead of the output of this command. - -- Key: M-x 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 ~$~. - - When git's output is consumed in some way, then it would be too - expensive to also insert it into this buffer, but with this command - that can be enabled temporarily. In that case, if git returns with - a non-zero exit status, then at least its standard error is inserted - into this buffer. - - Also note that just because git exits with a non-zero 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. - -- Key: M-x 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 ~*Messages*~ buffer. - -- Key: M-x magit-toggle-subprocess-record :: - - This command toggles whether subprocess invocations are recorded. - - When enabled, all subprocesses started by ~magit-process-file~ are - logged into the buffer specified by ~magit-process-record-buffer-name~ - using the format ~magit-process-record-entry-format~. This is for - debugging purposes. - - This is in addition to and distinct from the default logging done by - default, and additional logging enabled with ~magit-toggle-git-debug~. - -- Key: M-x magit-debug-git-executable :: - - This command displays a buffer containing information about the - available and used ~git~ executable(s), and can be useful when - investigating ~exec-path~ issues. - - Also see [[*Git Executable]]. - -- Key: M-x magit-profile-refresh-buffer :: - - This command profiles refreshing the current Magit buffer and then - displays the results. - -- Key: M-x magit-toggle-profiling :: - - This command starts profiling Magit and Forge, or if profiling is - already in progress, it instead stops that and displays the results. - -- Key: M-x with-editor-debug :: - - This command displays a buffer containing information about the - available and used ~emacsclient~ executable(s), and can be useful - when investigating why Magit (or rather ~with-editor~) cannot find - an appropriate ~emacsclient~ executable. - - Also see [[info:with-editor#Debugging]]. - -#+texinfo: @noindent -Please also see [[*FAQ]]. - -* Keystroke Index -:PROPERTIES: -:APPENDIX: t -:INDEX: ky -:COOKIE_DATA: recursive -:END: -* Function and Command Index -:PROPERTIES: -:APPENDIX: t -:INDEX: fn -:END: -* Variable Index -:PROPERTIES: -:APPENDIX: t -:INDEX: vr -:END: - -* Copying -:PROPERTIES: -:COPYING: t -:END: - -#+begin_quote -Copyright (C) 2015-{{{year}}} 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_quote - -# LocalWords: ARG ARGS CONDITIONs ChangeLog DNS Dired Ediff Ediffing -# LocalWords: Elpa Emacsclient FUNC Flyspell Git Git's Gitk HOOK's -# LocalWords: IDENT Junio LocalWords Magit Magit's Magitian Magitians -# LocalWords: Melpa Propertize REF REF's RET Reflog SPC SYM Spacemacs -# LocalWords: Submodules TODO TYPEs Theming Unpulled Unpushed Unstaged -# LocalWords: Untracked WORKTREE Wip ack args async autoloads autosaving -# LocalWords: autosquash backport basename branchref builtin -# LocalWords: cdr changelog committer config customizable diff's diffstat -# LocalWords: dwim ediff ediffing editmsg emacsclient filename fixup -# LocalWords: flyspell func git's gitk gitman gitmodule gitmodules goto -# LocalWords: gpg gui ident init inserter inserters keymap keymaps -# LocalWords: logfile magit maildir manpage manpages minibuffer multi mv -# LocalWords: namespace newbase nocommit notesRef posix prev -# LocalWords: propertize rebase rebased rebasing reflog repo signoff str -# LocalWords: struct subcommand submodule submodule's submodules subprocess -# LocalWords: sym texinfo theming todo topdir un unhighlighted unpulled -# LocalWords: unpushed unstage unstaged unstages unstaging untracked url -# LocalWords: versa whitespace wip workflow worktree wtree -# LocalWords: backported macOS - -# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. -# Local Variables: -# eval: (require 'magit-base nil t) -# eval: (require 'ol-man nil t) -# indent-tabs-mode: nil -# org-src-preserve-indentation: nil -# End: |