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.90.1 (v2.90.1-9-gd2c84d9a5+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 Melpa::
|
* 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::
|
* Auxiliary 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::
|
|
|
Wip Modes
|
|
* Wip Graph::
|
* Legacy Wip Modes::
|
|
|
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 Melpa::
|
* Installing from the Git Repository::
|
* Post-Installation Tasks::
|
|
|
File: magit.info, Node: Installing from Melpa, Next: Installing from the Git Repository, Up: Installation
|
|
2.1 Installing from Melpa
|
=========================
|
|
Magit is available from Melpa and Melpa-Stable. If you haven’t used
|
Emacs’ package manager before, then it is high time you familiarize
|
yourself with it by reading the documentation in the Emacs manual, see
|
*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 Melpa, Up: Installation
|
|
2.2 Installing from the Git Repository
|
======================================
|
|
Magit depends on the ‘dash’, ‘ghub’, ‘graphql’, ‘magit-popup’, ‘treepy’
|
and ‘with-editor’ libraries which are available from Melpa and
|
Melpa-Stable. Install them using ‘M-x package-install RET <package>
|
RET’. Of course you may also install them manually from their
|
repository.
|
|
Then clone the Magit repository:
|
|
$ 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’, ‘ghub’, ‘graphql’, ‘magit-popup’,
|
‘treepy’ 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/ghub
|
LOAD_PATH += -L /path/to/graphql
|
LOAD_PATH += -L /path/to/magit-popup
|
LOAD_PATH += -L /path/to/treepy
|
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*. It’s usually from this buffer that
|
the user invokes Git commands, or creates or visits other buffers.
|
|
In this manual we often speak about "Magit buffers". By that we mean
|
buffers whose major-modes derive from ‘magit-mode’.
|
|
‘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-other’)
|
|
Show log for one or more revs read from the minibuffer. The user
|
can input any revision or revisions separated by a space, or even
|
ranges, but only branches, tags, and a representation of the commit
|
at point are available as completion candidates.
|
|
‘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 or another ref.
|
|
‘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-range’)
|
|
Show differences between two commits.
|
|
RANGE should be a range (A..B or A...B) but can also be a single
|
commit. If one side of the range is omitted, then it defaults to
|
‘HEAD’. If just a commit is given, then changes in the working
|
tree relative to that commit are shown.
|
|
If the region is active, use the revisions on the first and last
|
line of the region. With a prefix argument, instead of diffing the
|
revisions, choose a revision to view changes along, starting at the
|
common ancestor of both revisions (i.e., use a "..." range).
|
|
‘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.
|
|
-- User Option: magit-log-trace-definition-function
|
|
The function used by ‘magit-log-trace-definition’ to determine the
|
function at point. For major-modes that have special needs, you
|
could set that using the mode’s hook.
|
|
‘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 adjust tab width. Use ‘tab-width’s value from the
|
Magit buffer itself instead.
|
|
• ‘t’ If the corresponding file-visiting buffer exits, then use
|
‘tab-width’’s value from that buffer. Doing this is cheap, so
|
this value is used even if a corresponding cache entry exists.
|
|
• ‘always’ If there is no such buffer, then temporarily visit
|
the file to determine the value.
|
|
• NUMBER Like ‘always’, but don’t visit files larger than NUMBER
|
bytes.
|
|
-- User Option: magit-diff-paint-whitespace
|
|
Specify where to highlight whitespace errors.
|
|
See ‘magit-diff-highlight-trailing’,
|
‘magit-diff-highlight-indentation’. The symbol ‘t’ means in all
|
diffs, ‘status’ means only in the status buffer, and nil means
|
nowhere.
|
|
-- 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 branches in revision buffers.
|
|
• ‘nil’ Don’t show any related branches.
|
|
• ‘t’ Show related local branches.
|
|
• ‘all’ Show related local and remote branches.
|
|
• ‘mixed’ Show all containing branches and local merged
|
branches.
|
|
-- User Option: magit-revision-show-gravatars
|
|
Whether to show gravatar images in revision buffers.
|
|
If ‘nil’, then don’t insert any gravatar images. If ‘t’, then
|
insert both images. If ‘author’ or ‘committer’, then insert only
|
the respective image.
|
|
If you have customized the option ‘magit-revision-header-format’
|
and want to insert the images then you might also have to specify
|
where to do so. In that case the value has to be a cons-cell of
|
two regular expressions. The car specifies where to insert the
|
author’s image. The top half of the image is inserted right after
|
the matched text, the bottom half on the next line in the same
|
column. The cdr specifies where to insert the committer’s image,
|
accordingly. Either the car or the cdr may be nil."
|
|
-- User Option: magit-revision-use-hash-sections
|
|
Whether to turn hashes inside the commit message into sections.
|
|
If non-nil, then hashes inside the commit message are turned into
|
‘commit’ sections. There is a trade off to be made between
|
performance and reliability:
|
|
• ‘slow’ calls git for every word to be absolutely sure.
|
|
• ‘quick’ skips words less than seven characters long.
|
|
• ‘quicker’ additionally skips words that don’t contain a
|
number.
|
|
• ‘quickest’ uses all words that are at least seven characters
|
long and which contain at least one number as well as at least
|
one letter.
|
|
If nil, then no hashes are turned into sections, but you can still
|
visit the commit at point using "RET".
|
|
The diffs shown in the revision buffer may be automatically
|
restricted to a subset of the changed files. If the revision buffer is
|
displayed from a log buffer, the revision buffer will share the same
|
file restriction as that log buffer (also see the command
|
‘magit-diff-toggle-file-filter’). 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 preceding the list of its branches.
|
|
-- User Option: magit-refs-primary-column-width
|
|
Width of the primary column in ‘magit-refs-mode’ buffers. The
|
primary column is the column that contains the name of the branch
|
that the current row is about.
|
|
If this is an integer, then the column is that many columns wide.
|
Otherwise it has to be a cons-cell of two integers. The first
|
specifies the minimal width, the second the maximal width. In that
|
case the actual width is determined using the length of the names
|
of the shown local branches. (Remote branches and tags are not
|
taken into account when calculating to optimal width.)
|
|
-- User Option: magit-refs-focus-column-width
|
|
Width of the focus column in ‘magit-refs-mode’ buffers.
|
|
The focus column is the first column, which marks one branch
|
(usually the current branch) as the focused branch using ‘*’ or
|
‘@’. For each other reference, this column optionally shows how
|
many commits it is ahead of the focused branch and ‘<’, or if it
|
isn’t ahead then the commits it is behind and ‘>’, or if it isn’t
|
behind either, then a ‘=’.
|
|
This column may also display only ‘*’ or ‘@’ for the focused
|
branch, in which case this option is ignored. Use ‘L v’ to change
|
the verbosity of this column.
|
|
-- User Option: magit-refs-margin
|
|
This option specifies whether the margin is initially shown in
|
Magit-Refs mode buffers and how it is formatted.
|
|
The value has the form ‘(INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH)’.
|
|
• If INIT is non-nil, then the margin is shown initially.
|
|
• STYLE controls how to format the 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-addition
|
|
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-addition’ except that it doesn’t
|
turn on ‘read-only-mode’ and that it initially uses the
|
visualization style specified by option ‘magit-blame-echo-style’.
|
|
-- 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-addition’, 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-addition’, 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’)
|
|
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::
|
* Auxiliary 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’)
|
|
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: Auxiliary 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: Auxiliary Branch Commands, Prev: The Branch Config Popup, Up: Branching
|
|
6.5.4 Auxiliary Branch Commands
|
-------------------------------
|
|
These commands are not available from the branch popup by default.
|
|
-- Command: magit-branch-shelve
|
|
This command shelves a branch. This is done by deleting the
|
branch, and creating a new reference "refs/shelved/BRANCH-NAME"
|
pointing at the same commit as the branch pointed at. If the
|
deleted branch had a reflog, then that is preserved as the reflog
|
of the new reference.
|
|
This is useful if you want to move a branch out of sight, but are
|
not ready to completely discard it yet.
|
|
-- Command: magit-branch-unshelve
|
|
This command unshelves a branch that was previously shelved using
|
‘magit-branch-shelve’. This is done by deleting the reference
|
"refs/shelved/BRANCH-NAME" and creating a branch "BRANCH-NAME"
|
pointing at the same commit as the deleted reference pointed at.
|
If the deleted reference had a reflog, then that is restored as the
|
reflog of the branch.
|
|
|
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-plain’)
|
|
This command merges another branch or an arbitrary revision into
|
the current branch. The branch or revision to be merged is read in
|
the minibuffer and defaults to the branch at point.
|
|
Unless there are conflicts or a prefix argument is used, then the
|
resulting merge commit uses a generic commit message, and the user
|
does not get a chance to inspect or change it before the commit is
|
created. With a prefix argument this does not actually create the
|
merge commit, which makes it possible to inspect how conflicts were
|
resolved and to adjust the commit message.
|
|
‘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-branch’)
|
|
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-copy’)
|
|
This command copies COMMITS from another branch onto the current
|
branch. If the region selects multiple commits, then those are
|
copied, without prompting. Otherwise the user is prompted for a
|
commit or range, defaulting to the commit at point.
|
|
‘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-and-commit’)
|
|
Revert a commit by creating a new commit. Prompt for a commit,
|
defaulting to the commit at point. If the region selects multiple
|
commits, then revert all of them, without prompting.
|
|
‘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-quickly’)
|
|
Reset the ‘HEAD’ and index to some commit read from the user and
|
defaulting to the commit at point, and possibly also reset the
|
working tree. With a prefix argument reset the working tree
|
otherwise don’t.
|
|
‘X m’ (‘magit-reset-mixed’)
|
|
Reset the ‘HEAD’ and index to some commit read from the user and
|
defaulting to the commit at point. The working tree is kept as-is.
|
|
‘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-both’)
|
|
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-both’)
|
|
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-other’)
|
|
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-branch’)
|
|
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-other’)
|
|
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’)
|
|
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 a global mode that saves *tracked*
|
files to work-in-progress references after or before certain actions.
|
(At present untracked files are never saved and for technical reasons
|
nothing is saved before the first commit has been created).
|
|
Two separate work-in-progress references are used to track the state
|
of the index and of the working tree: ‘refs/wip/index/<branchref>’ and
|
‘refs/wip/wtree/<branchref>’, where ‘<branchref>’ is the full ref of the
|
current branch, e.g. ‘refs/heads/master’. When the ‘HEAD’ is detached
|
then ‘HEAD’ is used in place of ‘<branchref>’.
|
|
Checking out another branch (or detaching ‘HEAD’) causes the use of
|
different wip refs for subsequent changes.
|
|
-- User Option: magit-wip-mode
|
|
When this mode is enabled, then uncommitted changes are committed
|
to dedicated work-in-progress refs whenever appropriate (i.e. when
|
dataloss would be a possibility otherwise).
|
|
Setting this variable directly does not take effect; either use the
|
Custom interface to do so or call the respective mode function.
|
|
For historic reasons this mode is implemented on top of four other
|
‘magit-wip-*’ modes, which can also be used individually, if you
|
want finer control over when the wip refs are updated; but that is
|
discouraged. See *note Legacy Wip Modes::.
|
|
To view the log for a branch and its wip refs use the commands
|
‘magit-wip-log’ and ‘magit-wip-log-current’. You should use ‘--graph’
|
when using these commands.
|
|
-- Command: magit-wip-log
|
|
This command shows the log for a branch and its wip refs. With a
|
negative prefix argument only the worktree wip ref is shown.
|
|
The absolute numeric value of the prefix argument controls how many
|
"branches" of each wip ref are shown. This is only relevant if the
|
value of ‘magit-wip-merge-branch’ is ‘nil’.
|
|
-- Command: magit-wip-log-current
|
|
This command shows the log for the current branch and its wip refs.
|
With a negative prefix argument only the worktree wip ref is shown.
|
|
The absolute numeric value of the prefix argument controls how many
|
"branches" of each wip ref are shown. This is only relevant if the
|
value of ‘magit-wip-merge-branch’ is ‘nil’.
|
|
‘X w’ (‘magit-reset-worktree’)
|
|
This command resets the working tree to some commit read from the
|
user and defaulting to the commit at point, while keeping the
|
‘HEAD’ and index as-is.
|
|
This can be used to restore files to the state committed to a wip
|
ref. Note that this will discard any unstaged changes that might
|
have existed before invoking this command (but of course only after
|
committing that to the working tree wip ref).
|
|
Note that even if you enable ‘magit-wip-mode’ this won’t give you
|
perfect protection. The most likely scenario for losing changes despite
|
the use of ‘magit-wip-mode’ is making a change outside Emacs and then
|
destroying it also outside Emacs. In some such a scenario, Magit, being
|
an Emacs package, didn’t get the opportunity to keep you from shooting
|
yourself in the foot.
|
|
When you are unsure whether Magit did commit a change to the wip
|
refs, then you can explicitly request that all changes to all tracked
|
files are being committed.
|
|
‘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-namespace
|
|
The namespace used for work-in-progress refs. It has to end with a
|
slash. The wip refs are named ‘<namespace>index/<branchref>’ and
|
‘<namespace>wtree/<branchref>’. When snapshots are created while
|
the ‘HEAD’ is detached then ‘HEAD’ is used in place of
|
‘<branchref>’.
|
|
-- User Option: magit-wip-mode-lighter
|
|
Mode-line lighter for ‘magit-wip--mode’.
|
|
* Menu:
|
|
* Wip Graph::
|
* Legacy Wip Modes::
|
|
|
File: magit.info, Node: Wip Graph, Next: Legacy Wip Modes, Up: Wip Modes
|
|
8.7.1 Wip Graph
|
---------------
|
|
-- User Option: magit-wip-merge-branch
|
|
This option controls whether the current branch is merged into the
|
wip refs after a new commit was created on the branch.
|
|
If non-nil and the current branch has new commits, then it is
|
merged into the wip ref before creating a new wip commit. This
|
makes it easier to inspect wip history and the wip commits are
|
never garbage collected.
|
|
If nil and the current branch has new commits, then the wip ref is
|
reset to the tip of the branch before creating a new wip commit.
|
With this setting wip commits are eventually garbage collected.
|
|
When ‘magit-wip-merge-branch’ is ‘t’, then the history looks like
|
this:
|
|
*--*--*--*--*--* refs/wip/index/refs/heads/master
|
/ / /
|
A-----B-----C refs/heads/master
|
|
When ‘magit-wip-merge-branch’ is ‘nil’, then creating a commit on the
|
real branch and then making a change causes the wip refs to be recreated
|
to fork from the new commit. But the old commits on the wip refs are
|
not lost. They are still available from the reflog. To make it easier
|
to see when the fork point of a wip ref was changed, an additional
|
commit with the message "restart autosaving" is created on it (‘xxO’
|
commits below are such boundary commits).
|
|
Starting with
|
|
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.
|
|
|
File: magit.info, Node: Legacy Wip Modes, Prev: Wip Graph, Up: Wip Modes
|
|
8.7.2 Legacy Wip Modes
|
----------------------
|
|
It is recommended that you use the mode ‘magit-wip-mode’ (which see) and
|
ignore the existence of the following modes, which are preserved for
|
historic reasons.
|
|
Setting the following variables directly does not take effect; either
|
use the Custom interface to do so or call the respective mode functions.
|
|
-- 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. Two additional modes exists that do 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.
|
|
-- User Option: magit-wip-initial-backup-mode
|
|
When this mode is enabled, then the current version of a file is
|
committed to the worktree wip ref before the buffer visiting that
|
file is saved for the first time since the buffer was created.
|
|
This backs up the same version of the file that ‘backup-buffer’
|
would save. While ‘backup-buffer’ uses a backup file, this mode
|
uses the same worktree wip ref as used by the other 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 mode ignores the variables that affect ‘backup-buffer’ and can
|
be used along-side that function, which is recommended because it
|
only backs up files that are tracked in a Git repository.
|
|
-- 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-initial-backup-mode-lighter
|
|
Mode-line lighter for ‘magit-wip-initial-backup-mode’.
|
|
|
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-addition’)
|
|
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))
|
