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.