Magit runs Git either for side-effects (e.g., when pushing) or to get some value (e.g., the name of the current branch).
When Git is run for side-effects, the process output is logged in a
per-repository log buffer, which can be consulted using the
magit-process-buffer command, when things don’t go as expected.
The output/errors for up to magit-process-log-max Git commands are
retained.
magit-process-buffer) ¶This commands displays the process buffer for the current repository.
Inside that buffer, the usual key bindings for navigating and showing sections are available. There is one additional command.
magit-process-kill) ¶This command kills the process represented by the section at point.
This command toggles whether additional git errors are reported.
Magit basically calls git for one of these two reasons: for side-effects or to do something with its standard output.
When git is run for side-effects then its output, including error
messages, go into the process buffer which is shown when using $.
When git’s output is consumed in some way, then it would be too expensive to also insert it into this buffer, but with this command that can be enabled temporarily. In that case, if git returns with a non-zero exit status, then at least its standard error is inserted into this buffer.
Also note that just because git exits with a non-zero status and prints an error message, that usually doesn’t mean that it is an error as far as Magit is concerned, which is another reason we usually hide these error messages. Whether some error message is relevant in the context of some unexpected behavior has to be judged on a case by case basis.
When a Git process is running for side-effects, Magit displays an
indicator in the mode line, using the magit-mode-line-process face.
If the Git process exits successfully, the process indicator is removed from the mode line immediately.
In the case of a Git error, the process indicator is not removed, but
is instead highlighted with the magit-mode-line-process-error face,
and the error details from the process buffer are provided as a
tooltip for mouse users. This error indicator persists in the mode
line until the next magit buffer refresh.
If you do not wish process errors to be indicated in the mode line,
set magit-process-display-mode-line-error to nil.
Process errors are displayed at the top of the status buffer and in
the echo area. In both places a hint is appended, which informs users
that they can see the full output in the process buffer and how to
display that buffer. However, once you are aware of that, you might
want to set magit-show-process-buffer-hint to nil.
While Magit provides many Emacs commands to interact with Git, it does not cover everything. In those cases your existing Git knowledge will come in handy. Magit provides some commands for running arbitrary Git commands by typing them into the minibuffer, instead of having to switch to a shell.
magit-run) ¶This transient prefix command binds the following suffix commands and displays them in a temporary buffer until a suffix is invoked.
magit-git-command-topdir) ¶This command reads a command from the user and executes it in the top-level directory of the current working tree.
The string "git " is used as initial input when prompting the user for the command. It can be removed to run another command.
magit-git-command) ¶This command reads a command from the user and executes it in
default-directory. With a prefix argument the command is executed
in the top-level directory of the current working tree instead.
The string "git " is used as initial input when prompting the user for the command. It can be removed to run another command.
magit-shell-command-topdir) ¶This command reads a command from the user and executes it in the top-level directory of the current working tree.
magit-shell-command) ¶This command reads a command from the user and executes it in
default-directory. With a prefix argument the command is executed
in the top-level directory of the current working tree instead.
Whether the prompt, used by the above commands when reading a shell command, shows the directory in which it will be run.
These suffix commands start external gui tools.
magit-run-gitk) ¶This command runs gitk in the current repository.
magit-run-gitk-all) ¶This command runs gitk --all in the current repository.
magit-run-gitk-branches) ¶This command runs gitk --branches in the current repository.
magit-run-git-gui) ¶This command runs git gui in the current repository.
magit-git-mergetool) ¶This command runs ‘git mergetool --gui’ in the current repository.
With a prefix argument this acts as a transient prefix command, allowing the user to select the mergetool and change some settings.
When Magit calls Git, then it may do so using the absolute path to the
git executable, or using just its name.
When running git locally and the system-type is windows-nt (any
Windows version) or darwin (macOS) then magit-git-executable is set
to an absolute path when Magit is loaded.
On Windows it is necessary to use an absolute path because Git comes
with several wrapper scripts for the actual git binary, which are also
placed on $PATH, and using one of these wrappers instead of the binary
would degrade performance horribly. For some macOS users using just
the name of the executable also performs horribly, so we avoid doing
that on that platform as well. On other platforms, using just the
name seems to work just fine.
Using an absolute path when running git on a remote machine over
Tramp, would be problematic to use an absolute path that is suitable
on the local machine, so a separate option is used to control the name
or path that is used on remote machines.
The git executable used by Magit on the local host. This should be
either the absolute path to the executable, or the string "git" to
let Emacs find the executable itself, using the standard mechanism
for doing such things.
The git executable used by Magit on remote machines over Tramp.
Normally this should be just the string "git". Consider customizing
tramp-remote-path instead of this option.
If Emacs is unable to find the correct executable, then you can
work around that by explicitly setting the value of one of these two
options. Doing that should be considered a kludge; it is better to
make sure that the order in exec-path or tramp-remote-path is correct.
Note that exec-path is set based on the value of the PATH environment
variable that is in effect when Emacs is started. If you set PATH in
your shell’s init files, then that only has an effect on Emacs if you
start it from that shell (because the environment of a process is only
passed to its child processes, not to arbitrary other processes). If
that is not how you start Emacs, then the exec-path-from-shell package
can help; though honestly I consider that a kludge too.
The command magit-debug-git-executable can be useful to find out where
Emacs is searching for git.
This command displays a buffer with information about
magit-git-executable and magit-remote-git-executable.
This command shows the currently used versions of Magit, Git, and Emacs in the echo area. Non-interactively this just returns the Magit version.
The arguments set here are used every time the git executable is run
as a subprocess. They are placed right after the executable itself
and before the git command - as in git HERE... COMMAND REST. For
valid arguments see
the git(1) manpage.
Be careful what you add here, especially if you are using Tramp to connect to servers with ancient Git versions. Never remove anything that is part of the default value, unless you really know what you are doing. And think very hard before adding something; it will be used every time Magit runs Git for any purpose.