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 \&rest args
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.
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 input \&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.