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.
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.
Executes git with ARGS and returns its exit code.
Executes git with ARGS and returns t if the exit code is 0, nil
otherwise.
Executes git with ARGS and returns t if the exit code is 1, nil
otherwise.
Executes git with ARGS and returns t if the first line printed by
git is the string "true", nil otherwise.
Executes git with ARGS and returns t if the first line printed by
git is the string "false", nil otherwise.
Executes git with ARGS and inserts its output at point.
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.
Executes git with ARGS and returns its output as a list of lines. Empty lines anywhere in the output are omitted.
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.
Calls Git synchronously in a separate process, returning its exit
code. DESTINATION specifies how to handle the output, like for
call-process, except that file handlers are supported. Enables
Cygwin’s "noglob" option during the call and ensures unix eol
conversion.
Processes files synchronously in a separate process. Identical to
process-file but temporarily enables Cygwin’s "noglob" option during
the call and ensures unix eol conversion.
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.
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.
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.
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.
The synchronous functions return the exit code, while the asynchronous functions return the process object.
Calls git synchronously with ARGS.
Calls PROGRAM synchronously with ARGS.
Calls git synchronously with ARGS and then refreshes.
Calls git synchronously with ARGS and sends it the content of the current buffer on standard input.
If the current buffer’s default-directory is on a remote
filesystem, this function actually runs git asynchronously. But
then it waits for the process to return, so the function itself is
synchronous.
Calls git synchronously with ARGS for side-effects only. This function does not refresh the buffer.
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.
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.
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.
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.
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.
The child process which is about to start. This can be used to change the filter and sentinel.
When this is non-nil, then magit-process-sentinel raises an error if
git exits with a non-zero exit status. For debugging purposes.