2004 lines
120 KiB
Plaintext
2004 lines
120 KiB
Plaintext
This is magit.info, produced by makeinfo version 5.2 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: Matching Sections, Prev: Section Selection, Up: Section Plumbing
|
||
|
||
10.2.3 Matching Sections
|
||
------------------------
|
||
|
||
‘M-x magit-describe-section’ (‘magit-describe-section’)
|
||
|
||
Show information about the section at point. This command is
|
||
intended for debugging purposes.
|
||
|
||
-- Function: magit-section-ident
|
||
|
||
Return an unique identifier for SECTION. The return value has the
|
||
form ‘((TYPE . VALUE)...)’.
|
||
|
||
-- Function: magit-get-section
|
||
|
||
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.
|
||
|
||
• ‘[TYPE...]’
|
||
|
||
matches if the first TYPE matches the type of the section, the
|
||
second matches that of its parent, and so on.
|
||
|
||
• ‘[* TYPE...]’
|
||
|
||
matches sections that match [TYPE…] and also recursively all
|
||
their child sections.
|
||
|
||
• ‘TYPE’
|
||
|
||
matches sections of TYPE regardless of the types of the parent
|
||
sections.
|
||
|
||
Each TYPE is a symbol. Note that it is not necessary to specify
|
||
all TYPEs up to the root section as printed by
|
||
‘magit-describe-type’, unless of course you want to be that
|
||
precise.
|
||
|
||
-- Function: magit-section-when condition &rest body
|
||
|
||
If the section at point matches CONDITION evaluate BODY.
|
||
|
||
If the section matches, then evaluate BODY forms sequentially with
|
||
‘it’ bound to the section and return the value of the last form.
|
||
If there are no BODY forms, then return the value of the section.
|
||
If the section does not match or if there is no section at point
|
||
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/18/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::
|
||
* Emacs 24.5 hangs when loading Magit: Emacs 245 hangs when loading Magit.
|
||
* A branch and tag sharing the same name breaks SOMETHING::
|
||
|
||
|
||
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 because then you get colorful output
|
||
in terminals but git’s output is consumed by something else, then no
|
||
colors are used.
|
||
|
||
If you actually use some other tool which expects that requires that
|
||
you force git to output control sequences (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: Emacs 245 hangs when loading Magit, 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: Emacs 245 hangs when loading Magit, Next: A branch and tag sharing the same name breaks SOMETHING, Prev: The mode-line information isn't always up-to-date, Up: FAQ - Issues and Errors
|
||
|
||
A.2.10 Emacs 24.5 hangs when loading Magit
|
||
------------------------------------------
|
||
|
||
This is actually triggered by loading Tramp. See
|
||
<https://debbugs.gnu.org/cgi/bugreport.cgi?bug=20015> for details. You
|
||
can work around the problem by setting
|
||
‘tramp-ssh-controlmaster-options’. Changing your DNS server (e.g. to
|
||
Google’s ‘8.8.8.8’) may also be sufficient to work around the issue.
|
||
|
||
|
||
File: magit.info, Node: A branch and tag sharing the same name breaks SOMETHING, Prev: Emacs 245 hangs when loading Magit, Up: FAQ - Issues and Errors
|
||
|
||
A.2.11 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: 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 an 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.
|
||
|
||
‘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 ‘git’ 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
|
||
**************************
|
||
|
||
|