diff options
Diffstat (limited to 'configs/shared/emacs/.emacs.d/elpa/magit-20180913.1247/magit.info-1')
| -rw-r--r-- | configs/shared/emacs/.emacs.d/elpa/magit-20180913.1247/magit.info-1 | 7899 |
1 files changed, 0 insertions, 7899 deletions
diff --git a/configs/shared/emacs/.emacs.d/elpa/magit-20180913.1247/magit.info-1 b/configs/shared/emacs/.emacs.d/elpa/magit-20180913.1247/magit.info-1 deleted file mode 100644 index 4699ff7ca8..0000000000 --- a/configs/shared/emacs/.emacs.d/elpa/magit-20180913.1247/magit.info-1 +++ /dev/null @@ -1,7899 +0,0 @@ -This is magit.info, produced by makeinfo version 6.5 from magit.texi. - - Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li> - - 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. -INFO-DIR-SECTION Emacs -START-INFO-DIR-ENTRY -* Magit: (magit). Using Git from Emacs with Magit. -END-INFO-DIR-ENTRY - - -File: magit.info, Node: Top, Next: Introduction, Up: (dir) - -Magit User Manual -***************** - -Magit is an interface to the version control system Git, implemented as -an Emacs package. Magit aspires to be a complete Git porcelain. While -we cannot (yet) claim that Magit wraps and improves upon each and every -Git command, it is complete enough to allow even experienced Git users -to perform almost all of their daily version control tasks directly from -within Emacs. While many fine Git clients exist, only Magit and Git -itself deserve to be called porcelains. - -This manual is for Magit version 2.13.0 (2.13.0-201-g865c5bdac+1). - - Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li> - - 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. - -* Menu: - -* Introduction:: -* Installation:: -* Getting Started:: -* Interface Concepts:: -* Inspecting:: -* Manipulating:: -* Transferring:: -* Miscellaneous:: -* Customizing:: -* Plumbing:: -* FAQ:: -* Debugging Tools:: -* Keystroke Index:: -* Command Index:: -* Function Index:: -* Variable Index:: - -— The Detailed Node Listing — - -Installation - -* Installing from an Elpa Archive:: -* Installing from the Git Repository:: -* Post-Installation Tasks:: - -Interface Concepts - -* Modes and Buffers:: -* Sections:: -* Popup Buffers and Prefix Commands:: -* Completion, Confirmation and the Selection: Completion Confirmation and the Selection. -* Running Git:: - -Modes and Buffers - -* Switching Buffers:: -* Naming Buffers:: -* Quitting Windows:: -* Automatic Refreshing of Magit Buffers:: -* Automatic Saving of File-Visiting Buffers:: -* Automatic Reverting of File-Visiting Buffers:: - - -Sections - -* Section Movement:: -* Section Visibility:: -* Section Hooks:: -* Section Types and Values:: -* Section Options:: - - -Completion, Confirmation and the Selection - -* Action Confirmation:: -* Completion and Confirmation:: -* The Selection:: -* The hunk-internal region:: -* Support for Completion Frameworks:: -* Additional Completion Options:: - - -Running Git - -* Viewing Git Output:: -* Git Process Status:: -* Running Git Manually:: -* Git Executable:: -* Global Git Arguments:: - - -Inspecting - -* Status Buffer:: -* Repository List:: -* Logging:: -* Diffing:: -* Ediffing:: -* References Buffer:: -* Bisecting:: -* Visiting Blobs:: -* Blaming:: - -Status Buffer - -* Status Sections:: -* Status Header Sections:: -* Status Module Sections:: -* Status Options:: - - -Logging - -* Refreshing Logs:: -* Log Buffer:: -* Log Margin:: -* Select from Log:: -* Reflog:: -* Cherries:: - - -Diffing - -* Refreshing Diffs:: -* Diff Buffer:: -* Diff Options:: -* Revision Buffer:: - - -References Buffer - -* References Sections:: - - -Manipulating - -* Repository Setup:: -* Staging and Unstaging:: -* Applying:: -* Committing:: -* Branching:: -* Merging:: -* Resolving Conflicts:: -* Rebasing:: -* Cherry Picking:: -* Resetting:: -* Stashing:: - -Staging and Unstaging - -* Staging from File-Visiting Buffers:: - - -Committing - -* Initiating a Commit:: -* Editing Commit Messages:: - - -Branching - -* The Two Remotes:: -* The Branch Popup:: -* The Branch Config Popup:: -* Auxillary Branch Commands:: - - -Rebasing - -* Editing Rebase Sequences:: -* Information About In-Progress Rebase:: - - -Cherry Picking - -* Reverting:: - - -Transferring - -* Remotes:: -* Fetching:: -* Pulling:: -* Pushing:: -* Creating and Sending Patches:: -* Applying Patches:: - -Remotes - -* The Remote Popup:: -* The Remote Config Popup:: - - -Miscellaneous - -* Tagging:: -* Notes:: -* Submodules:: -* Subtree:: -* Worktree:: -* Common Commands:: -* Wip Modes:: -* Minor Mode for Buffers Visiting Files:: -* Minor Mode for Buffers Visiting Blobs:: - -Submodules - -* Listing Submodules:: -* Submodule Popup:: - - -Customizing - -* Per-Repository Configuration:: -* Essential Settings:: - -Essential Settings - -* Safety:: -* Performance:: - - -Plumbing - -* Calling Git:: -* Section Plumbing:: -* Refreshing Buffers:: -* Conventions:: - -Calling Git - -* Getting a Value from Git:: -* Calling Git for Effect:: - - -Section Plumbing - -* Creating Sections:: -* Section Selection:: -* Matching Sections:: - - -Conventions - -* Theming Faces:: - - -FAQ - -* FAQ - How to ...?:: -* FAQ - Issues and Errors:: - -FAQ - How to ...? - -* How to show git's output?:: -* How to install the gitman info manual?:: -* How to show diffs for gpg-encrypted files?:: -* How does branching and pushing work?:: -* Can Magit be used as ediff-version-control-package?:: - - -FAQ - Issues and Errors - -* Magit is slow:: -* I changed several thousand files at once and now Magit is unusable:: -* I am having problems committing:: -* I am using MS Windows and cannot push with Magit:: -* I am using OS X and SOMETHING works in shell, but not in Magit: I am using OS X and SOMETHING works in shell but not in Magit. -* Diffs contain control sequences:: -* Expanding a file to show the diff causes it to disappear:: -* Point is wrong in the COMMIT_EDITMSG buffer:: -* The mode-line information isn't always up-to-date:: -* A branch and tag sharing the same name breaks SOMETHING:: -* My Git hooks work on the command-line but not inside Magit:: -* git-commit-mode isn't used when committing from the command-line:: -* Point ends up inside invisible text when jumping to a file-visiting buffer:: - - - - -File: magit.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top - -1 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 Evil (https://bitbucket.org/lyro/evil/wiki/Home), the -"Extensible VI Layer for Emacs", and Spacemacs -(https://github.com/syl20bnr/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. - - -File: magit.info, Node: Installation, Next: Getting Started, Prev: Introduction, Up: Top - -2 Installation -************** - -Magit can be installed using Emacs’ package manager or manually from its -development repository. - -* Menu: - -* Installing from an Elpa Archive:: -* Installing from the Git Repository:: -* Post-Installation Tasks:: - - -File: magit.info, Node: Installing from an Elpa Archive, Next: Installing from the Git Repository, Up: Installation - -2.1 Installing from an Elpa Archive -=================================== - -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 -*note (emacs)Packages::. Then add one of the archives to -‘package-archives’: - - • To use Melpa: - - (require 'package) - (add-to-list 'package-archives - '("melpa" . "http://melpa.org/packages/") t) - - • To use Melpa-Stable: - - (require 'package) - (add-to-list 'package-archives - '("melpa-stable" . "http://stable.melpa.org/packages/") t) - - Once you have added your preferred archive, you need to update the -local package list using: - - M-x package-refresh-contents RET - - Once you have done that, you can install Magit and its dependencies -using: - - M-x package-install RET magit RET - - Now see *note Post-Installation Tasks::. - - -File: magit.info, Node: Installing from the Git Repository, Next: Post-Installation Tasks, Prev: Installing from an Elpa Archive, Up: Installation - -2.2 Installing from the Git Repository -====================================== - -Magit depends on the ‘dash’, ‘magit-popup’, ‘ghub’ 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 development repository. - - (An ancient release of Magit is also available from Marmalade, but no -new versions will be uploaded. Marmalade is unmaintained — its -maintainer has stopped responding to support requests from package -authors or even just to create new accounts so that new authors can -upload their packages in the first place.) - - Then clone the Magit repository: - - $ git clone https://github.com/magit/magit.git ~/.emacs.d/site-lisp/magit - $ cd ~/.emacs.d/site-lisp/magit - - Then compile the libraries and generate the info manuals: - - $ make - - If you haven’t installed ‘dash’, ‘magit-popup’, ‘ghub’ 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’: - - LOAD_PATH = -L /path/to/magit/lisp - LOAD_PATH += -L /path/to/dash - LOAD_PATH += -L /path/to/magit-popup - LOAD_PATH += -L /path/to/ghub - LOAD_PATH += -L /path/to/with-editor - - Finally add this to your init file: - - (add-to-list 'load-path "~/.emacs.d/site-lisp/magit/lisp") - (require 'magit) - - (with-eval-after-load 'info - (info-initialize) - (add-to-list 'Info-directory-list - "~/.emacs.d/site-lisp/magit/Documentation/")) - - 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’. - - (load "/path/to/magit/lisp/magit-autoloads") - - 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: - - $ git pull - $ make - - At times it might be necessary to run ‘make clean all’ instead. - - To view all available targets use ‘make help’. - - Now see *note Post-Installation Tasks::. - - -File: magit.info, Node: Post-Installation Tasks, Prev: Installing from the Git Repository, Up: Installation - -2.3 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’. - - M-x magit-version RET - - should display something like - - Magit 2.8.0, Git 2.10.2, Emacs 25.1.1, gnu/linux - - Then you might also want to read about options that many users likely -want to customize. See *note 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 *note How to install the gitman info manual?::. - - If you are completely new to Magit then see *note Getting Started::. - - If you run into problems, then please see the *note FAQ::. Also see -the *note 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/donations>. -for various donation options. - - -File: magit.info, Node: Getting Started, Next: Interface Concepts, Prev: Installation, Up: Top - -3 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. - - To display information about the current Git repository, type ‘M-x -magit-status RET’. You will be using this command a lot, and should -therefore give it a global key binding. This is what we recommend: - - (global-set-key (kbd "C-x g") 'magit-status) - - 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 -not 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 committing popup buffer featuring various commit variants and -arguments that can be passed to ‘git commit’. Do not worry about those -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 committed. -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 bring up the push popup 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, push, and log popups. These are -probably among the popups you will be using the most, but many others -exist. To show a popup that lists all other popups (as well as the -various apply commands and some other fundamental commands), type ‘h’. -Try a few. - - The key bindings in that popup 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 popup, but once you remember that "d" -stands for "diff", you would usually do so by just typing ‘d’. But the -"popup of popups" is useful even once you have memorized all the -bindings, as it can provide easy access to Magit commands from non-Magit -buffers. You should create a global key binding for this command too: - - (global-set-key (kbd "C-x M-g") 'magit-dispatch-popup) - - In the same vein, you might also want to enable -‘global-magit-file-mode’ to get some more Magit key bindings in regular -file-visiting buffers (see *note Minor Mode for Buffers Visiting -Files::). - - 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. - - -File: magit.info, Node: Interface Concepts, Next: Inspecting, Prev: Getting Started, Up: Top - -4 Interface Concepts -******************** - -* Menu: - -* Modes and Buffers:: -* Sections:: -* Popup Buffers and Prefix Commands:: -* Completion, Confirmation and the Selection: Completion Confirmation and the Selection. -* Running Git:: - - -File: magit.info, Node: Modes and Buffers, Next: Sections, Up: Interface Concepts - -4.1 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*. Its 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’. - -‘M-x magit-toggle-buffer-lock’ (‘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. - -* Menu: - -* Switching Buffers:: -* Naming Buffers:: -* Quitting Windows:: -* Automatic Refreshing of Magit Buffers:: -* Automatic Saving of File-Visiting Buffers:: -* Automatic Reverting of File-Visiting Buffers:: - - -File: magit.info, Node: Switching Buffers, Next: Naming Buffers, Up: Modes and Buffers - -4.1.1 Switching Buffers ------------------------ - - -- Function: magit-display-buffer buffer - - 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. - - -- 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 *note (elisp)Choosing a Window - for Display::. - - -- 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. - - -File: magit.info, Node: Naming Buffers, Next: Quitting Windows, Prev: Switching Buffers, Up: Modes and Buffers - -4.1.2 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. - - • ‘%T’ - - Obsolete, use "%t%x" instead. Like ‘%t’, but append an - asterisk if and only if ‘magit-uniquify-buffer-names’ is nil. - - The value should always contain ‘%m’ or ‘%M’, ‘%v’ or ‘%V’, and - ‘%t’ (or the obsolete ‘%T’). If ‘magit-uniquify-buffer-names’ is - non-nil, then the value must end with ‘%t’ or ‘%t%x’ (or the - obsolete ‘%T’). 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. - - -File: magit.info, Node: Quitting Windows, Next: Automatic Refreshing of Magit Buffers, Prev: Naming Buffers, Up: Modes and Buffers - -4.1.3 Quitting Windows ----------------------- - -‘q’ (‘magit-mode-bury-buffer’) - - This command buries the current Magit buffer. With a prefix - argument, it instead kills the 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-restore-window-configuration’. - - -- 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. - - -File: magit.info, Node: Automatic Refreshing of Magit Buffers, Next: Automatic Saving of File-Visiting Buffers, Prev: Quitting Windows, Up: Modes and Buffers - -4.1.4 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 may optionally be automatically -refreshed whenever a buffer is saved to a file inside the respective -repository. - - 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. - -‘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. - -‘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. - - -File: magit.info, Node: Automatic Saving of File-Visiting Buffers, Next: Automatic Reverting of File-Visiting Buffers, Prev: Automatic Refreshing of Magit Buffers, Up: Modes and Buffers - -4.1.5 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. - - -File: magit.info, Node: Automatic Reverting of File-Visiting Buffers, Prev: Automatic Saving of File-Visiting Buffers, Up: Modes and Buffers - -4.1.6 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 changed 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 changed 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. - - -- Command: 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 for how many seconds Emacs waits 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 redefines - ‘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-buffers-p’. - - However the default is nil, to not 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. - -* Menu: - -* Risk of Reverting Automatically:: - - -File: magit.info, Node: Risk of Reverting Automatically, Up: Automatic Reverting of File-Visiting Buffers - -Risk of Reverting Automatically -............................... - -For the vast majority 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 would 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 would 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 would -refuse to discard the changes. - - However if you do 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 only heard from 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 -crashed 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). - - -File: magit.info, Node: Sections, Next: Popup Buffers and Prefix Commands, Prev: Modes and Buffers, Up: Interface Concepts - -4.2 Sections -============ - -Magit buffers are organized into nested sections, which can be collapsed -and expanded, similar to how sections are handled in Org mode. Each -section also has a type, and some sections also have a value. For each -section type there can also be a local keymap, shared by all sections of -that type. - - Taking advantage of the section value and type, many commands operate -on the current section, or when the region is active and selects -sections of the same type, all of the selected sections. Commands that -only make sense for a particular section type (as opposed to just -behaving differently depending on the type) are usually bound in section -type keymaps. - -* Menu: - -* Section Movement:: -* Section Visibility:: -* Section Hooks:: -* Section Types and Values:: -* Section Options:: - - -File: magit.info, Node: Section Movement, Next: Section Visibility, Up: Sections - -4.2.1 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. - -‘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. - -‘n’ (‘magit-section-forward’) - - Move to the beginning of the next visible section. - -‘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. - -‘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. - -‘^’ (‘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. - - -- Variable: magit-section-movement-hook - - This hook is run by all of the above movement commands, after - arriving at the destination. - - -- 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. This function is a member of the hook’s default - value. - - -- 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. This function - is a member of the hook’s default value. - - -- 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. This function is a member of the hook’s - default value. - - -- 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-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. - - -- User Option: magit-update-other-window-delay - - Delay before automatically updating the other window. - - When moving around in certain buffers, then certain other buffers, - which are being displayed in another window, may optionally be - updated to display information about the section at point. - - When holding down a key to move by more than just one section, then - that would update that buffer for each section on the way. To - prevent that, updating the revision buffer is delayed, and this - option controls for how long. For optimal experience you might - have to adjust this delay and/or the keyboard repeat rate and delay - of your graphical environment or operating system. - - -File: magit.info, Node: Section Visibility, Next: Section Hooks, Prev: Section Movement, Up: Sections - -4.2.2 Section Visibility ------------------------- - -Magit provides many commands for changing the visibility of sections, -but all you need to get started are the next two. - -‘TAB’ (‘magit-section-toggle’) - - Toggle the visibility of the body of the current section. - -‘C-<tab>’ (‘magit-section-cycle’) - - Cycle the visibility of current section and its children. - -‘M-<tab>’ (‘magit-section-cycle-diffs’) - - Cycle the visibility of diff-related sections in the current - buffer. - -‘S-<tab>’ (‘magit-section-cycle-global’) - - Cycle the visibility of all sections in the current buffer. - -‘1’ (‘magit-section-show-level-1’) -‘2’ (‘magit-section-show-level-2’) -‘3’ (‘magit-section-show-level-3’) -‘4’ (‘magit-section-show-level-4’) - - Show sections surrounding the current section up to level N. - -‘M-1’ (‘magit-section-show-level-1-all’) -‘M-2’ (‘magit-section-show-level-2-all’) -‘M-3’ (‘magit-section-show-level-3-all’) -‘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’. - - -File: magit.info, Node: Section Hooks, Next: Section Types and Values, Prev: Section Visibility, Up: Sections - -4.2.3 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’. - - -File: magit.info, Node: Section Types and Values, Next: Section Options, Prev: Section Hooks, Up: Sections - -4.2.4 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. - -‘M-x magit-describe-section-briefly’ (‘magit-describe-section-briefly’) - - Show 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. - - -File: magit.info, Node: Section Options, Prev: Section Types and Values, Up: Sections - -4.2.5 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. - - -File: magit.info, Node: Popup Buffers and Prefix Commands, Next: Completion Confirmation and the Selection, Prev: Sections, Up: Interface Concepts - -4.3 Popup Buffers and Prefix Commands -===================================== - -Many Magit commands are implemented using *popup buffers*. First the -user invokes a *popup* or *prefix* command, which causes a popup buffer -with the available *infix* arguments and *suffix* commands to be -displayed. The user then optionally toggles/sets some arguments and -finally invokes one of the suffix commands. - - This is implemented in the library ‘magit-popup’. Earlier releases -used the library ‘magit-key-mode’. A future release will switch to a -yet-to-be-written successor, which will likely be named ‘transient’. - - Because ‘magit-popup’ can also be used by other packages without -having to depend on all of Magit, it is documented in its own manual. -See *note (magit-popup)Top::. - -‘C-c C-c’ (‘magit-dispatch-popup’) - - This popup command shows a buffer featuring all other Magit popup - commands as well as some other commands that are not popup commands - themselves. - - This command is also, or especially, useful outside Magit buffers, so -you should setup a global binding: - - (global-set-key (kbd "C-x M-g") 'magit-dispatch-popup) - - Most popups set their initial arguments according to the -corresponding ‘magit-*-arguments’ variable. Two popups, the log and -diff popups (see *note Logging:: and *note Diffing::), may behave a bit -differently, depending on the value of ‘magit-use-sticky-arguments’. - - -- User Option: magit-use-sticky-arguments - - This option controls how diff and log commands reuse arguments from - existing buffers. - - When ‘t’ (the default value), the log or diff popup reuses the - arguments from the current repository’s log or diff buffer, - respectively. When no log or diff buffer exists for the current - repository, these popups use the default value of - ‘magit-log-arguments’ or ‘magit-diff-arguments’. - - When ‘current’, log and diff popups will only reuse the arguments - if the current buffer is derived from ‘magit-log-mode’ or - ‘magit-diff-mode’, respectively. - - When ‘nil’, the default value of ‘magit-log-arguments’ or - ‘magit-diff-arguments’ is always used. - - -File: magit.info, Node: Completion Confirmation and the Selection, Next: Running Git, Prev: Popup Buffers and Prefix Commands, Up: Interface Concepts - -4.4 Completion, Confirmation and the Selection -============================================== - -* Menu: - -* Action Confirmation:: -* Completion and Confirmation:: -* The Selection:: -* The hunk-internal region:: -* Support for Completion Frameworks:: -* Additional Completion Options:: - - -File: magit.info, Node: Action Confirmation, Next: Completion and Confirmation, Up: Completion Confirmation and the Selection - -4.4.1 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-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-branch’ 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. - - • 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 popup 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: - - • ‘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. - - -File: magit.info, Node: Completion and Confirmation, Next: The Selection, Prev: Action Confirmation, Up: Completion Confirmation and the Selection - -4.4.2 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. - - -File: magit.info, Node: The Selection, Next: The hunk-internal region, Prev: Completion and Confirmation, Up: Completion Confirmation and the Selection - -4.4.3 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. - - -File: magit.info, Node: The hunk-internal region, Next: Support for Completion Frameworks, Prev: The Selection, Up: Completion Confirmation and the Selection - -4.4.4 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. - - -File: magit.info, Node: Support for Completion Frameworks, Next: Additional Completion Options, Prev: The hunk-internal region, Up: Completion Confirmation and the Selection - -4.4.5 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. - - However if you want to use Ido, then ‘ido-mode’ won’t do the trick. -You will also have to install the ‘ido-completing-read+’ package and use -‘magit-ido-completing-read’ as ‘magit-completing-read-function’. - - -- 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 - ‘completion-read’ and does some additional magit-specific work. - - -- Function: magit-ido-completing-read prompt choices &optional - predicate require-match initial-input hist def - - This function performs completion using ‘ido-completing-read+’ from - the package by the same name (which you have to explicitly install) - and does some additional magit-specific work. - - We have to use ‘ido-completing-read+’ instead of the - ‘ido-completing-read’ that comes with Ido itself, because the - latter, while intended as a drop-in replacement, cannot serve that - purpose because it violates too many of the implicit conventions. - - -- 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: - - • 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 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’. - - • ": " is appended to PROMPT. - - • PROMPT is modified to end with \" (default DEF|FALLBACK): \" - provided that DEF or FALLBACK is non-nil, that neither - ‘ivy-mode’ nor ‘helm-mode’ is enabled, and that - ‘magit-completing-read-function’ is set to its default value - of ‘magit-builtin-completing-read’. - - -File: magit.info, Node: Additional Completion Options, Prev: Support for Completion Frameworks, Up: Completion Confirmation and the Selection - -4.4.6 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"). - - -File: magit.info, Node: Running Git, Prev: Completion Confirmation and the Selection, Up: Interface Concepts - -4.5 Running Git -=============== - -* Menu: - -* Viewing Git Output:: -* Git Process Status:: -* Running Git Manually:: -* Git Executable:: -* Global Git Arguments:: - - -File: magit.info, Node: Viewing Git Output, Next: Git Process Status, Up: Running Git - -4.5.1 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’ command when things don’t go as expected. - - The output/errors for up to ‘magit-process-log-max’ Git commands are -retained. - -‘$’ (‘magit-process’) - - 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. - -‘k’ (‘magit-process-kill’) - - This command kills the process represented by the section at point. - - -- User Option: magit-git-debug - - When this is non-nil then the output of all calls to git are logged - in the process buffer. This is useful when debugging, otherwise it - just negatively affects performance. - - -File: magit.info, Node: Git Process Status, Next: Running Git Manually, Prev: Viewing Git Output, Up: Running Git - -4.5.2 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, -customize the ‘magit-process-display-mode-line-error’ user option. - - Process errors are additionally indicated at the top of the status -buffer. - - -File: magit.info, Node: Running Git Manually, Next: Git Executable, Prev: Git Process Status, Up: Running Git - -4.5.3 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. - -‘!’ (‘magit-run-popup’) - - Shows the popup buffer featuring the below suffix commands. - -‘! !’ (‘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. - -‘! p’ (‘magit-git-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. - - The string "git " is used as initial input when prompting the user - for the command. It can be removed to run another command. - -‘! 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. - -‘! 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 the above commands when reading a - shell command, shows the directory in which it will be run. - - These suffix commands start external gui tools. - -‘! k’ (‘magit-run-gitk’) - - This command runs ‘gitk’ in the current repository. - -‘! a’ (‘magit-run-gitk-all’) - - This command runs ‘gitk --all’ in the current repository. - -‘! b’ (‘magit-run-gitk-branches’) - - This command runs ‘gitk --branches’ in the current repository. - -‘! g’ (‘magit-run-git-gui’) - - This command runs ‘git gui’ in the current repository. - - -File: magit.info, Node: Git Executable, Next: Global Git Arguments, Prev: Running Git Manually, Up: Running Git - -4.5.4 Git Executable --------------------- - -Except on MS Windows, Magit defaults to running Git without specifying -the path to the git executable. Instead the first executable found by -Emacs on ‘exec-path’ is used (whose value in turn is set based on the -value of the environment variable ‘$PATH’ when Emacs was started). - - This has the advantage that it continues to work even when using -Tramp to connect to a remote machine on which the executable is found in -a different place. The downside is that if you have multiple versions -of Git installed, then you might end up using another version than the -one you think you are using. - -‘M-x magit-version’ (‘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. - - When the ‘system-type’ is ‘windows-nt’, then ‘magit-git-executable’ -is set to an absolute path when Magit is first loaded. This is -necessary because Git on that platform 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. - - If Magit doesn’t find the correct executable then you *can* work -around that by setting ‘magit-git-executable’ to an absolute path. But -note that doing so is a kludge. It is better to make sure the order in -the environment variable ‘$PATH’ is correct, and that Emacs is started -with that environment in effect. The command -‘magit-debug-git-executable’ can be useful to find out where Emacs is -searching for git. If you have to connect from Windows to a non-Windows -machine, then you must change the value to "git". - - -- User Option: magit-git-executable - - The git executable used by Magit, either the full path to the - executable or the string "git" to let Emacs find the executable - itself, using the standard mechanism for doing such things. - -‘M-x magit-debug-git-executable’ (‘magit-debug-git-executable’) - - Display a buffer with information about ‘magit-git-executable’. - - -File: magit.info, Node: Global Git Arguments, Prev: Git Executable, Up: Running Git - -4.5.5 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 *note (gitman)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. - - -File: magit.info, Node: Inspecting, Next: Manipulating, Prev: Interface Concepts, Up: Top - -5 Inspecting -************ - -The functionality provided by Magit can be roughly divided into three -groups: inspecting existing data, manipulating existing data or adding -new data, and transferring data. Of course that is a rather crude -distinction that often falls short, but it’s more useful than no -distinction at all. This section is concerned with inspecting data, the -next two with manipulating and transferring it. Then follows a section -about miscellaneous functionality, which cannot easily be fit into this -distinction. - - Of course other distinctions make sense too, e.g. Git’s distinction -between porcelain and plumbing commands, which for the most part is -equivalent to Emacs’ distinction between interactive commands and -non-interactive functions. All of the sections mentioned before are -mainly concerned with the porcelain – Magit’s plumbing layer is -described later. - -* Menu: - -* Status Buffer:: -* Repository List:: -* Logging:: -* Diffing:: -* Ediffing:: -* References Buffer:: -* Bisecting:: -* Visiting Blobs:: -* Blaming:: - - -File: magit.info, Node: Status Buffer, Next: Repository List, Up: Inspecting - -5.1 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’: - - (global-set-key (kbd "C-x g") 'magit-status) - -‘C-x g’ (‘magit-status’) - - Show the status of the current Git repository in a buffer. With a - prefix argument prompt for a repository to be shown. With two - prefix arguments prompt for an arbitrary directory. If that - directory isn’t the root of an existing repository, then offer to - initialize it as a new repository. - - -- 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. - - -- User Option: magit-repository-directories-depth - - The maximum depth to look for Git repositories. This option is - obsolete and only used for elements of the option - ‘magit-repository-directories’ (which see) that don’t specify the - depth directly. - - -- Command: ido-enter-magit-status - - From an Ido prompt used to open a file, instead drop into - ‘magit-status’. This is similar to ‘ido-magic-delete-char’, which, - despite its name, usually causes a Dired buffer to be created. - - To make this command available, use something like: - - (add-hook 'ido-setup-hook - (lambda () - (define-key ido-completion-map - (kbd \"C-x g\") 'ido-enter-magit-status))) - - Starting with Emacs 25.1 the Ido keymaps are defined just once - instead of every time Ido is invoked, so now you can modify it like - pretty much every other keymap: - - (define-key ido-common-completion-map - (kbd \"C-x g\") 'ido-enter-magit-status) - -* Menu: - -* Status Sections:: -* Status Header Sections:: -* Status Module Sections:: -* Status Options:: - - -File: magit.info, Node: Status Sections, Next: Status Header Sections, Up: Status Buffer - -5.1.1 Status Sections ---------------------- - -The contents of status buffers is controlled using the hook -‘magit-status-sections-hook’. See *note Section Hooks:: to learn about -such hooks and how to customize them. - - -- User Option: magit-status-sections-hook - - Hook run to insert sections into a status buffer. - - The first function on that hook by default is -‘magit-insert-status-headers’; it is described in the next section. By -default the following functions are also members of that hook: - - -- 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-untracked-files - - Maybe insert a list or tree of untracked files. - - Do so depending on the value of ‘status.showUntrackedFiles’. Note - that even if the value is ‘all’, Magit still initially only shows - directories. But the directory sections can then be expanded using - ‘TAB’. - - -- 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 - - 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. - - The following functions can also be added to the above hook: - - -- Function: magit-insert-tracked-files - - Insert a tree of tracked files. - - -- Function: magit-insert-ignored-files - - Insert a tree of ignored files. - - If the first element of ‘magit-diff-section-arguments’ is a - directory, then limit the list to files below that. The value of - that variable can be set using ‘D = f <DIRECTORY> RET g’. - - -- 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 - "-". - - See *note References Buffer:: for some more section inserters, which -could be used here. - - -File: magit.info, Node: Status Header Sections, Next: Status Module Sections, Prev: Status Sections, Up: Status Buffer - -5.1.2 Status Header Sections ----------------------------- - -The contents of status buffers is controlled using the hook -‘magit-status-sections-hook’ (see *note 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. - - -File: magit.info, Node: Status Module Sections, Next: Status Options, Prev: Status Header Sections, Up: Status Buffer - -5.1.3 Status Module Sections ----------------------------- - -The contents of status buffers is controlled using the hook -‘magit-status-sections-hook’ (see *note 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. - - -File: magit.info, Node: Status Options, Prev: Status Module Sections, Up: Status Buffer - -5.1.4 Status Options --------------------- - - -- User Option: magit-status-refresh-hook - - Hook run after a status buffer has been refreshed. - - -- 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 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. - - • 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-log-section-args - - Additional Git arguments used when creating log sections. Only - ‘--graph’, ‘--decorate’, and ‘--show-signature’ are supported. - This option is only a temporary kludge and will be removed. - - Note that due to an issue in Git the use of ‘--graph’ is very slow - with long histories, so you probably don’t want to add this here. - - Also see the proceeding section for more options concerning status -buffers. - - -File: magit.info, Node: Repository List, Next: Logging, Prev: Status Buffer, Up: Inspecting - -5.2 Repository List -=================== - - -- Command: magit-list-repositories - - This command displays a list of repositories in a separate buffer. - - The options ‘magit-repository-directories’ and - ‘magit-repository-directories-depth’ control 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’ and ‘:pad-right’. - - 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-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. - - -File: magit.info, Node: Logging, Next: Diffing, Prev: Repository List, Up: Inspecting - -5.3 Logging -=========== - -The status buffer contains logs for the unpushed and unpulled commits, -but that obviously isn’t enough. The prefix command ‘magit-log-popup’, -on ‘l’, features several suffix commands, which show a specific log in a -separate log buffer. - - Like other popups, the log popup also features several arguments that -can be changed before invoking one of the suffix commands. However, in -the case of the log popup, these arguments may be taken from those -currently in use in the current repository’s log buffer, depending on -the value of ‘magit-use-sticky-arguments’ (see *note Popup Buffers and -Prefix Commands::). - - For information about the various arguments, see *note -(gitman)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 popup also features several reflog commands. See *note -Reflog::. - -‘l’ (‘magit-log-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘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. - -‘l o’ (‘magit-log’) - - 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. - -‘l h’ (‘magit-log-head’) - - Show log for ‘HEAD’. - -‘l L’ (‘magit-log-branches’) - - Show log for all local branches and ‘HEAD’. - -‘l b’ (‘magit-log-all-branches’) - - Show log for all local and remote branches and ‘HEAD’. - -‘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 *note Minor Mode for -Buffers Visiting Files::. The command ‘magit-cherry’ also shows a log, -see *note Cherries::. - -* Menu: - -* Refreshing Logs:: -* Log Buffer:: -* Log Margin:: -* Select from Log:: -* Reflog:: -* Cherries:: - - -File: magit.info, Node: Refreshing Logs, Next: Log Buffer, Up: Logging - -5.3.1 Refreshing Logs ---------------------- - -The prefix command ‘magit-log-refresh-popup’, 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. - -‘L’ (‘magit-log-refresh-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘L g’ (‘magit-log-refresh’) - - This suffix command sets the local log arguments for the current - buffer. - -‘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. - -‘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. - -‘L t’ (‘magit-toggle-margin’) - - Show or hide the margin. - - -File: magit.info, Node: Log Buffer, Next: Log Margin, Prev: Refreshing Logs, Up: Logging - -5.3.2 Log Buffer ----------------- - -‘L’ (‘magit-log-refresh-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. See *note - Refreshing Logs::. - -‘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. - -‘C-c C-b’ (‘magit-go-backward’) - - Move backward in current buffer’s history. - -‘C-c C-f’ (‘magit-go-forward’) - - Move forward in current buffer’s history. - -‘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. - -‘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. - -‘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. - -‘=’ (‘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. - -‘+’ (‘magit-log-double-commit-limit’) - - Double the number of commits the current log buffer is limited to. - -‘-’ (‘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. - - 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: - - origin/feature - [green][blue-] - - instead of - - feature origin/feature - [blue-] [green-------] - - Also note that while the popup 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 *note Log Margin::. - - -File: magit.info, Node: Log Margin, Next: Select from Log, Prev: Log Buffer, Up: Logging - -5.3.3 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 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. - - • 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. - -‘L’ (‘magit-margin-popup’) - - This prefix command features the following commands for changing - the appearance of the margin. - - In some buffers that support the margin, "L" is bound to -‘magit-log-refresh-popup’, but that popup features the same commands, -and then some other unrelated commands. - -‘L L’ (‘magit-toggle-margin’) - - This command shows or hides the margin. - -‘L l’ (‘magit-cycle-margin-style’) - - This command cycles the style used for the margin. - -‘L d’ (‘magit-toggle-margin-details’) - - This command shows or hides details in the margin. - - -File: magit.info, Node: Select from Log, Next: Reflog, Prev: Log Margin, Up: Logging - -5.3.4 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: - -‘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. - -‘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 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. - - • 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. - - -File: magit.info, Node: Reflog, Next: Cherries, Prev: Select from Log, Up: Logging - -5.3.5 Reflog ------------- - -Also see *note (gitman)git-reflog::. - - These reflog commands are available from the log popup. See *note -Logging::. - -‘l r’ (‘magit-reflog-current’) - - Display the reflog of the current branch. - -‘l O’ (‘magit-reflog-other’) - - Display the reflog of a branch. - -‘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 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. - - • 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. - - -File: magit.info, Node: Cherries, Prev: Reflog, Up: Logging - -5.3.6 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 *note References Buffer::) can show cherries -for multiple "upstreams" at once. - - Also see *note (gitman)git-reflog::. - -‘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 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. - - • 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. - - -File: magit.info, Node: Diffing, Next: Ediffing, Prev: Logging, Up: Inspecting - -5.4 Diffing -=========== - -The status buffer contains diffs for the staged and unstaged commits, -but that obviously isn’t enough. The prefix command ‘magit-diff-popup’, -on ‘d’, features several suffix commands, which show a specific diff in -a separate diff buffer. - - Like other popups, the diff popup also features several arguments -that can be changed before invoking one of the suffix commands. -However, in the case of the diff popup, these arguments may be taken -from those currently in use in the current repository’s log buffer, -depending on the value of ‘magit-use-sticky-arguments’ (see *note Popup -Buffers and Prefix Commands::). - - Also see *note (gitman)git-diff::. - -‘d’ (‘magit-diff-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘d d’ (‘magit-diff-dwim’) - - Show changes for the thing at point. - -‘d r’ (‘magit-diff’) - - 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). - -‘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. - -‘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. - -‘d u’ (‘magit-diff-unstaged’) - - Show changes between the working tree and the index. - -‘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 popup also features two commands which show differences in -another buffer: - -‘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. - -‘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 *note Minor Mode for -Buffers Visiting Files::. - -* Menu: - -* Refreshing Diffs:: -* Diff Buffer:: -* Diff Options:: -* Revision Buffer:: - - -File: magit.info, Node: Refreshing Diffs, Next: Diff Buffer, Up: Diffing - -5.4.1 Refreshing Diffs ----------------------- - -The prefix command ‘magit-diff-refresh-popup’, 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. - -‘D’ (‘magit-diff-refresh-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘D g’ (‘magit-diff-refresh’) - - This suffix command sets the local diff arguments for the current - buffer. - -‘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. - -‘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. - -‘D t’ (‘magit-diff-toggle-refine-hunk’) - - This command toggles hunk refinement on or off. - -‘D r’ (‘magit-diff-switch-range-type’) - - This command converts the diff range type from "revA..revB" to - "revB...revA", or vice versa. - -‘D f’ (‘magit-diff-flip-revs’) - - This command swaps revisions in the diff range from "revA..revB" to - "revB..revA", or vice versa. - -‘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 popup, which allows changing any of the -supported arguments, there also exist some commands which change a -particular argument. - -‘-’ (‘magit-diff-less-context’) - - This command decreases the context for diff hunks by COUNT lines. - -‘+’ (‘magit-diff-more-context’) - - This command increases the context for diff hunks by COUNT lines. - -‘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 popups. - -‘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. - -‘C-c C-b’ (‘magit-go-backward’) - - This command moves backward in current buffer’s history. - -‘C-c C-f’ (‘magit-go-forward’) - - This command moves forward in current buffer’s history. - - -File: magit.info, Node: Diff Buffer, Next: Diff Options, Prev: Refreshing Diffs, Up: Diffing - -5.4.2 Diff Buffer ------------------ - -These commands are available in diff buffers. - -‘RET’ (‘magit-diff-visit-file’) - - From a diff, visit the corresponding file at the appropriate - position. - - If the diff shows changes in the worktree, the index, or ‘HEAD’, - then visit the actual file. Otherwise, when the diff is about an - older commit or a range, then visit the appropriate blob. - - If point is on a removed line, then visit the blob for the first - parent of the commit which removed that line, i.e. the last commit - where that line still existed. Otherwise visit the blob for the - commit whose changes are being shown. - - Interactively, when the file or blob to be displayed is already - being displayed in another window of the same frame, then just - select that window and adjust point. Otherwise, or with a prefix - argument, display the buffer in another window. The meaning of the - prefix argument can be inverted or further modified using the - option ‘magit-display-file-buffer-function’. - - Non-interactively the optional OTHER-WINDOW argument is taken - literally. DISPLAY-FN can be used to specify the display function - explicitly, in which case OTHER-WINDOW is ignored. - - The optional FORCE-WORKTREE means to force visiting the worktree - version of the file. To do this interactively use the command - ‘magit-diff-visit-file-worktree’ instead. - - -- User Option: magit-diff-visit-previous-blob - - This option controls whether ‘magit-diff-visit-file’ may visit the - previous blob. When this is ‘t’ and point is on a removed line in - a diff for a committed change, then ‘magit-diff-visit-file’ visits - the blob from the last revision which still had that line. - - Currently this is only supported for committed changes, for staged - and unstaged changes ‘magit-diff-visit-file’ always visits the file - in the working tree. - -‘C-<return>’ (‘magit-diff-visit-file-worktree’) - - From a diff, visit the corresponding file at the appropriate - position. - - When the file is already being displayed in another window of the - same frame, then just select that window and adjust point. With a - prefix argument also display in another window. - - The actual file in the worktree is visited. The positions in the - hunk headers get less useful the "older" the changes are, and as a - result, jumping to the appropriate position gets less reliable. - - Also see ‘magit-diff-visit-file’, which visits the respective blob, - unless the diff shows changes in the worktree, the index, or - ‘HEAD’. - - -- Command: magit-diff-visit-file-other-window - - From a diff, visit the corresponding file at the appropriate - position in another window. - -‘C-c C-t’ (‘magit-diff-trace-definition’) - - From a diff, show log for the definition at point. - -‘C-c C-e’ (‘magit-diff-edit-hunk-commit’) - - From a hunk, edit the respective commit and visit the file. - - First visit 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 invoke ‘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-command’ instead of this command. - -‘j’ (‘magit-jump-to-diffstat-or-diff’) - - Jump 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. - -‘SPC’ (‘scroll-up’) - - Scroll text upward. - -‘DEL’ (‘scroll-down’) - - Scroll text downward. - - -File: magit.info, Node: Diff Options, Next: Revision Buffer, Prev: Diff Buffer, Up: Diffing - -5.4.3 Diff Options ------------------- - - -- User Option: magit-diff-refine-hunk - - Whether to show word-granularity differences within diff hunks. - - • ‘nil’ never show fine differences. - - • ‘t’ show fine differences for the current diff hunk only. - - • ‘all’ show fine differences for all displayed diff hunks. - - -- 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 ajust 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. - - -- 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 - - Highlight the "wrong" indentation style. Used only when - ‘magit-diff-paint-whitespace’ is non-nil. - - The value is a list of cons cells. The car is a regular - expression, and the cdr is the value that applies to repositories - whose directory matches the regular expression. If more than one - element matches, then the *last* element in the list applies. The - default value should therefore come first in the list. - - If the value is ‘tabs’, highlight indentation with tabs. If the - value 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 which 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’. - - -File: magit.info, Node: Revision Buffer, Prev: Diff Options, Up: Diffing - -5.4.4 Revision Buffer ---------------------- - - -- User Option: magit-revision-insert-related-refs - - Whether to show related refs in revision buffers. - - -- User Option: magit-revision-show-gravatar - - Whether to show gravatar images in revision buffers. - - If non-nil, then the value has to be a cons-cell which specifies - where the gravatar images for the author and/or the committer are - inserted inside the text that was previously inserted according to - ‘magit-revision-header-format’. - - Both cells are regular expressions. The car specifies where to - insert the author gravatar image. The top half of the image is - inserted right after the matched text, the bottom half on the next - line at the same offset. The cdr specifies where to insert the - committer 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’). Note, however, that the log’s file -restriction will be ignored when ‘magit-log-arguments’ includes -‘--follow’. In this case, the ‘-u’ argument of the log popup can be -used to show the file-restricted diffs inline. - - If the revision buffer is not displayed from a log buffer, the file -restriction is determined by the file restriction in the repository’s -diff buffer, if it exists, and the value of the option -‘magit-use-sticky-arguments’. - - -File: magit.info, Node: Ediffing, Next: References Buffer, Prev: Diffing, Up: Inspecting - -5.5 Ediffing -============ - -This section describes how to enter Ediff from Magit buffers. For -information on how to use Ediff itself, see *note (ediff)Top::. - -‘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. - -‘E’ (‘magit-ediff-popup’) - - This prefix command shows the following suffix commands in a popup - buffer. - -‘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). - -‘E m’ (‘magit-ediff-resolve’) - - Resolve outstanding conflicts in a file using Ediff, defaulting to - the file at point. - - Provided that the value of ‘merge.conflictstyle’ is ‘diff3’, you - can view the file’s merge-base revision using ‘/’ in the Ediff - control buffer. - - In the rare event that you want to manually resolve all conflicts, - including those already resolved by Git, use - ‘ediff-merge-revisions-with-ancestor’. - -‘E s’ (‘magit-ediff-stage’) - - Stage and unstage changes to a file using Ediff, defaulting to the - file at point. - -‘E u’ (‘magit-ediff-show-unstaged’) - - Show unstaged changes to a file using Ediff. - -‘E i’ (‘magit-ediff-show-staged’) - - Show staged changes to a file using Ediff. - -‘E w’ (‘magit-ediff-show-working-tree’) - - Show changes in a file between ‘HEAD’ and working tree using Ediff. - -‘E c’ (‘magit-ediff-show-commit’) - - Show changes to a file introduced by a commit using Ediff. - -‘E z’ (‘magit-ediff-show-stash’) - - Show changes to a file introduced by a stash using Ediff. - - -- 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. - - -File: magit.info, Node: References Buffer, Next: Bisecting, Prev: Ediffing, Up: Inspecting - -5.6 References Buffer -===================== - -‘y’ (‘magit-show-refs-popup’) - - List and compare references in a dedicated buffer. By default all - refs are compared with ‘HEAD’, but with a prefix argument this - command instead acts as a prefix command and shows the following - suffix commands along with the appropriate infix arguments in a - popup buffer. - -‘y y’ (‘magit-show-refs-head’) - - List and compare references in a dedicated buffer. Refs are - compared with ‘HEAD’. - -‘y c’ (‘magit-show-refs-current’) - - List and compare references in a dedicated buffer. Refs are - compared with the current branch or ‘HEAD’ if it is detached. - -‘y o’ (‘magit-show-refs’) - - List and compare references in a dedicated buffer. Refs are - compared with a branch read from the user. - - -- 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 preceeding 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 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. - - • 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. - - -- User Option: magit-refs-filter-alist - - 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. Contrary to how they are displayed in the - buffer, for comparison each tag begins with "tags/" and each remote - branch with "<remote>/". - -‘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. - -* Menu: - -* References Sections:: - - -File: magit.info, Node: References Sections, Up: References Buffer - -5.6.1 References Sections -------------------------- - -The contents of references buffers is controlled using the hook -‘magit-refs-sections-hook’. See *note 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. - - -File: magit.info, Node: Bisecting, Next: Visiting Blobs, Prev: References Buffer, Up: Inspecting - -5.7 Bisecting -============= - -Also see *note (gitman)git-bisect::. - -‘B’ (‘magit-bisect-popup’) - - This prefix command shows the following suffix commands in a popup - buffer. - - When bisecting is not in progress, then the popup buffer features the -following commands. - -‘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 and - a bad commit. - -‘B s’ (‘magit-bisect-run’) - - Bisect automatically by running commands after each step. - - When bisecting is in progress, then the popup buffer features these -commands instead. - -‘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. - -‘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. - -‘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. - -‘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. - - -File: magit.info, Node: Visiting Blobs, Next: Blaming, Prev: Bisecting, Up: Inspecting - -5.8 Visiting Blobs -================== - -‘M-x magit-find-file’ (‘magit-find-file’) - - View FILE from REV. Switch to a buffer visiting blob REV:FILE, - creating one if none already exists. - -‘M-x magit-find-file-other-window’ (‘magit-find-file-other-window’) - - View FILE from REV, in another window. Like ‘magit-find-file’, but - create a new window or reuse an existing one. - - -File: magit.info, Node: Blaming, Prev: Visiting Blobs, Up: Inspecting - -5.9 Blaming -=========== - -Also see *note (gitman)git-blame::. - - To start blaming you can use ‘M-x’ in a file-visiting buffer to -invoke one of the following commands. You can also invoke these -commands using the blame popup, which is available on ‘b’ in -file-visiting buffers that already contain blame information and, also -on ‘b’, in all blob-visiting buffers. You can also enter the blame -popup from the file popup, which is available on ‘C-c M-g’, provided -‘magit-file-mode’ is enabled, see *note Minor Mode for Buffers Visiting -Files::. - - -- Command: magit-blame - - This command augments each line or chunk of lines in the current - file- 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. - - -- Command: magit-blame-echo - - This command is like ‘magit-blame’ 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’. - - -- Command: magit-blame-removal - - This command augments each line or chunk of lines in the current - blob-visiting buffer with information about the revision that - removes it. It cannot be used in file-visiting buffers. - - Like ‘magit-blame’, this command can be used recursively. - - -- Command: magit-blame-reverse - - This command augments each line or chunk of lines in the current - file- or blob-visiting buffer with information about the last - revision in which a line still existed. - - Like ‘magit-blame’, this command can be used recursively. - - 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. - -‘RET’ (‘magit-show-commit’) - - This command shows the commit that last touched the line at point. - -‘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. - -‘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 Magit-Blame mode is -enabled and Read-Only mode is not enabled. - -‘b’ (‘magit-blame-popup’) - - This prefix command shows the above suffix command along with the - appropriate infix arguments in a popup buffer. - -‘n’ (‘magit-blame-next-chunk’) - - This command moves to the next chunk. - -‘N’ (‘magit-blame-next-chunk-same-commit’) - - This command moves to the next chunk from the same commit. - -‘p’ (‘magit-blame-previous-chunk’) - - This command moves to the previous chunk. - -‘P’ (‘magit-blame-previous-chunk-same-commit’) - - This command moves to the previous chunk from the same commit. - -‘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. - -‘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. - -‘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. - - -File: magit.info, Node: Manipulating, Next: Transferring, Prev: Inspecting, Up: Top - -6 Manipulating -************** - -* Menu: - -* Repository Setup:: -* Staging and Unstaging:: -* Applying:: -* Committing:: -* Branching:: -* Merging:: -* Resolving Conflicts:: -* Rebasing:: -* Cherry Picking:: -* Resetting:: -* Stashing:: - - -File: magit.info, Node: Repository Setup, Next: Staging and Unstaging, Up: Manipulating - -6.1 Repository Setup -==================== - -‘M-x magit-init’ (‘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. - -‘M-x magit-clone’ (‘magit-clone’) - - This command clones a repository and then shows the status buffer - for the new repository. - - The user is queried for a remote url and a local directory. - - -- User Option: magit-clone-set-remote.pushDefault - - Whether to set the value of ‘remote.pushDefault’ after cloning. - - If ‘t’, then set without asking. If ‘nil’, then don’t set. If - ‘ask’, then ask the user every time she clones a repository. - - -File: magit.info, Node: Staging and Unstaging, Next: Applying, Prev: Repository Setup, Up: Manipulating - -6.2 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 *note Ediffing::. - -‘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. - -‘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. - -‘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. - -‘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. - -‘M-x magit-reverse-in-index’ (‘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: - - • Optionally make sure that there are no uncommitted changes. - - • Visit the ‘HEAD’ commit and navigate to the change that should - not have been included in that commit. - - • Type ‘u’ (‘magit-unstage’) to reverse it in the index. This - assumes that ‘magit-unstage-committed-changes’ is non-nil. - - • Type ‘c e’ to extend ‘HEAD’ with the staged changes, including - those that were already staged before. - - • Optionally stage the remaining changes using ‘s’ or ‘S’ and - then type ‘c c’ to create a new commit. - -‘M-x magit-reset-index’ (‘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’. - -* Menu: - -* Staging from File-Visiting Buffers:: - - -File: magit.info, Node: Staging from File-Visiting Buffers, Up: Staging and Unstaging - -6.2.1 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. - -‘M-x magit-stage-file’ (‘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. - -‘M-x magit-unstage-file’ (‘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. - - -File: magit.info, Node: Applying, Next: Committing, Prev: Staging and Unstaging, Up: Manipulating - -6.3 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. - -‘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. - -‘k’ (‘magit-discard’) - - Remove the change at point from the working tree. - -‘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). - - -File: magit.info, Node: Committing, Next: Branching, Prev: Applying, Up: Manipulating - -6.4 Committing -============== - -When the user initiates a commit, Magit calls ‘git commit’ without any -arguments, so Git has to get it from the user. It creates the file -‘.git/COMMIT_EDITMSG’ and then opens that file in an editor. Magit -arranges for that editor to be the Emacsclient. Once the user finishes -the editing session, the Emacsclient exits and Git creates the commit -using the file’s content as message. - -* Menu: - -* Initiating a Commit:: -* Editing Commit Messages:: - - -File: magit.info, Node: Initiating a Commit, Next: Editing Commit Messages, Up: Committing - -6.4.1 Initiating a Commit -------------------------- - -Also see *note (gitman)git-commit::. - -‘c’ (‘magit-commit-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘c c’ (‘magit-commit’) - - Create a new commit on ‘HEAD’. With a prefix argument amend to the - commit at ‘HEAD’ instead. - -‘c a’ (‘magit-commit-amend’) - - Amend the last commit. - -‘c e’ (‘magit-commit-extend’) - - Amend the last commit, without editing the message. With a prefix - argument keep the committer date, otherwise change it. The option - ‘magit-commit-extend-override-date’ can be used to inverse the - meaning of the prefix argument. - - Non-interactively respect the optional OVERRIDE-DATE argument and - ignore the option. - -‘c w’ (‘magit-commit-reword’) - - Reword the last commit, ignoring staged changes. With a prefix - argument keep the committer date, otherwise change it. The option - ‘magit-commit-reword-override-date’ can be used to inverse the - meaning of the prefix argument. - - Non-interactively respect the optional OVERRIDE-DATE argument and - ignore the option. - -‘c f’ (‘magit-commit-fixup’) - - Create a fixup commit. - - With a prefix argument the target commit has to be confirmed. - Otherwise the commit at point may be used without confirmation - depending on the value of option ‘magit-commit-squash-confirm’. - -‘c F’ (‘magit-commit-instant-fixup’) - - Create a fixup commit and instantly rebase. - -‘c s’ (‘magit-commit-squash’) - - Create a squash commit, without editing the squash message. - - With a prefix argument the target commit has to be confirmed. - Otherwise the commit at point may be used without confirmation - depending on the value of option ‘magit-commit-squash-confirm’. - -‘c S’ (‘magit-commit-instant-squash’) - - Create a squash commit and instantly rebase. - -‘c A’ (‘magit-commit-augment’) - - Create a squash commit, editing the squash message. - - With a prefix argument the target commit has to be confirmed. - Otherwise the commit at point may be used without confirmation - depending on the value of option ‘magit-commit-squash-confirm’. - - -- User Option: magit-commit-ask-to-stage - - Whether to ask to stage all unstaged changes when committing and - nothing is staged. - - -- 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. - - -- 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. - - -File: magit.info, Node: Editing Commit Messages, Prev: Initiating a Commit, Up: Committing - -6.4.2 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 committed, -while the other is used to write the message. All regular editing -commands are available in the commit message buffer. This section only -describes the additional commands. - - Commit messages are edited in an edit session - in the background Git -is waiting for the editor, in our case the Emacsclient, to save the -commit message in a file (in most cases ‘.git/COMMIT_EDITMSG’) and then -return. If the Emacsclient 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. - -‘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. - -‘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, these 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. - -‘C-c M-s’ (‘git-commit-save-message’) - - Save the current buffer content to the commit message ring. - -‘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. - -‘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. 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 together with -those that are already committed. - -‘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. - -‘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). - - 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. - -‘C-c C-a’ (‘git-commit-ack’) - - Insert a header acknowledging that you have looked at the commit. - -‘C-c C-r’ (‘git-commit-review’) - - Insert a header acknowledging that you have reviewed the commit. - -‘C-c C-s’ (‘git-commit-signoff’) - - Insert a header to sign off the commit. - -‘C-c C-t’ (‘git-commit-test’) - - Insert a header acknowledging that you have tested the commit. - -‘C-c C-o’ (‘git-commit-cc’) - - Insert a header mentioning someone who might be interested. - -‘C-c C-p’ (‘git-commit-reported’) - - Insert a header mentioning the person who reported the issue being - fixed by the commit. - -‘C-c C-i’ (‘git-commit-suggested’) - - Insert a header mentioning the person who suggested the change. - - ‘git-commit-mode’ is a minor mode that is only used to establish the -above key bindings. This allows using an arbitrary major mode when -editing the commit message. It’s even possible to use a different major -mode 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’. The following functions are -suitable for that hook. - - -- User Option: git-commit-setup-hook - - Hook run at the end of ‘git-commit-setup’. - - -- Function: magit-revert-buffers &optional force - - Revert unmodified file-visiting buffers of the current repository. - - If either ‘magit-revert-buffers’ is non-nil and - ‘inhibit-magit-revert’ is nil, or if optional FORCE is non-nil, - then revert all unmodified buffers that visit files being tracked - in the current repository. - - -- 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’ and set ‘fill-column’ to the value of - ‘git-commit-fill-column’. - - -- 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’s commit popup 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: with-editor-usage-message - - Show usage information in the echo area. - - Magit also helps with writing *good* commit messages by complaining -when certain rules are violated. - - -- 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-fill-column - - Column beyond which automatic line-wrapping should happen in commit - message buffers. - - -- 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. - - -- Function: git-commit-check-style-conventions - - Check for violations of certain basic style conventions. For each - violation ask the user if she wants to proceed anyway. This makes - sure the summary line isn’t too long and that the second line is - empty. - - To show no diff while committing remove ‘magit-commit-diff’ from -‘server-switch-hook’. - - -File: magit.info, Node: Branching, Next: Merging, Prev: Committing, Up: Manipulating - -6.5 Branching -============= - -* Menu: - -* The Two Remotes:: -* The Branch Popup:: -* The Branch Config Popup:: -* Auxillary Branch Commands:: - - -File: magit.info, Node: The Two Remotes, Next: The Branch Popup, Up: Branching - -6.5.1 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 popups features three -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 popup ‘magit-branch-config-popup’, which is a -sub-popup of many popups that deal with branches. It is also possible -to set the push-remote or upstream while pushing (see *note Pushing::). - - -File: magit.info, Node: The Branch Popup, Next: The Branch Config Popup, Prev: The Two Remotes, Up: Branching - -6.5.2 The Branch Popup ----------------------- - -The popup ‘magit-branch-popup’ 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 popup deals with -branches themselves, not with the commits reachable from them. Those -features are available from separate popups. - -‘b’ (‘magit-branch-popup’) - - This prefix command shows the following suffix commands in a popup - buffer. - - By default it also displays the values of some branch-related Git - variables and allows changing their values, just like the - specialized ‘magit-branch-config-popup’ does. - - -- User Option: magit-branch-popup-show-variables - - Whether the ‘magit-branch-popup’ shows Git variables. This - defaults to t to avoid changing key bindings. When set to nil, no - variables are displayed directly in this popup, and the sub-popup - ‘magit-branch-config-popup’ has to be used instead to view and - change branch related variables. - -‘b C’ (‘magit-branch-config-popup’) - - This command shows branch related variables in a separate popup. - By default this asks the user for which branch the variables should - be shown. When ‘magit-branch-popup-show-variables’ is ‘nil’, then - it shows the variables for the current branch, unless a prefix - argument is used. - -‘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. - -‘b n’ (‘magit-branch’) - - 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’. - -‘b c’ (‘magit-branch-and-checkout’) - - This command creates a new branch like ‘magit-branch’, but then - also checks it out. - - Also see option ‘magit-branch-prefer-remote-upstream’. - -‘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’. - -‘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 - began 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. - -‘b Y’ (‘magit-branch-pull-request’) - - This command creates and configures a new branch from a Github - pull-request, creating and configuring a new remote if necessary. - - The name of the local branch is the same as the name of the remote - branch that you are being asked to merge, unless the contributor - could not be bother to properly name the branch before opening the - pull-request. The most likely such case is when you are being - asked to merge something like "fork/master" into "origin/master". - In such cases the local branch will be named "pr-N", where ‘N’ is - the pull-request number. - - These variables are always set by this command: - - • ‘branch.<name>.pullRequest’ is set to the pull-request number. - - • ‘branch.<name>.pullRequestRemote’ is set to the remote on - which the pull-request branch is located. - - • ‘branch.<name>.pushRemote’ is set to the same remote as - ‘branch.<name>.pullRequestRemote’ if that is possible, - otherwise it is set to the upstream remote. - - • ‘branch.<name>.description’ is set to the pull-request title. - - • ‘branch.<name>.rebase’ is set to ‘true’ because there should - be no merge commits among the commits in a pull-request. - - This command also configures the upstream and the push-remote of - the local branch that it creates. - - The branch against which the pull-request was opened, is always - used as the upstream. This makes it easy to see what commits you - are being asked to merge in the section titled something like - "Unmerged into origin/master". - - Like for other commands that create a branch it depends on the - option ‘magit-branch-prefer-remote-upstream’ whether the remote - branch itself or the respective local branch is used as the - upstream, so this section may also be titled e.g. "Unmerged into - master". - - When necessary and possible, then the remote pull-request branch is - configured to be used as the push-target. This makes it easy to - see what further changes the contributor has made since you last - reviewed their changes in the section titled something like - "Unpulled from origin/new-feature" or "Unpulled from - fork/new-feature". - - • If the pull-request branch is located in the upstream - repository, then you probably have set ‘remote.pushDefault’ to - that repository. However some users like to set that variable - to their personal fork, even if they have push access to the - upstream, so ‘branch.<name>.pushRemote’ is set anyway. - - • If the pull-request branch is located inside a fork, then you - are usually able to push to that branch, because Github by - default allows the recipient of a pull-request to push to the - remote pull-request branch even if it is located in a fork. - The contributor has to explicitly disable this. - - • If you are not allowed to push to the pull-request branch - on the fork, then a branch by the same name located in - the upstream repository is configured as the push-target. - - • A — sadly rather common — special case is when the - contributor didn’t bother to use a dedicated branch for - the pull-request. - - The most likely such case is when you are being asked to - merge something like "fork/master" into "origin/master". - The special push permission mentioned above is never - granted for the branch that is the repository’s default - branch, and that would almost certainly be the case in - this scenario. - - To enable you to easily push somewhere anyway, the local - branch is named "pr-N" (where ‘N’ is the pull-request - number) and the upstream repository is used as the - push-remote. - - • Finally, if you are allowed to push to the pull-request - branch and the contributor had the foresight to use a - dedicated branch, then the fork is configured as the - push-remote. - - The push-remote is configured using - ‘branch.<name>.pushRemote’, even if the used value is - identical to that of ‘remote.pushDefault’, just in case you - change the value of the latter later on. Additionally the - variable ‘branch.<name>.pullRequestRemote’ is set to the - remote on which the pull-request branch is located. - - When you later delete the local pull-request branch, then you are - offered to also delete the corresponding remote, provided it is not - the upstream remote and that the tracking branch that corresponds - to the deleted branch is the only remaining tracked branch. If you - don’t confirm, then only the tracking branch itself is deleted in - addition to the local branch. - - Do not delete the tracking branch instead of the local branch. The - cleanup mentioned in the previous paragraph is not performed if you - do that. - -‘b y’ (‘magit-checkout-pull-request’) - - This command creates and configures a new branch from a pull - request, the same way ‘magit-branch-pull-request’ does. - Additionally it checks out the new branch. - -‘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. - -‘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. - -‘b r’ (‘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 - ‘nil’, 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.: - - feature --upstream--> origin/master - - instead of - - feature --upstream--> master --upstream--> origin/master - - 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: - - (("origin/master" "master" "next" "maint")) - - Or if the names of all your ephemeral branches contain a slash, at - least in some repositories, then a good value could be: - - (("origin/master" . "/")) - - Of course you can also fine-tune: - - (("origin/maint" . "\\`hotfix/") - ("origin/master" . "\\`feature/")) - - -- 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-popup’. - - 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: - - (magit-remove-popup-key 'magit-branch-popup :action ?b) - (magit-define-popup-action 'magit-branch-popup - ?b "Checkout" 'magit-branch-or-checkout - 'magit-branch t) - - -File: magit.info, Node: The Branch Config Popup, Next: Auxillary Branch Commands, Prev: The Branch Popup, Up: Branching - -6.5.3 The Branch Config Popup ------------------------------ - - -- Command: magit-branch-config-popup - - This prefix command shows the following branch-related Git - variables in a popup buffer. The values can be changed from that - buffer. - - This popup is a sub-popup of several popups that deal with - branches, including ‘magit-branch-popup’, ‘magit-pull-popup’, - ‘magit-fetch-popup’, ‘magit-pull-and-fetch-popup’, and - ‘magit-push-popup’. In all of these popups "C" is bound to this - popup. - - The following variables are used to configure a specific branch. The -values are being displayed for the current branch (if any). To change -the value for another branch invoke ‘magit-branch-config-popup’ with a -prefix argument. - - -- 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.: - - git config --global remote.autoSetupMerge always - - For more information about these variables you should also see - - *note (gitman)git-config::. Also see *note (gitman)git-branch::. , -*note (gitman)git-checkout::. and *note 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. - - -File: magit.info, Node: Auxillary Branch Commands, Prev: The Branch Config Popup, Up: Branching - -6.5.4 Auxillary Branch Commands -------------------------------- - -These commands are not available from the branch popup by default. - - -- Command: magit-branch-shelve - - This command shelve 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 unshelve 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. - - -File: magit.info, Node: Merging, Next: Resolving Conflicts, Prev: Branching, Up: Manipulating - -6.6 Merging -=========== - -Also see *note (gitman)git-merge::. For information on how to resolve -merge conflicts see the next section. - -‘m’ (‘magit-merge-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - When no merge is in progress, then the popup buffer features the -following commands. - -‘m m’ (‘magit-merge’) - - 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. - -‘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’. - -‘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. - -‘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. - -‘m i’ (‘magit-merge-into’) - - This command merges the current branch into another local branch - and then removes the former. The latter becomes the new current - branch. - - Before the source branch is merged, it is first force pushed to its - push-remote, provided the respective remote branch already exists. - This ensures that the respective pull-request (if any) won’t get - stuck on some obsolete version of the commits that are being - merged. Finally, if ‘magit-branch-pull-request’ was used to create - the merged branch, then the respective remote branch is also - removed. - -‘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 popup. - -‘m p’ (‘magit-merge-preview’) - - This command shows a preview of merging another branch or an - arbitrary revision into the current branch. - - When a merge is in progress, then the popup buffer features these -commands instead. - -‘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. - -‘m a’ (‘magit-merge-abort’) - - This command aborts the current merge operation. - - -File: magit.info, Node: Resolving Conflicts, Next: Rebasing, Prev: Merging, Up: Manipulating - -6.7 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 six times the same character, one of ‘<’, -‘|’, ‘=’ and ‘>’ and are followed by information about the source of the -respective versions, e.g.: - - <<<<<<< HEAD - Take the blue pill. - ======= - Take the red pill. - >>>>>>> feature - - 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: - - Take both pills. - - 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: - - git config --global merge.conflictStyle diff3 - - The above conflict might then have looked like this: - - <<<<<<< HEAD - Take the blue pill. - ||||||| merged common ancestors - Take either the blue or the red pill, but not both. - ======= - Take the red pill. - >>>>>>> feature - - 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 -(*note (ediff)Top::), and Emerge (*note (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. - - 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 *note Ediffing::. Explaining how -to use Ediff is beyond the scope of this manual, instead see *note -(ediff)Top::. - - 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. - - -File: magit.info, Node: Rebasing, Next: Cherry Picking, Prev: Resolving Conflicts, Up: Manipulating - -6.8 Rebasing -============ - -Also see *note (gitman)git-rebase::. For information on how to resolve -conflicts that occur during rebases see the preceding section. - -‘r’ (‘magit-rebase-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - When no rebase is in progress, then the popup buffer features the -following 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 *note Information About In-Progress Rebase::. - -‘r p’ (‘magit-rebase-onto-pushremote’) - - Rebase the current branch onto ‘branch.<name>.pushRemote’. If that - variable is unset, then rebase onto ‘remote.pushDefault’. - -‘r u’ (‘magit-rebase-onto-upstream’) - - Rebase the current branch onto its upstream branch. - -‘r e’ (‘magit-rebase’) - - Rebase 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." - -‘r s’ (‘magit-rebase-subset’) - - Start a non-interactive rebase sequence with 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 popup 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 popup. - -‘r i’ (‘magit-rebase-interactive’) - - Start an interactive rebase sequence. - -‘r f’ (‘magit-rebase-autosquash’) - - Combine squash and fixup commits with their intended targets. - -‘r m’ (‘magit-rebase-edit-commit’) - - Edit a single older commit using rebase. - -‘r w’ (‘magit-rebase-reword-commit’) - - Reword a single older commit using rebase. - -‘r k’ (‘magit-rebase-remove-commit’) - - Remove a single older commit using rebase. - - When a rebase is in progress, then the popup buffer features these -commands instead. - -‘r r’ (‘magit-rebase-continue’) - - 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. - -‘r s’ (‘magit-rebase-skip’) - - Skip the current commit and restart the current rebase operation. - -‘r e’ (‘magit-rebase-edit’) - - Edit the todo list of the current rebase operation. - -‘r a’ (‘magit-rebase-abort’) - - Abort the current rebase operation, restoring the original branch. - -* Menu: - -* Editing Rebase Sequences:: -* Information About In-Progress Rebase:: - - -File: magit.info, Node: Editing Rebase Sequences, Next: Information About In-Progress Rebase, Up: Rebasing - -6.8.1 Editing Rebase Sequences ------------------------------- - -‘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. - -‘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. - -‘RET’ (‘git-rebase-show-commit’) - - Show the commit on the current line in another buffer and select - that buffer. - -‘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. - -‘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. - -‘p’ (‘git-rebase-backward-line’) - - Move to previous line. - -‘n’ (‘forward-line’) - - Move to next line. - -‘M-p’ (‘git-rebase-move-line-up’) - - Move the current commit (or command) up. - -‘M-n’ (‘git-rebase-move-line-down’) - - Move the current commit (or command) down. - -‘r’ (‘git-rebase-reword’) - - Edit message of commit on current line. - -‘e’ (‘git-rebase-edit’) - - Stop at the commit on the current line. - -‘s’ (‘git-rebase-squash’) - - Meld commit on current line into previous commit, and edit message. - -‘f’ (‘git-rebase-fixup’) - - Meld commit on current line into previous commit, discarding the - current commit’s message. - -‘k’ (‘git-rebase-kill-line’) - - Kill the current action line. - -‘c’ (‘git-rebase-pick’) - - Use commit on current line. - -‘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. - -‘y’ (‘git-rebase-insert’) - - Read an arbitrary commit and insert it below current line. - -‘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. - - -File: magit.info, Node: Information About In-Progress Rebase, Prev: Editing Rebase Sequences, Up: Rebasing - -6.8.2 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: - - • Yellow commits have not been applied yet. - - • 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 *note Editing Rebase Sequences::. - - • 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 (1) 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. - - ---------- Footnotes ---------- - - (1) 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?". - - -File: magit.info, Node: Cherry Picking, Next: Resetting, Prev: Rebasing, Up: Manipulating - -6.9 Cherry Picking -================== - -Also see *note (gitman)git-cherry-pick::. - -‘A’ (‘magit-cherry-pick-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - When no cherry-pick or revert is in progress, then the popup buffer -features the following commands. - -‘A A’ (‘magit-cherry-pick’) - - 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. - -‘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 popup 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. - -‘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. - -‘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. - - 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. - -‘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. - -‘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 popup buffer -features these commands instead. - -‘A A’ (‘magit-sequence-continue’) - - Resume the current cherry-pick or revert sequence. - -‘A s’ (‘magit-sequence-skip’) - - Skip the stopped at commit during a cherry-pick or revert sequence. - -‘A a’ (‘magit-sequence-abort’) - - Abort the current cherry-pick or revert sequence. This discards - all changes made since the sequence started. - -* Menu: - -* Reverting:: - - -File: magit.info, Node: Reverting, Up: Cherry Picking - -6.9.1 Reverting ---------------- - -‘V’ (‘magit-revert-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - When no cherry-pick or revert is in progress, then the popup buffer -features the following commands. - -‘V V’ (‘magit-revert’) - - 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. - -‘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 popup buffer -features these commands instead. - -‘V A’ (‘magit-sequence-continue’) - - Resume the current cherry-pick or revert sequence. - -‘V s’ (‘magit-sequence-skip’) - - Skip the stopped at commit during a cherry-pick or revert sequence. - -‘V a’ (‘magit-sequence-abort’) - - Abort the current cherry-pick or revert sequence. This discards - all changes made since the sequence started. - - -File: magit.info, Node: Resetting, Next: Stashing, Prev: Cherry Picking, Up: Manipulating - -6.10 Resetting -============== - -Also see *note (gitman)git-reset::. - -‘x’ (‘magit-reset’) - - 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. - With a prefix argument also reset the working tree. - -‘X m’ (‘magit-reset-head’) - - 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. - -‘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. - -‘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. - -‘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. - -‘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. - -‘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. - - -File: magit.info, Node: Stashing, Prev: Resetting, Up: Manipulating - -6.11 Stashing -============= - -Also see *note (gitman)git-stash::. - -‘z’ (‘magit-stash-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘z z’ (‘magit-stash’) - - Create a stash of the index and working tree. Untracked files are - included according to popup arguments. One prefix argument is - equivalent to ‘--include-untracked’ while two prefix arguments are - equivalent to ‘--all’. - -‘z i’ (‘magit-stash-index’) - - Create a stash of the index only. Unstaged and untracked changes - are not stashed. - -‘z w’ (‘magit-stash-worktree’) - - Create a stash of unstaged changes in the working tree. Untracked - files are included according to popup arguments. One prefix - argument is equivalent to ‘--include-untracked’ while two prefix - arguments are equivalent to ‘--all’. - -‘z x’ (‘magit-stash-keep-index’) - - Create a stash of the index and working tree, keeping index intact. - Untracked files are included according to popup arguments. One - prefix argument is equivalent to ‘--include-untracked’ while two - prefix arguments are equivalent to ‘--all’. - -‘z Z’ (‘magit-snapshot’) - - Create a snapshot of the index and working tree. Untracked files - are included according to popup arguments. One prefix argument is - equivalent to ‘--include-untracked’ while two prefix arguments are - equivalent to ‘--all’. - -‘z I’ (‘magit-snapshot-index’) - - Create a snapshot of the index only. Unstaged and untracked - changes are not stashed. - -‘z W’ (‘magit-snapshot-worktree’) - - Create a snapshot of unstaged changes in the working tree. - Untracked files are included according to popup arguments. One - prefix argument is equivalent to ‘--include-untracked’ while two - prefix arguments are equivalent to ‘--all’-. - -‘z a’ (‘magit-stash-apply’) - - Apply a stash to the working tree. Try to preserve the stash - index. If that fails because there are staged changes, apply - without preserving the stash index. - -‘z p’ (‘magit-stash-pop’) - - Apply a stash to the working tree and remove it from stash list. - Try to preserve the stash index. If that fails because there are - staged changes, apply without preserving the stash index and forgo - removing the stash. - -‘z k’ (‘magit-stash-drop’) - - Remove a stash from the stash list. When the region is active, - offer to drop all contained stashes. - -‘z v’ (‘magit-stash-show’) - - Show all diffs of a stash in a buffer. - -‘z b’ (‘magit-stash-branch’) - - Create and checkout a new BRANCH from STASH. The branch starts at - the commit that was current when the stash was created. - -‘z B’ (‘magit-stash-branch-here’) - - Create and checkout a new BRANCH using ‘magit-branch’ with the - current branch or ‘HEAD’ as the starting-point. Then apply STASH, - dropping it if it applies cleanly. - -‘z f’ (‘magit-stash-format-patch’) - - Create a patch from STASH. - -‘k’ (‘magit-stash-clear’) - - Remove all stashes saved in REF’s reflog by deleting REF. - -‘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 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. - - • 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. - - -File: magit.info, Node: Transferring, Next: Miscellaneous, Prev: Manipulating, Up: Top - -7 Transferring -************** - -* Menu: - -* Remotes:: -* Fetching:: -* Pulling:: -* Pushing:: -* Creating and Sending Patches:: -* Applying Patches:: - - -File: magit.info, Node: Remotes, Next: Fetching, Up: Transferring - -7.1 Remotes -=========== - -* Menu: - -* The Remote Popup:: -* The Remote Config Popup:: - - -File: magit.info, Node: The Remote Popup, Next: The Remote Config Popup, Up: Remotes - -7.1.1 The Remote Popup ----------------------- - -The popup ‘magit-remote-popup’ is used to add remotes and to make -changes to existing remotes. This popup only deals with remotes -themselves, not with branches or the transfer of commits. Those -features are available from separate popups. - - Also see *note (gitman)git-remote::. - -‘M’ (‘magit-remote-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - -- User Option: magit-remote-popup-show-variables - - This option controls whether the ‘magit-remote-popup’ shows remote - related Git variables. When set to nil, no variables are displayed - directly in this popup, and the sub-popup - ‘magit-remote-config-popup’ has to be used instead to view and - change remote related variables. - -‘M C’ (‘magit-remote-config-popup’) - - This command shows remote related variables in a separate popup. - By default this asks the user for which remote the variables should - be shown. When ‘magit-remote-popup-show-variables’ is ‘nil’, then - it shows the variables for the upstream of the current branch or - "origin" it that branch has no remote upstream. To select another - remote use a prefix argument. - -‘M a’ (‘magit-remote-add’) - - This command add a remote and fetches it. The remote name and url - are read in the minibuffer. - -‘M r’ (‘magit-remote-rename’) - - This command renames a remote. Both the old and the new names are - read in the minibuffer. - -‘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. - -‘M k’ (‘magit-remote-remove’) - - This command deletes a remote, read in the minibuffer. - -‘M p’ (‘magit-remote-prune’) - - This command removes stale remote-tracking branches for a remote - read in the minibuffer. - -‘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. - - -File: magit.info, Node: The Remote Config Popup, Prev: The Remote Popup, Up: Remotes - -7.1.2 The Remote Config Popup ------------------------------ - - -- Command: magit-remote-config-popup - - This prefix command shows the following remote-related Git - variables in a popup buffer. The values can be changed from that - buffer. - - This popup is a sub-popup of the ‘magit-remote-popup’ in which "C" - is bound to this popup. - - The following variables are used to configure a specific remote. The -values are being displayed for the upstream remote of the current -branch. To change the value for another remote invoke -‘magit-remote-config-popup’ with a prefix argument. - - -- 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 fetching from 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 not - value, then only tags are fetched that are reachable from fetched - branches. - - -File: magit.info, Node: Fetching, Next: Pulling, Prev: Remotes, Up: Transferring - -7.2 Fetching -============ - -For information about the differences between the _upstream_ and the -_push-remote_, see *note Branching::. - - Also see *note (gitman)git-fetch::. - -‘f’ (‘magit-fetch-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘f p’ (‘magit-fetch-from-pushremote’) - - Fetch from the push-remote of the current branch. - -‘f u’ (‘magit-fetch-from-upstream’) - - Fetch from the upstream of the current branch. - -‘f e’ (‘magit-fetch’) - - Fetch from another repository. - -‘f o’ (‘magit-fetch-branch’) - - Fetch a branch from a remote, both of which are read from the - minibuffer. - -‘f r’ (‘magit-fetch-refspec’) - - Fetch from a remote using an explicit refspec, both of which are - read from the minibuffer. - -‘f a’ (‘magit-fetch-all’) - - Fetch from all remotes. - -‘f m’ (‘magit-submodule-fetch’) - - Fetch all submodules. With a prefix argument fetch all remotes of - all submodules. - - Instead of using one popup for fetching and another for pulling, you -could also use ‘magit-pull-and-fetch-popup’. See its doc-string for -more information. - - -File: magit.info, Node: Pulling, Next: Pushing, Prev: Fetching, Up: Transferring - -7.3 Pulling -=========== - -For information about the differences between the _upstream_ and the -_push-remote_, see *note Branching::. - - Also see *note (gitman)git-pull::. - -‘F’ (‘magit-pull-popup’) - - This prefix command shows the following suffix commands in a popup - buffer. - -‘F p’ (‘magit-pull-from-pushremote’) - - Pull from the push-remote of the current branch. - -‘F u’ (‘magit-pull-from-upstream’) - - Pull from the upstream of the current branch. - -‘F e’ (‘magit-pull’) - - Pull from a branch read in the minibuffer. - - Instead of using one popup for fetching and another for pulling, you -could also use ‘magit-pull-and-fetch-popup’. See its doc-string for -more information. - - -File: magit.info, Node: Pushing, Next: Creating and Sending Patches, Prev: Pulling, Up: Transferring - -7.4 Pushing -=========== - -For information about the differences between the _upstream_ and the -_push-remote_, see *note Branching::. - - Also see *note (gitman)git-push::. - -‘P’ (‘magit-push-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘P p’ (‘magit-push-current-to-pushremote’) - - Push the current branch to ‘branch.<name>.pushRemote’ or if that is - unset to ‘remote.pushDefault’. - - When ‘magit-push-current-set-remote-if-missing’ is non-nil and the - push-remote is not configured, then read the push-remote from the - user, set it, and then push to it. With a prefix argument the - push-remote can be changed before pushed to it. - -‘P u’ (‘magit-push-current-to-upstream’) - - Push the current branch to its upstream branch. - - When ‘magit-push-current-set-remote-if-missing’ is non-nil and the - push-remote is not configured, then read the upstream from the - user, set it, and then push to it. With a prefix argument the - push-remote can be changed before pushed to it. - -‘P e’ (‘magit-push-current’) - - Push the current branch to a branch read in the minibuffer. - -‘P o’ (‘magit-push’) - - Push an arbitrary branch or commit somewhere. Both the source and - the target are read in the minibuffer. - -‘P r’ (‘magit-push-refspecs’) - - Push 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. - -‘P m’ (‘magit-push-matching’) - - Push all matching branches to another repository. If multiple - remotes exit, then read one from the user. If just one exists, use - that without requiring confirmation. - -‘P t’ (‘magit-push-tags’) - - Push 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. - -‘P T’ (‘magit-push-tag’) - - Push a tag to another repository. - - Two more push commands exist, which by default are not available from -the push popup. See their doc-strings for instructions on how to add -them to the popup. - - -- Command: magit-push-implicitly args - - Push somewhere without using an explicit refspec. - - This command simply runs ‘git push -v [ARGS]’. ARGS are the - arguments specified in the popup buffer. 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’. - - -- Command: magit-push-to-remote remote args - - Push 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 - arguments specified in the popup buffer. 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’. - - -- User Option: magit-push-current-set-remote-if-missing - - This option controls whether missing remotes are configured before - pushing. - - When ‘nil’, then the command ‘magit-push-current-to-pushremote’ and - ‘magit-push-current-to-upstream’ do not appear in the push popup if - the push-remote resp. upstream is not configured. If the user - invokes one of these commands anyway, then it raises an error. - - When ‘non-nil’, then these commands always appear in the push - popup. But if the required configuration is missing, then they do - appear in a way that indicates that this is the case. If the user - invokes one of them, then it asks for the necessary configuration, - stores the configuration, and then uses it to push a first time. - - This option also affects whether the argument ‘--set-upstream’ is - available in the popup. If the value is ‘non-nil’, then that - argument is redundant. But note that changing the value of this - option does not take affect immediately, the argument will only be - added or removed after restarting Emacs. - - -File: magit.info, Node: Creating and Sending Patches, Next: Applying Patches, Prev: Pushing, Up: Transferring - -7.5 Creating and Sending Patches -================================ - -‘W’ (‘magit-patch-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘W p’ (‘magit-format-patch’) - - Create patches for a set commits. If the region marks commits, - then create patches for those. Otherwise prompt for a range or a - single commit, defaulting to the commit at point. - -‘W r’ (‘magit-request-pull’) - - Request that upstream pulls from your public repository. - - 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. - - -File: magit.info, Node: Applying Patches, Prev: Creating and Sending Patches, Up: Transferring - -7.6 Applying Patches -==================== - -Also see *note (gitman)git-am::. and *note (gitman)git-apply::. - -‘w’ (‘magit-am-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘w w’ (‘magit-am-apply-patches’) - - Apply one or more patches. If the region marks files, then apply - those patches. Otherwise read a file name in the minibuffer - defaulting to the file at point. - -‘w m’ (‘magit-am-apply-maildir’) - - Apply the patches from a maildir. - - When an "am" operation is in progress, then the popup buffer features -these commands instead. - -‘w w’ (‘magit-am-continue’) - - Resume the current patch applying sequence. - -‘w s’ (‘magit-am-skip’) - - Skip the stopped at patch during a patch applying sequence. - -‘w a’ (‘magit-am-abort’) - - Abort the current patch applying sequence. This discards all - changes made since the sequence started. - - In addition to the commands listed at the top, the "am" popup also -has a binding for the related "patch" popup. - -‘w a’ (‘magit-patch-apply-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘w a a’ (‘magit-patch-apply’) - - This command applies a simple patch file, which may not contain any - Git metadata in addition to the actual diff. - - -File: magit.info, Node: Miscellaneous, Next: Customizing, Prev: Transferring, Up: Top - -8 Miscellaneous -*************** - -* Menu: - -* Tagging:: -* Notes:: -* Submodules:: -* Subtree:: -* Worktree:: -* Common Commands:: -* Wip Modes:: -* Minor Mode for Buffers Visiting Files:: -* Minor Mode for Buffers Visiting Blobs:: - - -File: magit.info, Node: Tagging, Next: Notes, Up: Miscellaneous - -8.1 Tagging -=========== - -Also see *note (gitman)git-tag::. - -‘t’ (‘magit-tag-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘t t’ (‘magit-tag’) - - Create a new tag with the given NAME at REV. With a prefix - argument annotate the tag. - -‘t k’ (‘magit-tag-delete’) - - Delete one or more tags. If the region marks multiple tags (and - nothing else), then offer to delete those. Otherwise, prompt for a - single tag to be deleted, defaulting to the tag at point. - -‘t p’ (‘magit-tag-prune’) - - Offer to delete tags missing locally from REMOTE, and vice versa. - - -- Command: magit-tag-release - - Create an opinionated release tag. - - Assume version tags that match "\\‘v?[0-9]\*\\’". Prompt for the - name of the new tag using the highest existing tag as initial input - and call "git tag –annotate –sign -m MSG" TAG, regardless of - whether these arguments are enabled in the popup. Given a TAG - "v1.2.3" and a repository "/path/to/foo-bar", the MESSAGE would be - "Foo-Bar 1.2.3". - - Because it is so opinionated, this command is not available from - the tag popup by default. - - -File: magit.info, Node: Notes, Next: Submodules, Prev: Tagging, Up: Miscellaneous - -8.2 Notes -========= - -Also see *note (gitman)git-notes::. - -‘T’ (‘magit-notes-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - -‘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. - -‘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. - -‘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". - -‘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 popup features the -following suffix commands, instead of those listed above. - -‘T c’ (‘magit-notes-merge-commit’) - - Commit the current notes ref merge, after manually resolving - conflicts. - -‘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). - - -File: magit.info, Node: Submodules, Next: Subtree, Prev: Notes, Up: Miscellaneous - -8.3 Submodules -============== - -Also see *note (gitman)git-submodule::. - -* Menu: - -* Listing Submodules:: -* Submodule Popup:: - - -File: magit.info, Node: Listing Submodules, Next: Submodule Popup, Up: Submodules - -8.3.1 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-submodules’ to the hook -‘magit-status-sections-hook’ as described in *note Status Module -Sections::. - - -- Command: magit-list-submodules - - This command displays a list of the current repository’s 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’ and ‘:pad-right’. - - -- Function: magit-insert-submodules - - 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. - - -File: magit.info, Node: Submodule Popup, Prev: Listing Submodules, Up: Submodules - -8.3.2 Submodule Popup ---------------------- - -‘o’ (‘magit-submodule-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - 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. - -‘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. - -‘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. - -‘o p’ (‘magit-submodule-populate’) - - This command creates the working directory or directories of the - selected modules, checking out the recorded commits. - -‘o u’ (‘magit-submodule-update’) - - This command updates the selected modules checking out the recorded - commits. - -‘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. - -‘o d’ (‘magit-submodule-unpopulate’) - - This command removes the working directory of the selected modules. - -‘o l’ (‘magit-list-submodules’) - - This command displays a list of the current repository’s modules. - -‘o f’ (‘magit-fetch-modules’) - - This command fetches all modules. - - Option ‘magit-fetch-modules-jobs’ controls how many submodules are - being fetched in parallel. Also fetch the super-repository, - because ‘git fetch’ does not support not doing that. With a prefix - argument fetch all remotes. - - -File: magit.info, Node: Subtree, Next: Worktree, Prev: Submodules, Up: Miscellaneous - -8.4 Subtree -=========== - -Also see *note (gitman)git-subtree::. - -‘O’ (‘magit-tree-popup’) - - This prefix command shows the following suffix commands along with - the appropriate infix arguments in a popup buffer. - - Most infix arguments only apply to some of the ‘git subtree’ -subcommands. When an argument that does not apply to the invoked -command is set, then it is silently ignored. - - When the ‘--prefix’ argument is set in the popup buffer, then that is -used. Otherwise the prefix is read in the minibuffer. - -‘O a’ (‘magit-subtree-add’) - - Add COMMIT from REPOSITORY as a new subtree at PREFIX. - -‘O c’ (‘magit-subtree-add-commit’) - - Add COMMIT as a new subtree at PREFIX. - -‘O m’ (‘magit-subtree-merge’) - - Merge COMMIT into the PREFIX subtree. - -‘O f’ (‘magit-subtree-pull’) - - Pull COMMIT from REPOSITORY into the PREFIX subtree. - -‘O p’ (‘magit-subtree-push’) - - Extract the history of the subtree PREFIX and push it to REF on - REPOSITORY. - -‘O s’ (‘magit-subtree-split’) - - Extract the history of the subtree PREFIX. - - -File: magit.info, Node: Worktree, Next: Common Commands, Prev: Subtree, Up: Miscellaneous - -8.5 Worktree -============ - -Also see *note (gitman)git-worktree::. - -‘%’ (‘magit-worktree-popup’) - - This prefix command shows the following suffix commands in a popup - buffer. - -‘% b’ (‘magit-worktree-checkout’) - - Checkout BRANCH in a new worktree at PATH. - -‘% c’ (‘magit-worktree-branch’) - - Create a new BRANCH and check it out in a new worktree at PATH. - -‘% p’ (‘magit-worktree-checkout-pull-request’) - - Create, configure and checkout a new worktree from a pull-request. - - This is like ‘magit-checkout-pull-request’ (which see) except that - it also creates a new worktree. - -‘% k’ (‘magit-worktree-delete’) - - Delete a worktree, defaulting to the worktree at point. The - primary worktree cannot be deleted. - -‘% 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. - - -File: magit.info, Node: Common Commands, Next: Wip Modes, Prev: Worktree, Up: Miscellaneous - -8.6 Common Commands -=================== - -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. - -‘M-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. - -‘C-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. - - -File: magit.info, Node: Wip Modes, Next: Minor Mode for Buffers Visiting Files, Prev: Common Commands, Up: Miscellaneous - -8.7 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 three global modes that save *tracked* -files to work-in-progress references after or before certain actions. -(Untracked files are never saved and these modes also only work after -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 in place of ‘<branchref>’. - - Checking out another branch (or detaching ‘HEAD’) causes the use of -different wip refs for subsequent changes, but the old refs are not -deleted. - - Creating a commit 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 - - BI0---BI1 refs/wip/index/refs/heads/master - / - A---B refs/heads/master - \ - BW0---BW1 refs/wip/wtree/refs/heads/master - - and committing the staged changes and editing and saving a file would -result in - - 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} - - 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. - - -- 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 nil - (currently the default), then no merge is perfomed and wip refs are - reset as described above. - - If this is 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. - - *--*--*--*--*--* refs/wip/index/refs/heads/master - / / / - A-----B-----C refs/heads/master - - 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. Alternatively you can use the reflog to show -all commits that ever existed on a wip ref. You can then recover lost -changes from the commits shown in the log or reflog. - - -- 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. - - -- 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. - -‘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). - - There exists a total of three global modes that save to the wip refs, -which might seem excessive, but allows fine tuning of when exactly -changes are being committed to the wip refs. Enabling all modes makes -it less likely that a change slips through the cracks. - - Setting the following variables directly does not take effect; either -customize them or call the respective mode function. - - -- User Option: magit-wip-after-save-mode - - When this mode is enabled, then saving a buffer that visits a file - tracked in a Git repository causes its current state to be - committed to the working tree wip ref for the current branch. - - -- User Option: magit-wip-after-apply-mode - - When this mode is enabled, then applying (i.e. staging, unstaging, - discarding, reversing, and regularly applying) a change to a file - tracked in a Git repository causes its current state to be - committed to the index and/or working tree wip refs for the current - branch. - - If you only ever edit files using Emacs and only ever interact with -Git using Magit, then the above two modes should be enough to protect -each and every change from accidental loss. In practice nobody does -that. So an additional mode exists that does commit to the wip refs -before making changes that could cause the loss of earlier changes. - - -- User Option: magit-wip-before-change-mode - - When this mode is enabled, then certain commands commit the - existing changes to the files they are about to make changes to. - - -- Function: magit-wip-commit-initial-backup - - Adding this function to ‘before-save-hook’ causes the current - version of the file to be committed to the worktree wip ref before - the modifications in the buffer are saved. It backs up the same - version of the file as ‘backup-buffer’ would but, instead of using - a backup file as ‘backup-buffer’ would, it uses the same worktree - wip ref as used by the various Magit Wip modes. Like - ‘backup-buffer’, it only does this once; unless you kill the buffer - and visit the file again only one backup will be created per Emacs - session. - - This function ignores the variables that affect ‘backup-buffer’ and - can be used along-side that function, which is recommended because - this function only backs up files that are tracked in a Git - repository. - - Note that even if you enable all three modes and add the above -function to the intended hook, this won’t give you perfect protection. -The most likely scenario for losing changes despite the use of these -modes 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. - -‘M-x magit-wip-commit’ (‘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-after-save-local-mode-lighter - - Mode-line lighter for ‘magit-wip-after-save-local-mode’. - - -- User Option: magit-wip-after-apply-mode-lighter - - Mode-line lighter for ‘magit-wip-after-apply-mode’. - - -- User Option: magit-wip-before-change-mode-lighter - - Mode-line lighter for ‘magit-wip-before-change-mode’. - - -- 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>’. - - -File: magit.info, Node: Minor Mode for Buffers Visiting Files, Next: Minor Mode for Buffers Visiting Blobs, Prev: Wip Modes, Up: Miscellaneous - -8.8 Minor Mode for Buffers Visiting Files -========================================= - -The ‘magit-file-mode’ enables certain Magit features in file-visiting -buffers belonging to a Git repository. It should be enabled globally -using ‘global-magit-file-mode’. Currently this mode only establishes a -few key bindings, but this might be extended in the future. - - -- User Option: magit-file-mode - - Whether to establish certain Magit key bindings in all - file-visiting buffers belonging to a Git repository. This - establishes the bindings suggested in *note Getting Started:: (but - only for file-visiting buffers), and additionally binds ‘C-c M-g’ - to ‘magit-file-popup’. - -‘C-c M-g’ (‘magit-file-popup’) - - This prefix command shows a popup buffer featuring suffix commands - that operate on the file being visited in the current buffer. - -‘C-c M-g s’ (‘magit-stage-file’) - - Stage all changes to the file being visited in the current buffer. - -‘C-c M-g u’ (‘magit-unstage-file’) - - Unstage all changes to the file being visited in the current - buffer. - -‘C-c M-g c’ (‘magit-commit-popup’) - - This prefix command shows suffix commands along with the - appropriate infix arguments in a popup buffer. See *note - Initiating a Commit::. - -‘C-c M-g D’ (‘magit-diff-buffer-file-popup’) - - This prefix command shows the same suffix commands and infix - arguments in a popup buffer as ‘magit-diff-popup’. But this - variant has to be called from a file-visiting buffer and the - visited file is automatically used in the popup to limit the diff - to that file. - -‘C-c M-g d’ (‘magit-diff-buffer-file’) - - This command shows the diff for the file of blob that the current - buffer visits. - - -- User Option: magit-diff-buffer-file-locked - - This option controls whether ‘magit-diff-buffer-file’ uses a - dedicated buffer. See *note Modes and Buffers::. - -‘C-c M-g L’ (‘magit-log-buffer-file-popup’) - - This prefix command shows the same suffix commands and infix - arguments in a popup buffer as ‘magit-log-popup’. But this variant - has to be called from a file-visiting buffer and the visited file - is automatically used in the popup to limit the log to that file. - -‘C-c M-g l’ (‘magit-log-buffer-file’) - - This command shows the log for the file of blob that the current - buffer visits. Renames are followed when a prefix argument is used - or when ‘--follow’ is part of ‘magit-log-arguments’. When the - region is active, the log is restricted to the selected line range. - -‘C-c M-g t’ (‘magit-log-trace-definition’) - - This command shows the log for the definition at point. - - -- User Option: magit-log-buffer-file-locked - - This option controls whether ‘magit-log-buffer-file’ uses a - dedicated buffer. See *note Modes and Buffers::. - -‘C-c M-g B’ (‘magit-blame-popup’) - - This prefix command shows all blaming suffix command along with the - appropriate infix arguments in a popup buffer. See *note - Blaming::. - -‘C-c M-g b’ (‘magit-blame’) - - This command shows for each line the revision in which it was - added. - -‘C-c M-g r’ (‘magit-blame-removal’) - - This command shows for each line the revision in which it was - removed. This command is only available in blob-visiting buffers. - -‘C-c M-g f’ (‘magit-blame-reverse’) - - This command shows for each line the last revision in which it - still exists. This command is only available in blob-visiting - buffers. - -‘C-c M-g e’ (‘magit-edit-line-commit’) - - This command makes the commit editable that added the current line. - - With a prefix argument it makes the commit editable that removes - the line, if any. The commit is determined using ‘git blame’ and - made editable using ‘git rebase --interactive’ if it is reachable - from ‘HEAD’, or by checking out the commit (or a branch that points - at it) otherwise. - -‘C-c M-g p’ (‘magit-blob-previous’) - - Visit the previous blob which modified the current file. - - There are a few additional commands that operate on a single file but -are not available from the file popup by default: - - -- Command: magit-file-rename - - This command renames a file read from the user. - - -- Command: magit-file-delete - - This command deletes a file read from the user. - - -- Command: magit-file-untrack - - This command untracks a file read from the user. - - -- Command: magit-file-checkout - - This command updates a file in the working tree and index to the - contents from a revision. Both the revision and file are read from - the user. - - You could add them to the popup like so: - - (magit-define-popup-action 'magit-file-popup - ?R "Rename file" 'magit-file-rename) - (magit-define-popup-action 'magit-file-popup - ?K "Delete file" 'magit-file-delete) - (magit-define-popup-action 'magit-file-popup - ?U "Untrack file" 'magit-file-untrack) - (magit-define-popup-action 'magit-file-popup - ?C "Checkout file" 'magit-file-checkout) - - -File: magit.info, Node: Minor Mode for Buffers Visiting Blobs, Prev: Minor Mode for Buffers Visiting Files, Up: Miscellaneous - -8.9 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. - -‘p’ (‘magit-blob-previous’) - - Visit the previous blob which modified the current file. - -‘n’ (‘magit-blob-next’) - - Visit the next blob which modified the current file. - -‘q’ (‘magit-kill-this-buffer’) - - Kill the current buffer. - - -File: magit.info, Node: Customizing, Next: Plumbing, Prev: Miscellaneous, Up: Top - -9 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 popup buffers. In - this case the ‘--prune’ argument in ‘magit-fetch-popup’ might be - active or inactive depending on the value of - ‘magit-fetch-arguments’ only, 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. - -* Menu: - -* Per-Repository Configuration:: -* Essential Settings:: - - -File: magit.info, Node: Per-Repository Configuration, Next: Essential Settings, Up: Customizing - -9.1 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 *note (gitman)git-config::. - - Similarly, Emacs options can be set for one repository only by -editing ‘/path/to/repo/.dir-locals.el’. See *note (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’ - - ((nil . ((magit-refresh-buffers . nil)))) - - 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’ - - [include] - path = /path/to/huge-gitconfig - - • ‘/path/to/huge-gitconfig’ - - [status] - showUntrackedFiles = no - - • ‘$HOME/.emacs.d/init.el’ - - (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) - - -File: magit.info, Node: Essential Settings, Prev: Per-Repository Configuration, Up: Customizing - -9.2 Essential Settings -====================== - -The next two sections list and discuss several variables that many users -might want to customize, for safety and/or performance reasons. - -* Menu: - -* Safety:: -* Performance:: - - -File: magit.info, Node: Safety, Next: Performance, Up: Essential Settings - -9.2.1 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 *note 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 *note 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 the 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 *note Risk of Reverting -Automatically::. - - -File: magit.info, Node: Performance, Prev: Safety, Up: Essential Settings - -9.2.2 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. - - I plan to do that in time for the next major release. I also intend -to create logs and diffs asynchronously, which should also help a lot -but also requires 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. - - (setq magit-refresh-status-buffer nil) - - You should also check whether any third-party packages have added -anything to ‘magit-refresh-buffer-hook’, ‘magit-status-refresh-hook’, -‘magit-pre-refresh-hook’, and ‘magit-post-refresh-hook’. If so, then -check whether those additions impact performance significantly. Setting -‘magit-refresh-verbose’ and then inspecting the output in the -‘*Messages*’ buffer, should help doing so. - - 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. - - (setq auto-revert-buffer-list-filter - 'magit-auto-revert-repository-buffers-p) - - For alternative approaches see *note 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 *note -Per-Repository Configuration::. - -* Menu: - -* Microsoft Windows Performance:: -* MacOS Performance:: - -Log Performance -............... - -When showing logs, Magit limits the number of commits initially shown in -the hope that this avoids unnecessary work. When using ‘--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 -(<http://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. - - In repositories with more than a few thousand commits ‘--graph’ -should never be a member of ‘magit-log-section-arguments’. That -variable is used in the status buffer which is refreshed every time you -run any Magit command. - - 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 -................ - -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’. - -Refs Buffer Performance -....................... - -When refreshing the "references buffer" is slow, then that’s usually -because several hundred refs are being displayed. The best way to -address that is to display fewer refs, obviously. - - If you are not, or only mildly, interested in seeing the list of -tags, then start by not displaying them: - - (remove-hook 'magit-refs-sections-hook 'magit-insert-tags) - - 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 -...................... - -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: - - (remove-hook 'server-switch-hook 'magit-commit-diff) - - 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. - -The Built-In VC Package -....................... - -Emacs comes with a version control interface called "VC", see *note -(emacs)Version Control::. It is enabled be default, and if you don’t -use it in addition to Magit, then you should disable it to keep it from -performing unnecessary work: - - (setq vc-handled-backends nil) - - You can also disable its use for Git but keep using it when using -another version control system: - - (setq vc-handled-backends (delq 'Git vc-handled-backends)) - |