Skip to main content

10.1.1 Getting a Value from Git

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.

function magit-git-exit-code \&rest args​

Executes git with ARGS and returns its exit code.

function magit-git-success \&rest args​

Executes git with ARGS and returns t if the exit code is 0, nil otherwise.

function magit-git-failure \&rest args​

Executes git with ARGS and returns t if the exit code is 1, nil otherwise.

function magit-git-true \&rest args​

Executes git with ARGS and returns t if the first line printed by git is the string "true", nil otherwise.

function magit-git-false \&rest args​

Executes git with ARGS and returns t if the first line printed by git is the string "false", nil otherwise.

function magit-git-insert \&rest args​

Executes git with ARGS and inserts its output at point.

function magit-git-string \&rest args​

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.

function magit-git-lines \&rest args​

Executes git with ARGS and returns its output as a list of lines. Empty lines anywhere in the output are omitted.

function magit-git-items \&rest args​

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.

function magit-process-git destination \&rest args​

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.

function magit-process-file process \&optional infile buffer display \&rest args​

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.

user option magit-git-debug​

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.

function magit-git-str \&rest args​

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.