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.

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.