mirror of https://tildegit.org/ben/dotfiles
2688 lines
152 KiB
Plaintext
2688 lines
152 KiB
Plaintext
|
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: Microsoft Windows Performance, Next: MacOS Performance, Up: Performance
|
|||
|
|
|||
|
Microsoft Windows Performance
|
|||
|
.............................
|
|||
|
|
|||
|
In order to update the status buffer, ‘git’ has to be run a few dozen
|
|||
|
times. That is problematic on Microsoft Windows, because that operating
|
|||
|
system is exceptionally slow at starting processes. Sadly this is an
|
|||
|
issue that can only be fixed by Microsoft itself, and they don’t appear
|
|||
|
to be particularly interested in doing so.
|
|||
|
|
|||
|
Beside the subprocess issue, there are also other Windows-specific
|
|||
|
performance issues. Some of these have workarounds. The maintainers of
|
|||
|
"Git for Windows" try to improve performance on Windows. Always use the
|
|||
|
latest release in order to benefit from the latest performance tweaks.
|
|||
|
Magit too tries to work around some Windows-specific issues.
|
|||
|
|
|||
|
According to some sources, setting the following Git variables can
|
|||
|
also help.
|
|||
|
|
|||
|
git config --global core.preloadindex true # default since v2.1
|
|||
|
git config --global core.fscache true # default since v2.8
|
|||
|
git config --global gc.auto 256
|
|||
|
|
|||
|
You should also check whether an anti-virus program is affecting
|
|||
|
performance.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: MacOS Performance, Prev: Microsoft Windows Performance, Up: Performance
|
|||
|
|
|||
|
MacOS Performance
|
|||
|
.................
|
|||
|
|
|||
|
On macOS Emacs currently creates child processes using ‘fork’. It
|
|||
|
appears that this also copies GUI resources. The result is that forking
|
|||
|
takes about 30 times as long on Darwin than on Linux. And because Magit
|
|||
|
starts many ‘git’ processes even when doing simple things, that makes
|
|||
|
quite a difference.
|
|||
|
|
|||
|
On the ‘master’ branch Emacs now uses ‘vfork’ when possible, like
|
|||
|
this was already done on Linux, and now child creation only takes about
|
|||
|
twice as long on Darwin. See (1) for more information.
|
|||
|
|
|||
|
Nobody knows when the changes on the ‘master’ branch will be released
|
|||
|
as ‘26.1’, but it is still a long way off. You might want to get your
|
|||
|
hands on this change before then. The easiest way to get a patched
|
|||
|
Emacs is to install the ‘emacs-plus’ formula (2) using ‘homebrew’. The
|
|||
|
change has been backported, so you get it not only when using ‘--HEAD’,
|
|||
|
but also when using ‘--devel’ or when installing the latest release (by
|
|||
|
not using a version argument).
|
|||
|
|
|||
|
Alternatively you can apply the backport (3) manually.
|
|||
|
|
|||
|
---------- Footnotes ----------
|
|||
|
|
|||
|
(1)
|
|||
|
<https://lists.gnu.org/archive/html/bug-gnu-emacs/2017-04/msg00201.html>
|
|||
|
|
|||
|
(2) <https://github.com/d12frosted/homebrew-emacs-plus>
|
|||
|
|
|||
|
(3)
|
|||
|
<https://gist.githubusercontent.com/aaronjensen/f45894ddf431ecbff78b1bcf533d3e6b/raw/6a5cd7f57341aba673234348d8b0d2e776f86719/Emacs-25-OS-X-use-vfork.patch>
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Plumbing, Next: FAQ, Prev: Customizing, Up: Top
|
|||
|
|
|||
|
10 Plumbing
|
|||
|
***********
|
|||
|
|
|||
|
The following sections describe how to use several of Magit’s core
|
|||
|
abstractions to extend Magit itself or implement a separate extension.
|
|||
|
|
|||
|
A few of the low-level features used by Magit have been factored out
|
|||
|
into separate libraries/packages, so that they can be used by other
|
|||
|
packages, without having to depend on Magit. These libraries are
|
|||
|
described in separate manuals, see *note (with-editor)Top:: and *note
|
|||
|
(magit-popup)Top::.
|
|||
|
|
|||
|
If you are trying to find an unused key that you can bind to a
|
|||
|
command provided by your own Magit extension, then checkout
|
|||
|
<https://github.com/magit/magit/wiki/Plugin-Dispatch-Key-Registry>.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Calling Git::
|
|||
|
* Section Plumbing::
|
|||
|
* Refreshing Buffers::
|
|||
|
* Conventions::
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Calling Git, Next: Section Plumbing, Up: Plumbing
|
|||
|
|
|||
|
10.1 Calling Git
|
|||
|
================
|
|||
|
|
|||
|
Magit provides many specialized functions for calling Git. All of these
|
|||
|
functions are defined in either ‘magit-git.el’ or ‘magit-process.el’ and
|
|||
|
have one of the prefixes ‘magit-run-’, ‘magit-call-’, ‘magit-start-’, or
|
|||
|
‘magit-git-’ (which is also used for other things).
|
|||
|
|
|||
|
All of these functions accept an indefinite number of arguments,
|
|||
|
which are strings that specify command line arguments for Git (or in
|
|||
|
some cases an arbitrary executable). These arguments are flattened
|
|||
|
before being passed on to the executable; so instead of strings they can
|
|||
|
also be lists of strings and arguments that are ‘nil’ are silently
|
|||
|
dropped. Some of these functions also require a single mandatory
|
|||
|
argument before these command line arguments.
|
|||
|
|
|||
|
Roughly speaking, these functions run Git either to get some value or
|
|||
|
for side-effects. The functions that return a value are useful to
|
|||
|
collect the information necessary to populate a Magit buffer, while the
|
|||
|
others are used to implement Magit commands.
|
|||
|
|
|||
|
The functions in the value-only group always run synchronously, and
|
|||
|
they never trigger a refresh. The function in the side-effect group can
|
|||
|
be further divided into subgroups depending on whether they run Git
|
|||
|
synchronously or asynchronously, and depending on whether they trigger a
|
|||
|
refresh when the executable has finished.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Getting a Value from Git::
|
|||
|
* Calling Git for Effect::
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Getting a Value from Git, Next: Calling Git for Effect, Up: Calling Git
|
|||
|
|
|||
|
10.1.1 Getting a Value from Git
|
|||
|
-------------------------------
|
|||
|
|
|||
|
These functions run Git in order to get a value, an exit status, or
|
|||
|
output. Of course you could also use them to run Git commands that have
|
|||
|
side-effects, but that should be avoided.
|
|||
|
|
|||
|
-- Function: magit-git-exit-code &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns its exit code.
|
|||
|
|
|||
|
-- Function: magit-git-success &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns ‘t’ if the exit code is ‘0’,
|
|||
|
‘nil’ otherwise.
|
|||
|
|
|||
|
-- Function: magit-git-failure &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns ‘t’ if the exit code is ‘1’,
|
|||
|
‘nil’ otherwise.
|
|||
|
|
|||
|
-- Function: magit-git-true &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns ‘t’ if the first line printed by
|
|||
|
git is the string "true", ‘nil’ otherwise.
|
|||
|
|
|||
|
-- Function: magit-git-false &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns ‘t’ if the first line printed by
|
|||
|
git is the string "false", ‘nil’ otherwise.
|
|||
|
|
|||
|
-- Function: magit-git-insert &rest args
|
|||
|
|
|||
|
Executes git with ARGS and inserts its output at point.
|
|||
|
|
|||
|
-- Function: magit-git-string &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns the first line of its output.
|
|||
|
If there is no output or if it begins with a newline character,
|
|||
|
then this returns ‘nil’.
|
|||
|
|
|||
|
-- Function: magit-git-lines &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns its output as a list of lines.
|
|||
|
Empty lines anywhere in the output are omitted.
|
|||
|
|
|||
|
-- Function: magit-git-items &rest args
|
|||
|
|
|||
|
Executes git with ARGS and returns its null-separated output as a
|
|||
|
list. Empty items anywhere in the output are omitted.
|
|||
|
|
|||
|
If the value of option ‘magit-git-debug’ is non-nil and git exits
|
|||
|
with a non-zero exit status, then warn about that in the echo area
|
|||
|
and add a section containing git’s standard error in the current
|
|||
|
repository’s process buffer.
|
|||
|
|
|||
|
If an error occurs when using one of the above functions, then that
|
|||
|
is usually due to a bug, i.e. using an argument which is not actually
|
|||
|
supported. Such errors are usually not reported, but when they occur we
|
|||
|
need to be able to debug them.
|
|||
|
|
|||
|
-- User Option: magit-git-debug
|
|||
|
|
|||
|
Whether to report errors that occur when using ‘magit-git-insert’,
|
|||
|
‘magit-git-string’, ‘magit-git-lines’, or ‘magit-git-items’. This
|
|||
|
does not actually raise an error. Instead a message is shown in
|
|||
|
the echo area, and git’s standard error is insert into a new
|
|||
|
section in the current repository’s process buffer.
|
|||
|
|
|||
|
-- Function: magit-git-str &rest args
|
|||
|
|
|||
|
This is a variant of ‘magit-git-string’ that ignores the option
|
|||
|
‘magit-git-debug’. It is mainly intended to be used while handling
|
|||
|
errors in functions that do respect that option. Using such a
|
|||
|
function while handing an error could cause yet another error and
|
|||
|
therefore lead to an infinite recursion. You probably won’t ever
|
|||
|
need to use this function.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Calling Git for Effect, Prev: Getting a Value from Git, Up: Calling Git
|
|||
|
|
|||
|
10.1.2 Calling Git for Effect
|
|||
|
-----------------------------
|
|||
|
|
|||
|
These functions are used to run git to produce some effect. Most Magit
|
|||
|
commands that actually run git do so by using such a function.
|
|||
|
|
|||
|
Because we do not need to consume git’s output when using these
|
|||
|
functions, their output is instead logged into a per-repository buffer,
|
|||
|
which can be shown using ‘$’ from a Magit buffer or ‘M-x magit-process’
|
|||
|
elsewhere.
|
|||
|
|
|||
|
These functions can have an effect in two distinct ways. Firstly,
|
|||
|
running git may change something, i.e. create or push a new commit.
|
|||
|
Secondly, that change may require that Magit buffers are refreshed to
|
|||
|
reflect the changed state of the repository. But refreshing isn’t
|
|||
|
always desirable, so only some of these functions do perform such a
|
|||
|
refresh after git has returned.
|
|||
|
|
|||
|
Sometimes it is useful to run git asynchronously. For example, when
|
|||
|
the user has just initiated a push, then there is no reason to make her
|
|||
|
wait until that has completed. In other cases it makes sense to wait
|
|||
|
for git to complete before letting the user do something else. For
|
|||
|
example after staging a change it is useful to wait until after the
|
|||
|
refresh because that also automatically moves to the next change.
|
|||
|
|
|||
|
-- Function: magit-call-git &rest args
|
|||
|
|
|||
|
Calls git synchronously with ARGS.
|
|||
|
|
|||
|
-- Function: magit-call-process program &rest args
|
|||
|
|
|||
|
Calls PROGRAM synchronously with ARGS.
|
|||
|
|
|||
|
-- Function: magit-run-git &rest args
|
|||
|
|
|||
|
Calls git synchronously with ARGS and then refreshes.
|
|||
|
|
|||
|
-- Function: magit-run-git-with-input input &rest args
|
|||
|
|
|||
|
Calls git synchronously with ARGS and sends it INPUT on standard
|
|||
|
input.
|
|||
|
|
|||
|
INPUT should be a buffer or the name of an existing buffer. The
|
|||
|
content of that buffer is used as the process’ standard input.
|
|||
|
After the process returns a refresh is performed.
|
|||
|
|
|||
|
As a special case, INPUT may also be nil. In that case the content
|
|||
|
of the current buffer is used as standard input and *no* refresh is
|
|||
|
performed.
|
|||
|
|
|||
|
This function actually runs git asynchronously. But then it waits
|
|||
|
for the process to return, so the function itself is synchronous.
|
|||
|
|
|||
|
-- Function: magit-run-git-with-logfile file &rest args
|
|||
|
|
|||
|
Calls git synchronously with ARGS. The process’ output is saved in
|
|||
|
FILE. This is rarely useful and so this function might be removed
|
|||
|
in the future.
|
|||
|
|
|||
|
This function actually runs git asynchronously. But then it waits
|
|||
|
for the process to return, so the function itself is synchronous.
|
|||
|
|
|||
|
-- Function: magit-git &rest args
|
|||
|
|
|||
|
Calls git synchronously with ARGS for side-effects only. This
|
|||
|
function does not refresh the buffer.
|
|||
|
|
|||
|
-- Function: magit-git-wash washer &rest args
|
|||
|
|
|||
|
Execute Git with ARGS, inserting washed output at point. Actually
|
|||
|
first insert the raw output at point. If there is no output call
|
|||
|
‘magit-cancel-section’. Otherwise temporarily narrow the buffer to
|
|||
|
the inserted text, move to its beginning, and then call function
|
|||
|
WASHER with ARGS as its sole argument.
|
|||
|
|
|||
|
And now for the asynchronous variants.
|
|||
|
|
|||
|
-- Function: magit-run-git-async &rest args
|
|||
|
|
|||
|
Start Git, prepare for refresh, and return the process object.
|
|||
|
ARGS is flattened and then used as arguments to Git.
|
|||
|
|
|||
|
Display the command line arguments in the echo area.
|
|||
|
|
|||
|
After Git returns some buffers are refreshed: the buffer that was
|
|||
|
current when this function was called (if it is a Magit buffer and
|
|||
|
still alive), as well as the respective Magit status buffer.
|
|||
|
Unmodified buffers visiting files that are tracked in the current
|
|||
|
repository are reverted if ‘magit-revert-buffers’ is non-nil.
|
|||
|
|
|||
|
-- Function: magit-run-git-with-editor &rest args
|
|||
|
|
|||
|
Export GIT_EDITOR and start Git. Also prepare for refresh and
|
|||
|
return the process object. ARGS is flattened and then used as
|
|||
|
arguments to Git.
|
|||
|
|
|||
|
Display the command line arguments in the echo area.
|
|||
|
|
|||
|
After Git returns some buffers are refreshed: the buffer that was
|
|||
|
current when this function was called (if it is a Magit buffer and
|
|||
|
still alive), as well as the respective Magit status buffer.
|
|||
|
|
|||
|
-- Function: magit-start-git &rest args
|
|||
|
|
|||
|
Start Git, prepare for refresh, and return the process object.
|
|||
|
|
|||
|
If INPUT is non-nil, it has to be a buffer or the name of an
|
|||
|
existing buffer. The buffer content becomes the processes standard
|
|||
|
input.
|
|||
|
|
|||
|
Option ‘magit-git-executable’ specifies the Git executable and
|
|||
|
option ‘magit-git-global-arguments’ specifies constant arguments.
|
|||
|
The remaining arguments ARGS specify arguments to Git. They are
|
|||
|
flattened before use.
|
|||
|
|
|||
|
After Git returns, some buffers are refreshed: the buffer that was
|
|||
|
current when this function was called (if it is a Magit buffer and
|
|||
|
still alive), as well as the respective Magit status buffer.
|
|||
|
Unmodified buffers visiting files that are tracked in the current
|
|||
|
repository are reverted if ‘magit-revert-buffers’ is non-nil.
|
|||
|
|
|||
|
-- Function: magit-start-process &rest args
|
|||
|
|
|||
|
Start PROGRAM, prepare for refresh, and return the process object.
|
|||
|
|
|||
|
If optional argument INPUT is non-nil, it has to be a buffer or the
|
|||
|
name of an existing buffer. The buffer content becomes the
|
|||
|
processes standard input.
|
|||
|
|
|||
|
The process is started using ‘start-file-process’ and then setup to
|
|||
|
use the sentinel ‘magit-process-sentinel’ and the filter
|
|||
|
‘magit-process-filter’. Information required by these functions is
|
|||
|
stored in the process object. When this function returns the
|
|||
|
process has not started to run yet so it is possible to override
|
|||
|
the sentinel and filter.
|
|||
|
|
|||
|
After the process returns, ‘magit-process-sentinel’ refreshes the
|
|||
|
buffer that was current when ‘magit-start-process’ was called (if
|
|||
|
it is a Magit buffer and still alive), as well as the respective
|
|||
|
Magit status buffer. Unmodified buffers visiting files that are
|
|||
|
tracked in the current repository are reverted if
|
|||
|
‘magit-revert-buffers’ is non-nil.
|
|||
|
|
|||
|
-- Variable: magit-this-process
|
|||
|
|
|||
|
The child process which is about to start. This can be used to
|
|||
|
change the filter and sentinel.
|
|||
|
|
|||
|
-- Variable: magit-process-raise-error
|
|||
|
|
|||
|
When this is non-nil, then ‘magit-process-sentinel’ raises an error
|
|||
|
if git exits with a non-zero exit status. For debugging purposes.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Section Plumbing, Next: Refreshing Buffers, Prev: Calling Git, Up: Plumbing
|
|||
|
|
|||
|
10.2 Section Plumbing
|
|||
|
=====================
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Creating Sections::
|
|||
|
* Section Selection::
|
|||
|
* Matching Sections::
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Creating Sections, Next: Section Selection, Up: Section Plumbing
|
|||
|
|
|||
|
10.2.1 Creating Sections
|
|||
|
------------------------
|
|||
|
|
|||
|
-- Macro: magit-insert-section &rest args
|
|||
|
|
|||
|
Insert a section at point.
|
|||
|
|
|||
|
TYPE is the section type, a symbol. Many commands that act on the
|
|||
|
current section behave differently depending on that type. Also if
|
|||
|
a variable ‘magit-TYPE-section-map’ exists, then use that as the
|
|||
|
text-property ‘keymap’ of all text belonging to the section (but
|
|||
|
this may be overwritten in subsections). TYPE can also have the
|
|||
|
form ‘(eval FORM)’ in which case FORM is evaluated at runtime.
|
|||
|
|
|||
|
Optional VALUE is the value of the section, usually a string that
|
|||
|
is required when acting on the section.
|
|||
|
|
|||
|
When optional HIDE is non-nil collapse the section body by default,
|
|||
|
i.e. when first creating the section, but not when refreshing the
|
|||
|
buffer. Otherwise, expand it by default. This can be overwritten
|
|||
|
using ‘magit-section-set-visibility-hook’. When a section is
|
|||
|
recreated during a refresh, then the visibility of predecessor is
|
|||
|
inherited and HIDE is ignored (but the hook is still honored).
|
|||
|
|
|||
|
BODY is any number of forms that actually insert the section’s
|
|||
|
heading and body. Optional NAME, if specified, has to be a symbol,
|
|||
|
which is then bound to the struct of the section being inserted.
|
|||
|
|
|||
|
Before BODY is evaluated the ‘start’ of the section object is set
|
|||
|
to the value of ‘point’ and after BODY was evaluated its ‘end’ is
|
|||
|
set to the new value of ‘point’; BODY is responsible for moving
|
|||
|
‘point’ forward.
|
|||
|
|
|||
|
If it turns out inside BODY that the section is empty, then
|
|||
|
‘magit-cancel-section’ can be used to abort and remove all traces
|
|||
|
of the partially inserted section. This can happen when creating a
|
|||
|
section by washing Git’s output and Git didn’t actually output
|
|||
|
anything this time around.
|
|||
|
|
|||
|
-- Function: magit-insert-heading &rest args
|
|||
|
|
|||
|
Insert the heading for the section currently being inserted.
|
|||
|
|
|||
|
This function should only be used inside ‘magit-insert-section’.
|
|||
|
|
|||
|
When called without any arguments, then just set the ‘content’ slot
|
|||
|
of the object representing the section being inserted to a marker
|
|||
|
at ‘point’. The section should only contain a single line when
|
|||
|
this function is used like this.
|
|||
|
|
|||
|
When called with arguments ARGS, which have to be strings, then
|
|||
|
insert those strings at point. The section should not contain any
|
|||
|
text before this happens and afterwards it should again only
|
|||
|
contain a single line. If the ‘face’ property is set anywhere
|
|||
|
inside any of these strings, then insert all of them unchanged.
|
|||
|
Otherwise use the ‘magit-section-heading’ face for all inserted
|
|||
|
text.
|
|||
|
|
|||
|
The ‘content’ property of the section struct is the end of the
|
|||
|
heading (which lasts from ‘start’ to ‘content’) and the beginning
|
|||
|
of the body (which lasts from ‘content’ to ‘end’). If the value of
|
|||
|
‘content’ is nil, then the section has no heading and its body
|
|||
|
cannot be collapsed. If a section does have a heading then its
|
|||
|
height must be exactly one line, including a trailing newline
|
|||
|
character. This isn’t enforced; you are responsible for getting it
|
|||
|
right. The only exception is that this function does insert a
|
|||
|
newline character if necessary.
|
|||
|
|
|||
|
-- Function: magit-cancel-section
|
|||
|
|
|||
|
Cancel the section currently being inserted. This exits the
|
|||
|
innermost call to ‘magit-insert-section’ and removes all traces of
|
|||
|
what has already happened inside that call.
|
|||
|
|
|||
|
-- Function: magit-define-section-jumper sym title &optional value
|
|||
|
|
|||
|
Define an interactive function to go to section SYM. TITLE is the
|
|||
|
displayed title of the section.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Section Selection, Next: Matching Sections, Prev: Creating Sections, Up: Section Plumbing
|
|||
|
|
|||
|
10.2.2 Section Selection
|
|||
|
------------------------
|
|||
|
|
|||
|
-- Function: magit-current-section
|
|||
|
|
|||
|
Return the section at point.
|
|||
|
|
|||
|
-- Function: magit-region-sections &optional condition multiple
|
|||
|
|
|||
|
Return a list of the selected sections.
|
|||
|
|
|||
|
When the region is active and constitutes a valid section
|
|||
|
selection, then return a list of all selected sections. This is
|
|||
|
the case when the region begins in the heading of a section and
|
|||
|
ends in the heading of the same section or in that of a sibling
|
|||
|
section. If optional MULTIPLE is non-nil, then the region cannot
|
|||
|
begin and end in the same section.
|
|||
|
|
|||
|
When the selection is not valid, then return nil. In this case,
|
|||
|
most commands that can act on the selected sections will instead
|
|||
|
act on the section at point.
|
|||
|
|
|||
|
When the region looks like it would in any other buffer then the
|
|||
|
selection is invalid. When the selection is valid then the region
|
|||
|
uses the ‘magit-section-highlight’ face. This does not apply to
|
|||
|
diffs where things get a bit more complicated, but even here if the
|
|||
|
region looks like it usually does, then that’s not a valid
|
|||
|
selection as far as this function is concerned.
|
|||
|
|
|||
|
If optional CONDITION is non-nil, then the selection not only has
|
|||
|
to be valid; all selected sections additionally have to match
|
|||
|
CONDITION, or nil is returned. See ‘magit-section-match’ for the
|
|||
|
forms CONDITION can take.
|
|||
|
|
|||
|
-- Function: magit-region-values &optional condition multiple
|
|||
|
|
|||
|
Return a list of the values of the selected sections.
|
|||
|
|
|||
|
Return the values that themselves would be returned by
|
|||
|
‘magit-region-sections’ (which see).
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Matching Sections, Prev: Section Selection, Up: Section Plumbing
|
|||
|
|
|||
|
10.2.3 Matching Sections
|
|||
|
------------------------
|
|||
|
|
|||
|
‘M-x magit-describe-section-briefly’ (‘magit-describe-section-briefly’)
|
|||
|
|
|||
|
Show information about the section at point. This command is
|
|||
|
intended for debugging purposes.
|
|||
|
|
|||
|
-- Function: magit-section-ident section
|
|||
|
|
|||
|
Return an unique identifier for SECTION. The return value has the
|
|||
|
form ‘((TYPE . VALUE)...)’.
|
|||
|
|
|||
|
-- Function: magit-get-section ident &optional root
|
|||
|
|
|||
|
Return the section identified by IDENT. IDENT has to be a list as
|
|||
|
returned by ‘magit-section-ident’.
|
|||
|
|
|||
|
-- Function: magit-section-match condition &optional section
|
|||
|
|
|||
|
Return ‘t’ if SECTION matches CONDITION. SECTION defaults to the
|
|||
|
section at point. If SECTION is not specified and there also is no
|
|||
|
section at point, then return ‘nil’.
|
|||
|
|
|||
|
CONDITION can take the following forms:
|
|||
|
• ‘(CONDITION...)’
|
|||
|
|
|||
|
matches if any of the CONDITIONs matches.
|
|||
|
|
|||
|
• ‘[CLASS...]’
|
|||
|
|
|||
|
matches if the section’s class is the same as the first CLASS
|
|||
|
or a subclass of that; the section’s parent class matches the
|
|||
|
second CLASS; and so on.
|
|||
|
|
|||
|
• ‘[* CLASS...]’
|
|||
|
|
|||
|
matches sections that match ‘[CLASS...]’ and also recursively
|
|||
|
all their child sections.
|
|||
|
|
|||
|
• ‘CLASS’
|
|||
|
|
|||
|
matches if the section’s class is the same as CLASS or a
|
|||
|
subclass of that; regardless of the classes of the parent
|
|||
|
sections.
|
|||
|
|
|||
|
Each CLASS should be a class symbol, identifying a class that
|
|||
|
derives from ‘magit-section’. For backward compatibility CLASS can
|
|||
|
also be a "type symbol". A section matches such a symbol if the
|
|||
|
value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in
|
|||
|
‘magit--section-type-alist’, then a section also matches that type
|
|||
|
if its class is a subclass of the class that corresponds to the
|
|||
|
type as per that alist.
|
|||
|
|
|||
|
Note that it is not necessary to specify the complete section
|
|||
|
lineage as printed by ‘magit-describe-section-briefly’, unless of
|
|||
|
course you want to be that precise.
|
|||
|
|
|||
|
-- Function: magit-section-value-if condition &optional section
|
|||
|
|
|||
|
If the section at point matches CONDITION, then return its value.
|
|||
|
|
|||
|
If optional SECTION is non-nil then test whether that matches
|
|||
|
instead. If there is no section at point and SECTION is nil, then
|
|||
|
return nil. If the section does not match, then return nil.
|
|||
|
|
|||
|
See ‘magit-section-match’ for the forms CONDITION can take.
|
|||
|
|
|||
|
-- Function: magit-section-case &rest clauses
|
|||
|
|
|||
|
Choose among clauses on the type of the section at point.
|
|||
|
|
|||
|
Each clause looks like (CONDITION BODY...). The type of the
|
|||
|
section is compared against each CONDITION; the BODY forms of the
|
|||
|
first match are evaluated sequentially and the value of the last
|
|||
|
form is returned. Inside BODY the symbol ‘it’ is bound to the
|
|||
|
section at point. If no clause succeeds or if there is no section
|
|||
|
at point return nil.
|
|||
|
|
|||
|
See ‘magit-section-match’ for the forms CONDITION can take.
|
|||
|
Additionally a CONDITION of t is allowed in the final clause and
|
|||
|
matches if no other CONDITION match, even if there is no section at
|
|||
|
point.
|
|||
|
|
|||
|
-- Variable: magit-root-section
|
|||
|
|
|||
|
The root section in the current buffer. All other sections are
|
|||
|
descendants of this section. The value of this variable is set by
|
|||
|
‘magit-insert-section’ and you should never modify it.
|
|||
|
|
|||
|
For diff related sections a few additional tools exist.
|
|||
|
|
|||
|
-- Function: magit-diff-type &optional section
|
|||
|
|
|||
|
Return the diff type of SECTION.
|
|||
|
|
|||
|
The returned type is one of the symbols ‘staged’, ‘unstaged’,
|
|||
|
‘committed’, or ‘undefined’. This type serves a similar purpose as
|
|||
|
the general type common to all sections (which is stored in the
|
|||
|
‘type’ slot of the corresponding ‘magit-section’ struct) but takes
|
|||
|
additional information into account. When the SECTION isn’t
|
|||
|
related to diffs and the buffer containing it also isn’t a
|
|||
|
diff-only buffer, then return nil.
|
|||
|
|
|||
|
Currently the type can also be one of ‘tracked’ and ‘untracked’,
|
|||
|
but these values are not handled explicitly in every place they
|
|||
|
should be. A possible fix could be to just return nil here.
|
|||
|
|
|||
|
The section has to be a ‘diff’ or ‘hunk’ section, or a section
|
|||
|
whose children are of type ‘diff’. If optional SECTION is nil,
|
|||
|
return the diff type for the current section. In buffers whose
|
|||
|
major mode is ‘magit-diff-mode’ SECTION is ignored and the type is
|
|||
|
determined using other means. In ‘magit-revision-mode’ buffers the
|
|||
|
type is always ‘committed’.
|
|||
|
|
|||
|
-- Function: magit-diff-scope &optional section strict
|
|||
|
|
|||
|
Return the diff scope of SECTION or the selected section(s).
|
|||
|
|
|||
|
A diff’s "scope" describes what part of a diff is selected, it is a
|
|||
|
symbol, one of ‘region’, ‘hunk’, ‘hunks’, ‘file’, ‘files’, or
|
|||
|
‘list’. Do not confuse this with the diff "type", as returned by
|
|||
|
‘magit-diff-type’.
|
|||
|
|
|||
|
If optional SECTION is non-nil, then return the scope of that,
|
|||
|
ignoring the sections selected by the region. Otherwise return the
|
|||
|
scope of the current section, or if the region is active and
|
|||
|
selects a valid group of diff related sections, the type of these
|
|||
|
sections, i.e. ‘hunks’ or ‘files’. If SECTION (or if the current
|
|||
|
section that is nil) is a ‘hunk’ section and the region starts and
|
|||
|
ends inside the body of a that section, then the type is ‘region’.
|
|||
|
|
|||
|
If optional STRICT is non-nil then return nil if the diff type of
|
|||
|
the section at point is ‘untracked’ or the section at point is not
|
|||
|
actually a ‘diff’ but a ‘diffstat’ section.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Refreshing Buffers, Next: Conventions, Prev: Section Plumbing, Up: Plumbing
|
|||
|
|
|||
|
10.3 Refreshing Buffers
|
|||
|
=======================
|
|||
|
|
|||
|
All commands that create a new Magit buffer or change what is being
|
|||
|
displayed in an existing buffer do so by calling ‘magit-mode-setup’.
|
|||
|
Among other things, that function sets the buffer local values of
|
|||
|
‘default-directory’ (to the top-level of the repository),
|
|||
|
‘magit-refresh-function’, and ‘magit-refresh-args’.
|
|||
|
|
|||
|
Buffers are refreshed by calling the function that is the local value
|
|||
|
of ‘magit-refresh-function’ (a function named ‘magit-*-refresh-buffer’,
|
|||
|
where ‘*’ may be something like ‘diff’) with the value of
|
|||
|
‘magit-refresh-args’ as arguments.
|
|||
|
|
|||
|
-- Macro: magit-mode-setup buffer switch-func mode refresh-func
|
|||
|
&optional refresh-args
|
|||
|
|
|||
|
This function displays and selects BUFFER, turns on MODE, and
|
|||
|
refreshes a first time.
|
|||
|
|
|||
|
This function displays and optionally selects BUFFER by calling
|
|||
|
‘magit-mode-display-buffer’ with BUFFER, MODE and SWITCH-FUNC as
|
|||
|
arguments. Then it sets the local value of
|
|||
|
‘magit-refresh-function’ to REFRESH-FUNC and that of
|
|||
|
‘magit-refresh-args’ to REFRESH-ARGS. Finally it creates the
|
|||
|
buffer content by calling REFRESH-FUNC with REFRESH-ARGS as
|
|||
|
arguments.
|
|||
|
|
|||
|
All arguments are evaluated before switching to BUFFER.
|
|||
|
|
|||
|
-- Function: magit-mode-display-buffer buffer mode &optional
|
|||
|
switch-function
|
|||
|
|
|||
|
This function display BUFFER in some window and select it. BUFFER
|
|||
|
may be a buffer or a string, the name of a buffer. The buffer is
|
|||
|
returned.
|
|||
|
|
|||
|
Unless BUFFER is already displayed in the selected frame, store the
|
|||
|
previous window configuration as a buffer local value, so that it
|
|||
|
can later be restored by ‘magit-mode-bury-buffer’.
|
|||
|
|
|||
|
The buffer is displayed and selected using SWITCH-FUNCTION. If
|
|||
|
that is ‘nil’ then ‘pop-to-buffer’ is used if the current buffer’s
|
|||
|
major mode derives from ‘magit-mode’. Otherwise ‘switch-to-buffer’
|
|||
|
is used.
|
|||
|
|
|||
|
-- Variable: magit-refresh-function
|
|||
|
|
|||
|
The value of this buffer-local variable is the function used to
|
|||
|
refresh the current buffer. It is called with ‘magit-refresh-args’
|
|||
|
as arguments.
|
|||
|
|
|||
|
-- Variable: magit-refresh-args
|
|||
|
|
|||
|
The list of arguments used by ‘magit-refresh-function’ to refresh
|
|||
|
the current buffer. ‘magit-refresh-function’ is called with these
|
|||
|
arguments.
|
|||
|
|
|||
|
The value is usually set using ‘magit-mode-setup’, but in some
|
|||
|
cases it’s also useful to provide commands which can change the
|
|||
|
value. For example, the ‘magit-diff-refresh-popup’ can be used to
|
|||
|
change any of the arguments used to display the diff, without
|
|||
|
having to specify again which differences should be shown.
|
|||
|
‘magit-diff-more-context’, ‘magit-diff-less-context’, and
|
|||
|
‘magit-diff-default-context’ change just the ‘-U<N>’ argument. In
|
|||
|
both case this is done by changing the value of this variable and
|
|||
|
then calling this ‘magit-refresh-function’.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Conventions, Prev: Refreshing Buffers, Up: Plumbing
|
|||
|
|
|||
|
10.4 Conventions
|
|||
|
================
|
|||
|
|
|||
|
Also see *note Completion and Confirmation::.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Theming Faces::
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Theming Faces, Up: Conventions
|
|||
|
|
|||
|
10.4.1 Theming Faces
|
|||
|
--------------------
|
|||
|
|
|||
|
The default theme uses blue for local branches, green for remote
|
|||
|
branches, and goldenrod (brownish yellow) for tags. When creating a new
|
|||
|
theme, you should probably follow that example. If your theme already
|
|||
|
uses other colors, then stick to that.
|
|||
|
|
|||
|
In older releases these reference faces used to have a background
|
|||
|
color and a box around them. The basic default faces no longer do so,
|
|||
|
to make Magit buffers much less noisy, and you should follow that
|
|||
|
example at least with regards to boxes. (Boxes were used in the past to
|
|||
|
work around a conflict between the highlighting overlay and text
|
|||
|
property backgrounds. That’s no longer necessary because highlighting
|
|||
|
no longer causes other background colors to disappear.) Alternatively
|
|||
|
you can keep the background color and/or box, but then have to take
|
|||
|
special care to adjust ‘magit-branch-current’ accordingly. By default
|
|||
|
it looks mostly like ‘magit-branch-local’, but with a box (by default
|
|||
|
the former is the only face that uses a box, exactly so that it sticks
|
|||
|
out). If the former also uses a box, then you have to make sure that it
|
|||
|
differs in some other way from the latter.
|
|||
|
|
|||
|
The most difficult faces to theme are those related to diffs,
|
|||
|
headings, highlighting, and the region. There are faces that fall into
|
|||
|
all four groups - expect to spend some time getting this right.
|
|||
|
|
|||
|
The ‘region’ face in the default theme, in both the light and dark
|
|||
|
variants, as well as in many other themes, distributed with Emacs or by
|
|||
|
third-parties, is very ugly. It is common to use a background color
|
|||
|
that really sticks out, which is ugly but if that were the only problem
|
|||
|
then it would be acceptable. Unfortunately many themes also set the
|
|||
|
foreground color, which ensures that all text within the region is
|
|||
|
readable. Without doing that there might be cases where some foreground
|
|||
|
color is too close to the region background color to still be readable.
|
|||
|
But it also means that text within the region loses all syntax
|
|||
|
highlighting.
|
|||
|
|
|||
|
I consider the work that went into getting the ‘region’ face right to
|
|||
|
be a good indicator for the general quality of a theme. My
|
|||
|
recommendation for the ‘region’ face is this: use a background color
|
|||
|
slightly different from the background color of the ‘default’ face, and
|
|||
|
do not set the foreground color at all. So for a light theme you might
|
|||
|
use a light (possibly tinted) gray as the background color of ‘default’
|
|||
|
and a somewhat darker gray for the background of ‘region’. That should
|
|||
|
usually be enough to not collide with the foreground color of any other
|
|||
|
face. But if some other faces also set a light gray as background
|
|||
|
color, then you should also make sure it doesn’t collide with those (in
|
|||
|
some cases it might be acceptable though).
|
|||
|
|
|||
|
Magit only uses the ‘region’ face when the region is "invalid" by its
|
|||
|
own definition. In a Magit buffer the region is used to either select
|
|||
|
multiple sibling sections, so that commands which support it act on all
|
|||
|
of these sections instead of just the current section, or to select
|
|||
|
lines within a single hunk section. In all other cases, the section is
|
|||
|
considered invalid and Magit won’t act on it. But such invalid sections
|
|||
|
happen, either because the user has not moved point enough yet to make
|
|||
|
it valid or because she wants to use a non-magit command to act on the
|
|||
|
region, e.g. ‘kill-region’.
|
|||
|
|
|||
|
So using the regular ‘region’ face for invalid sections is a feature.
|
|||
|
It tells the user that Magit won’t be able to act on it. It’s
|
|||
|
acceptable if that face looks a bit odd and even (but less so) if it
|
|||
|
collides with the background colors of section headings and other things
|
|||
|
that have a background color.
|
|||
|
|
|||
|
Magit highlights the current section. If a section has subsections,
|
|||
|
then all of them are highlighted. This is done using faces that have
|
|||
|
"highlight" in their names. For most sections,
|
|||
|
‘magit-section-highlight’ is used for both the body and the heading.
|
|||
|
Like the ‘region’ face, it should only set the background color to
|
|||
|
something similar to that of ‘default’. The highlight background color
|
|||
|
must be different from both the ‘region’ background color and the
|
|||
|
‘default’ background color.
|
|||
|
|
|||
|
For diff related sections Magit uses various faces to highlight
|
|||
|
different parts of the selected section(s). Note that hunk headings,
|
|||
|
unlike all other section headings, by default have a background color,
|
|||
|
because it is useful to have very visible separators between hunks.
|
|||
|
That face ‘magit-diff-hunk-heading’, should be different from both
|
|||
|
‘magit-diff-hunk-heading-highlight’ and ‘magit-section-highlight’, as
|
|||
|
well as from ‘magit-diff-context’ and ‘magit-diff-context-highlight’.
|
|||
|
By default we do that by changing the foreground color. Changing the
|
|||
|
background color would lead to complications, and there are already
|
|||
|
enough we cannot get around. (Also note that it is generally a good
|
|||
|
idea for section headings to always be bold, but only for sections that
|
|||
|
have subsections).
|
|||
|
|
|||
|
When there is a valid region selecting diff-related sibling sections,
|
|||
|
i.e. multiple files or hunks, then the bodies of all these sections use
|
|||
|
the respective highlight faces, but additionally the headings instead
|
|||
|
use one of the faces ‘magit-diff-file-heading-selection’ or
|
|||
|
‘magit-diff-hunk-heading-selection’. These faces have to be different
|
|||
|
from the regular highlight variants to provide explicit visual
|
|||
|
indication that the region is active.
|
|||
|
|
|||
|
When theming diff related faces, start by setting the option
|
|||
|
‘magit-diff-refine-hunk’ to ‘all’. You might personally prefer to only
|
|||
|
refine the current hunk or not use hunk refinement at all, but some of
|
|||
|
the users of your theme want all hunks to be refined, so you have to
|
|||
|
cater to that.
|
|||
|
|
|||
|
(Also turn on ‘magit-diff-highlight-indentation’,
|
|||
|
‘magit-diff-highlight-trailing’, and ‘magit-diff-paint-whitespace’; and
|
|||
|
insert some whitespace errors into the code you use for testing.)
|
|||
|
|
|||
|
For e.g. "added lines" you have to adjust three faces:
|
|||
|
‘magit-diff-added’, ‘magit-diff-added-highlight’, and
|
|||
|
‘smerge-refined-added’. Make sure that the latter works well with both
|
|||
|
of the former, as well as ‘smerge-other’ and ‘diff-added’. Then do the
|
|||
|
same for the removed lines, context lines, lines added by us, and lines
|
|||
|
added by them. Also make sure the respective added, removed, and
|
|||
|
context faces use approximately the same saturation for both the
|
|||
|
highlighted and unhighlighted variants. Also make sure the file and
|
|||
|
diff headings work nicely with context lines (e.g. make them look
|
|||
|
different). Line faces should set both the foreground and the
|
|||
|
background color. For example, for added lines use two different
|
|||
|
greens.
|
|||
|
|
|||
|
It’s best if the foreground color of both the highlighted and the
|
|||
|
unhighlighted variants are the same, so you will need to have to find a
|
|||
|
color that works well on the highlight and unhighlighted background, the
|
|||
|
refine background, and the highlight context background. When there is
|
|||
|
an hunk internal region, then the added- and removed-lines background
|
|||
|
color is used only within that region. Outside the region the
|
|||
|
highlighted context background color is used. This makes it easier to
|
|||
|
see what is being staged. With an hunk internal region the hunk heading
|
|||
|
is shown using ‘magit-diff-hunk-heading-selection’, and so are the thin
|
|||
|
lines that are added around the lines that fall within the region. The
|
|||
|
background color of that has to be distinct enough from the various
|
|||
|
other involved background colors.
|
|||
|
|
|||
|
Nobody said this would be easy. If your theme restricts itself to a
|
|||
|
certain set of colors, then you should make an exception here.
|
|||
|
Otherwise it would be impossible to make the diffs look good in each and
|
|||
|
every variation. Actually you might want to just stick to the default
|
|||
|
definitions for these faces. You have been warned. Also please note
|
|||
|
that if you do not get this right, this will in some cases look to users
|
|||
|
like bugs in Magit - so please do it right or not at all.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: FAQ, Next: Debugging Tools, Prev: Plumbing, Up: Top
|
|||
|
|
|||
|
Appendix A FAQ
|
|||
|
**************
|
|||
|
|
|||
|
The next two nodes lists frequently asked questions. For a list of
|
|||
|
frequently *and recently* asked questions, i.e. questions that haven’t
|
|||
|
made it into the manual yet, see
|
|||
|
<https://github.com/magit/magit/wiki/FAQ>.
|
|||
|
|
|||
|
Please also use the *note Debugging Tools::.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* FAQ - How to ...?::
|
|||
|
* FAQ - Issues and Errors::
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: FAQ - How to ...?, Next: FAQ - Issues and Errors, Up: FAQ
|
|||
|
|
|||
|
A.1 FAQ - How to ...?
|
|||
|
=====================
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* 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?::
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: How to show git's output?, Next: How to install the gitman info manual?, Up: FAQ - How to ...?
|
|||
|
|
|||
|
A.1.1 How to show git’s output?
|
|||
|
-------------------------------
|
|||
|
|
|||
|
To show the output of recently run git commands, press ‘$’ (or, if that
|
|||
|
isn’t available, ‘M-x magit-process-buffer’). This will show a buffer
|
|||
|
containing a section per git invocation; as always press ‘TAB’ to expand
|
|||
|
or collapse them.
|
|||
|
|
|||
|
By default, git’s output is only inserted into the process buffer if
|
|||
|
it is run for side-effects. When the output is consumed in some way,
|
|||
|
also inserting it into the process buffer would be too expensive. For
|
|||
|
debugging purposes, it’s possible to do so anyway by setting
|
|||
|
‘magit-git-debug’ to ‘t’.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: How to install the gitman info manual?, Next: How to show diffs for gpg-encrypted files?, Prev: How to show git's output?, Up: FAQ - How to ...?
|
|||
|
|
|||
|
A.1.2 How to install the gitman info manual?
|
|||
|
--------------------------------------------
|
|||
|
|
|||
|
Git’s manpages can be exported as an info manual called ‘gitman’.
|
|||
|
Magit’s own info manual links to nodes in that manual instead of the
|
|||
|
actual manpages because Info doesn’t support linking to manpages.
|
|||
|
|
|||
|
Unfortunately some distributions do not install the ‘gitman’ manual
|
|||
|
by default and you will have to install a separate documentation package
|
|||
|
to get it.
|
|||
|
|
|||
|
Magit patches Info adding the ability to visit links to the ‘gitman’
|
|||
|
Info manual by instead viewing the respective manpage. If you prefer
|
|||
|
that approach, then set the value of ‘magit-view-git-manual-method’ to
|
|||
|
one of the supported packages ‘man’ or ‘woman’, e.g.:
|
|||
|
|
|||
|
(setq magit-view-git-manual-method 'man)
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: How to show diffs for gpg-encrypted files?, Next: How does branching and pushing work?, Prev: How to install the gitman info manual?, Up: FAQ - How to ...?
|
|||
|
|
|||
|
A.1.3 How to show diffs for gpg-encrypted files?
|
|||
|
------------------------------------------------
|
|||
|
|
|||
|
Git supports showing diffs for encrypted files, but has to be told to do
|
|||
|
so. Since Magit just uses Git to get the diffs, configuring Git also
|
|||
|
affects the diffs displayed inside Magit.
|
|||
|
|
|||
|
git config --global diff.gpg.textconv "gpg --no-tty --decrypt"
|
|||
|
echo "*.gpg filter=gpg diff=gpg" > .gitattributes
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: How does branching and pushing work?, Next: Can Magit be used as ediff-version-control-package?, Prev: How to show diffs for gpg-encrypted files?, Up: FAQ - How to ...?
|
|||
|
|
|||
|
A.1.4 How does branching and pushing work?
|
|||
|
------------------------------------------
|
|||
|
|
|||
|
Please see *note Branching:: and
|
|||
|
<http://emacsair.me/2016/01/17/magit-2.4>
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Can Magit be used as ediff-version-control-package?, Prev: How does branching and pushing work?, Up: FAQ - How to ...?
|
|||
|
|
|||
|
A.1.5 Can Magit be used as ‘ediff-version-control-package’?
|
|||
|
-----------------------------------------------------------
|
|||
|
|
|||
|
No, it cannot. For that to work the functions ‘ediff-magit-internal’
|
|||
|
and ‘ediff-magit-merge-internal’ would have to be implemented, and they
|
|||
|
are not. These two functions are only used by the three commands
|
|||
|
‘ediff-revision’, ‘ediff-merge-revisions-with-ancestor’, and
|
|||
|
‘ediff-merge-revisions’.
|
|||
|
|
|||
|
These commands only delegate the task of populating buffers with
|
|||
|
certain revisions to the "internal" functions. The equally important
|
|||
|
task of determining which revisions are to be compared/merged is not
|
|||
|
delegated. Instead this is done without any support whatsoever from the
|
|||
|
version control package/system - meaning that the user has to enter the
|
|||
|
revisions explicitly. Instead of implementing ‘ediff-magit-internal’ we
|
|||
|
provide ‘magit-ediff-compare’, which handles both tasks like it is 2005.
|
|||
|
|
|||
|
The other commands ‘ediff-merge-revisions’ and
|
|||
|
‘ediff-merge-revisions-with-ancestor’ are normally not what you want
|
|||
|
when using a modern version control system like Git. Instead of letting
|
|||
|
the user resolve only those conflicts which Git could not resolve on its
|
|||
|
own, they throw away all work done by Git and then expect the user to
|
|||
|
manually merge all conflicts, including those that had already been
|
|||
|
resolved. That made sense back in the days when version control systems
|
|||
|
couldn’t merge (or so I have been told), but not anymore. Once in a
|
|||
|
blue moon you might actually want to see all conflicts, in which case
|
|||
|
you *can* use these commands, which then use ‘ediff-vc-merge-internal’.
|
|||
|
So we don’t actually have to implement ‘ediff-magit-merge-internal’.
|
|||
|
Instead we provide the more useful command ‘magit-ediff-resolve’ which
|
|||
|
only shows yet-to-be resolved conflicts.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: FAQ - Issues and Errors, Prev: FAQ - How to ...?, Up: FAQ
|
|||
|
|
|||
|
A.2 FAQ - Issues and Errors
|
|||
|
===========================
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* 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: Magit is slow, Next: I changed several thousand files at once and now Magit is unusable, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.1 Magit is slow
|
|||
|
-------------------
|
|||
|
|
|||
|
See *note Performance::.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: I changed several thousand files at once and now Magit is unusable, Next: I am having problems committing, Prev: Magit is slow, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.2 I changed several thousand files at once and now Magit is unusable
|
|||
|
------------------------------------------------------------------------
|
|||
|
|
|||
|
Magit is *currently* not expected to work under such conditions. It
|
|||
|
sure would be nice if it did, and v2.5 will hopefully be a big step into
|
|||
|
that direction. But it might take until v3.1 to accomplish fully
|
|||
|
satisfactory performance, because that requires some heavy refactoring.
|
|||
|
|
|||
|
But for now we recommend you use the command line to complete this
|
|||
|
one commit. Also see *note Performance::.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: I am having problems committing, Next: I am using MS Windows and cannot push with Magit, Prev: I changed several thousand files at once and now Magit is unusable, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.3 I am having problems committing
|
|||
|
-------------------------------------
|
|||
|
|
|||
|
That likely means that Magit is having problems finding an appropriate
|
|||
|
emacsclient executable. See *note (with-editor)Configuring
|
|||
|
With-Editor:: and *note (with-editor)Debugging::.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: I am using MS Windows and cannot push with Magit, Next: I am using OS X and SOMETHING works in shell but not in Magit, Prev: I am having problems committing, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.4 I am using MS Windows and cannot push with Magit
|
|||
|
------------------------------------------------------
|
|||
|
|
|||
|
It’s almost certain that Magit is only incidental to this issue. It is
|
|||
|
much more likely that this is a configuration issue, even if you can
|
|||
|
push on the command line.
|
|||
|
|
|||
|
Detailed setup instructions can be found at
|
|||
|
<https://github.com/magit/magit/wiki/Pushing-with-Magit-from-Windows>.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: I am using OS X and SOMETHING works in shell but not in Magit, Next: Diffs contain control sequences, Prev: I am using MS Windows and cannot push with Magit, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.5 I am using OS X and SOMETHING works in shell, but not in Magit
|
|||
|
--------------------------------------------------------------------
|
|||
|
|
|||
|
This usually occurs because Emacs doesn’t have the same environment
|
|||
|
variables as your shell. Try installing and configuring
|
|||
|
<https://github.com/purcell/exec-path-from-shell>. By default it
|
|||
|
synchronizes ‘$PATH’, which helps Magit find the same ‘git’ as the one
|
|||
|
you are using on the shell.
|
|||
|
|
|||
|
If SOMETHING is "passphrase caching with gpg-agent for commit and/or
|
|||
|
tag signing", then you’ll also need to synchronize ‘$GPG_AGENT_INFO’.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Diffs contain control sequences, Next: Expanding a file to show the diff causes it to disappear, Prev: I am using OS X and SOMETHING works in shell but not in Magit, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.6 Diffs contain control sequences
|
|||
|
-------------------------------------
|
|||
|
|
|||
|
This happens when you configure Git to always color diffs and/or all of
|
|||
|
its output. The valid values for relevant Git variables ‘color.ui’ and
|
|||
|
‘color.diff’ are ‘false’, ‘true’ and ‘always’, and the default is
|
|||
|
‘true’. You should leave it that way because then you get colorful
|
|||
|
output in terminals by default but when git’s output is consumed by
|
|||
|
something else, then no color control sequences are used.
|
|||
|
|
|||
|
If you actually use some other tool that requires setting ‘color.ui’
|
|||
|
and/or ‘color.diff’ to ‘always’ (which is highly unlikely), then you can
|
|||
|
override these settings just for Magit by using:
|
|||
|
|
|||
|
(setq magit-git-global-arguments
|
|||
|
(nconc magit-git-global-arguments
|
|||
|
'("-c" "color.ui=false"
|
|||
|
"-c" "color.diff=false")))
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Expanding a file to show the diff causes it to disappear, Next: Point is wrong in the COMMIT_EDITMSG buffer, Prev: Diffs contain control sequences, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.7 Expanding a file to show the diff causes it to disappear
|
|||
|
--------------------------------------------------------------
|
|||
|
|
|||
|
This is probably caused by a change of a ‘diff.*’ Git variable. You
|
|||
|
probably set that variable for a reason, and should therefore only undo
|
|||
|
that setting in Magit by customizing ‘magit-git-global-arguments’.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Point is wrong in the COMMIT_EDITMSG buffer, Next: The mode-line information isn't always up-to-date, Prev: Expanding a file to show the diff causes it to disappear, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.8 Point is wrong in the ‘COMMIT_EDITMSG’ buffer
|
|||
|
---------------------------------------------------
|
|||
|
|
|||
|
Neither Magit nor ‘git-commit‘ fiddle with point in the buffer used to
|
|||
|
write commit messages, so something else must be doing it.
|
|||
|
|
|||
|
You have probably globally enabled a mode which does restore point in
|
|||
|
file-visiting buffers. It might be a bit surprising, but when you write
|
|||
|
a commit message, then you are actually editing a file.
|
|||
|
|
|||
|
So you have to figure out which package is doing. ‘saveplace’,
|
|||
|
‘pointback’, and ‘session’ are likely candidates. These snippets might
|
|||
|
help:
|
|||
|
|
|||
|
(setq session-name-disable-regexp "\\(?:\\`'\\.git/[A-Z_]+\\'\\)")
|
|||
|
|
|||
|
(with-eval-after-load 'pointback
|
|||
|
(lambda ()
|
|||
|
(when (or git-commit-mode git-rebase-mode)
|
|||
|
(pointback-mode -1))))
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: The mode-line information isn't always up-to-date, Next: A branch and tag sharing the same name breaks SOMETHING, Prev: Point is wrong in the COMMIT_EDITMSG buffer, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.9 The mode-line information isn’t always up-to-date
|
|||
|
-------------------------------------------------------
|
|||
|
|
|||
|
Magit is not responsible for the version control information that is
|
|||
|
being displayed in the mode-line and looks something like ‘Git-master’.
|
|||
|
The built-in "Version Control" package, also known as "VC", updates that
|
|||
|
information, and can be told to do so more often:
|
|||
|
|
|||
|
(setq auto-revert-check-vc-info t)
|
|||
|
|
|||
|
But doing so isn’t good for performance. For more (overly
|
|||
|
optimistic) information see *note (emacs)VC Mode Line::.
|
|||
|
|
|||
|
If you don’t really care about seeing that information in the
|
|||
|
mode-line, but just don’t want to see _incorrect_ information, then
|
|||
|
consider disabling VC when using Git:
|
|||
|
|
|||
|
(setq vc-handled-backends (delq 'Git vc-handled-backends))
|
|||
|
|
|||
|
Or to disable it completely:
|
|||
|
|
|||
|
(setq vc-handled-backends nil)
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: A branch and tag sharing the same name breaks SOMETHING, Next: My Git hooks work on the command-line but not inside Magit, Prev: The mode-line information isn't always up-to-date, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.10 A branch and tag sharing the same name breaks SOMETHING
|
|||
|
--------------------------------------------------------------
|
|||
|
|
|||
|
Or more generally, ambiguous refnames break SOMETHING.
|
|||
|
|
|||
|
Magit assumes that refs are named non-ambiguously across the
|
|||
|
"refs/heads/", "refs/tags/", and "refs/remotes/" namespaces (i.e., all
|
|||
|
the names remain unique when those prefixes are stripped). We consider
|
|||
|
ambiguous refnames unsupported and recommend that you use a
|
|||
|
non-ambiguous naming scheme. However, if you do work with a repository
|
|||
|
that has ambiguous refnames, please report any issues you encounter so
|
|||
|
that we can investigate whether there is a simple fix.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: My Git hooks work on the command-line but not inside Magit, Next: git-commit-mode isn't used when committing from the command-line, Prev: A branch and tag sharing the same name breaks SOMETHING, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.11 My Git hooks work on the command-line but not inside Magit
|
|||
|
-----------------------------------------------------------------
|
|||
|
|
|||
|
When Magit calls ‘git’ it adds a few global arguments including
|
|||
|
‘--literal-pathspecs’ and the ‘git’ process started by Magit then passes
|
|||
|
that setting on to other ‘git’ process it starts itself. It does so by
|
|||
|
setting the environment variable ‘GIT_LITERAL_PATHSPECS’, not by calling
|
|||
|
subprocesses with the ‘--literal-pathspecs’. You can therefore override
|
|||
|
this setting in hook scripts using ‘unset GIT_LITERAL_PATHSPECS’.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: git-commit-mode isn't used when committing from the command-line, Next: Point ends up inside invisible text when jumping to a file-visiting buffer, Prev: My Git hooks work on the command-line but not inside Magit, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.12 ‘git-commit-mode’ isn’t used when committing from the command-line
|
|||
|
-------------------------------------------------------------------------
|
|||
|
|
|||
|
The reason for this is that ‘git-commit.el’ has not been loaded yet
|
|||
|
and/or that the server has not been started yet. These things have
|
|||
|
always already been taken care of when you commit from Magit because in
|
|||
|
order to do so, Magit has to be loaded and doing that involves loading
|
|||
|
‘git-commit’ and starting the server.
|
|||
|
|
|||
|
If you want to commit from the command-line, then you have to take
|
|||
|
care of these things yourself. Your ‘init.el’ file should contain:
|
|||
|
|
|||
|
(require 'git-commit)
|
|||
|
(server-mode)
|
|||
|
|
|||
|
Instead of ‘(require ’git-commit)‘ you may also use:
|
|||
|
|
|||
|
(load "/path/to/magit-autoloads.el")
|
|||
|
|
|||
|
You might want to do that because loading ‘git-commit’ causes large
|
|||
|
parts of Magit to be loaded.
|
|||
|
|
|||
|
There are also some variations of ‘(server-mode)’ that you might want
|
|||
|
to try. Personally I use:
|
|||
|
|
|||
|
(use-package server
|
|||
|
:config (or (server-running-p) (server-mode)))
|
|||
|
|
|||
|
Now you can use:
|
|||
|
|
|||
|
$ emacs&
|
|||
|
$ EDITOR=emacsclient git commit
|
|||
|
|
|||
|
However you cannot use:
|
|||
|
|
|||
|
$ killall emacs
|
|||
|
$ EDITOR="emacsclient --alternate-editor emacs" git commit
|
|||
|
|
|||
|
This will actually end up using ‘emacs’, not ‘emacsclient’. If you
|
|||
|
do this, then can still edit the commit message but ‘git-commit-mode’
|
|||
|
won’t be used and you have to exit ‘emacs’ to finish the process.
|
|||
|
|
|||
|
Tautology ahead. If you want to be able to use ‘emacsclient’ to
|
|||
|
connect to a running ‘emacs’ instance, even though no ‘emacs’ instance
|
|||
|
is running, then you cannot use ‘emacsclient’ directly.
|
|||
|
|
|||
|
Instead you have to create a script that does something like this:
|
|||
|
|
|||
|
Try to use ‘emacsclient’ (without using ‘--alternate-editor’). If
|
|||
|
that succeeds, do nothing else. Otherwise start ‘emacs &’ (and
|
|||
|
‘init.el’ must call ‘server-start’) and try to use ‘emacsclient’ again.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Point ends up inside invisible text when jumping to a file-visiting buffer, Prev: git-commit-mode isn't used when committing from the command-line, Up: FAQ - Issues and Errors
|
|||
|
|
|||
|
A.2.13 Point ends up inside invisible text when jumping to a file-visiting buffer
|
|||
|
---------------------------------------------------------------------------------
|
|||
|
|
|||
|
This can happen when you type ‘RET’ on a hunk to visit the respective
|
|||
|
file at the respective position. One solution to this problem is to use
|
|||
|
‘global-reveal-mode’. It makes sure that text around point is always
|
|||
|
visible. If that is too drastic for your taste, then you may instead
|
|||
|
use ‘magit-diff-visit-file-hook’ to reveal the text, possibly using
|
|||
|
‘reveal-post-command’ or for Org buffers ‘org-reveal’.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Debugging Tools, Next: Keystroke Index, Prev: FAQ, Up: Top
|
|||
|
|
|||
|
B Debugging Tools
|
|||
|
*****************
|
|||
|
|
|||
|
Magit and its dependencies provide a few debugging tools, and we
|
|||
|
appreciate it very much if you use those tools before reporting an
|
|||
|
issue. Please include all relevant output when reporting an issue.
|
|||
|
|
|||
|
‘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.
|
|||
|
|
|||
|
‘M-x magit-emacs-Q-command’ (‘magit-emacs-Q-command’)
|
|||
|
|
|||
|
This command shows a debugging shell command in the echo area and
|
|||
|
adds it to the kill ring. Paste that command into a shell and run
|
|||
|
it.
|
|||
|
|
|||
|
This shell command starts ‘emacs’ with only ‘magit’ and its
|
|||
|
dependencies loaded. Neither your configuration nor other
|
|||
|
installed packages are loaded. This makes it easier to determine
|
|||
|
whether some issue lays with Magit or something else.
|
|||
|
|
|||
|
If you run Magit from its Git repository, then you should be able
|
|||
|
to use ‘make emacs-Q’ instead of the output of this command.
|
|||
|
|
|||
|
‘M-x magit-debug-git-executable’ (‘magit-debug-git-executable’)
|
|||
|
|
|||
|
This command displays a buffer containing information about the
|
|||
|
available and used ‘git’ executable(s), and can be useful when
|
|||
|
investigating ‘exec-path’ issues.
|
|||
|
|
|||
|
Also see *note Git Executable::.
|
|||
|
|
|||
|
‘M-x with-editor-debug’ (‘with-editor-debug’)
|
|||
|
|
|||
|
This command displays a buffer containing information about the
|
|||
|
available and used ‘~emacsclient’ executable(s), and can be useful
|
|||
|
when investigating why Magit (or rather ‘with-editor’) cannot find
|
|||
|
an appropriate ‘emacsclient’ executable.
|
|||
|
|
|||
|
Also see *note (with-editor)Debugging::.
|
|||
|
|
|||
|
Please also see the *note FAQ::.
|
|||
|
|
|||
|
|
|||
|
File: magit.info, Node: Keystroke Index, Next: Command Index, Prev: Debugging Tools, Up: Top
|
|||
|
|
|||
|
Appendix C Keystroke Index
|
|||
|
**************************
|
|||
|
|
|||
|
|