While other Magit buffers contain, e.g., one particular diff or one particular log, the status buffer contains the diffs for staged and unstaged changes, logs for unpushed and unpulled commits, lists of stashes and untracked files, and information related to the current branch.
During certain incomplete operations – for example when a merge resulted in a conflict – additional information is displayed that helps proceeding with or aborting the operation.
The command magit-status displays the status buffer belonging to the
current repository in another window. This command is used so often
that it should be bound globally. We recommend using C-x g:
(global-set-key (kbd "C-x g") 'magit-status)
magit-status) ¶When invoked from within an existing Git repository, then this command shows the status of that repository in a buffer.
If the current directory isn’t located within a Git repository, then
this command prompts for an existing repository or an arbitrary
directory, depending on the option magit-repository-directories, and
the status for the selected repository is shown instead.
These fallback behaviors can also be forced using one or more prefix arguments:
magit-init.
magit-repository-directories, then the behavior is the same as with
two prefix arguments.
List of directories that are Git repositories or contain Git repositories.
Each element has the form (DIRECTORY . DEPTH). DIRECTORY has to be
a directory or a directory file-name, a string. DEPTH, an integer,
specifies the maximum depth to look for Git repositories. If it is
0, then only add DIRECTORY itself.
This option controls which repositories are being listed by
magit-list-repositories. It also affects magit-status (which see)
in potentially surprising ways (see above).
This command is an alternative to magit-status that usually avoids
refreshing the status buffer.
If the status buffer of the current Git repository exists but isn’t being displayed in the selected frame, then it is displayed without being refreshed.
If the status buffer is being displayed in the selected frame, then this command refreshes it.
Prefix arguments have the same meaning as for magit-status,
and additionally cause the buffer to be refresh.
To use this command add this to your init file:
(global-set-key (kbd "C-x g") 'magit-status-quick).
If you do that and then for once want to redisplay the buffer and
also immediately refresh it, then type C-x g followed by g.
A possible alternative command is magit-display-repository-buffer.
It supports displaying any existing Magit buffer that belongs to the
current repository; not just the status buffer.
The contents of status buffers is controlled using the hook
magit-status-sections-hook. See Section Hooks to learn about such
hooks and how to customize them.
This hook is run to insert sections into a status buffer.
The functions described in this section, and the functions
magit-insert-status-headers and magit-insert-untracked-files,
which are described in subsequent sections, are members of this
hook.
Some additional functions that can be added to this hook, but are by default added to another hooks, are listed in References Buffer.
Insert header sections appropriate for magit-status-mode buffers.
The sections are inserted by running the functions on the hook
magit-status-headers-hook. See Status Header Sections.
Insert section for the on-going merge. Display the heads that are being merged. If no merge is in progress, do nothing.
Insert section for the on-going rebase sequence. If no such sequence is in progress, do nothing.
Insert section for the on-going patch applying sequence. If no such sequence is in progress, do nothing.
Insert section for the on-going cherry-pick or revert sequence. If no such sequence is in progress, do nothing.
While bisecting, insert section with output from git bisect.
While bisecting, insert section visualizing the bisect state.
While bisecting, insert section logging bisect progress.
Insert section showing unstaged changes.
Insert section showing staged changes.
Insert the stashes section showing reflog for "refs/stash".
If optional REF is non-nil show reflog for that instead.
If optional HEADING is non-nil use that as section heading
instead of "Stashes:".
Insert section showing commits that haven’t been pulled from the upstream branch yet.
Insert section showing commits that haven’t been pulled from the push-remote branch yet.
Insert section showing unpushed or other recent commits.
If an upstream is configured for the current branch and it is
behind of the current branch, then show the commits that have
not yet been pushed into the upstream branch. If no upstream is
configured or if the upstream is not behind of the current branch,
then show the last magit-log-section-commit-count commits.
Insert section showing commits that haven’t been pushed to the upstream yet.
Insert section showing commits that haven’t been pushed to the push-remote yet.
These functions honor the buffer’s file filter, which can be set using
D - -.
This function may insert a list of untracked files. Whether it actually does so, depends on the option described next.
This option controls whether the above function inserts a list of untracked files in the status buffer.
nil, do not list any untracked files.
t, list untracked files, but if a directory does not contain any
tracked files, then only list that directory, not the contained
untracked files.
all, then list each individual untracked files. This is can be
very slow and is discouraged.
The corresponding values for the Git variable are "no", "normal" and "all".
To disable listing untracked files in a specific repository only,
add the following to .dir-locals.el:
((magit-status-mode (magit-status-show-untracked-files . "no")))
Alternatively (and mostly for historic reasons), it is possible to
use git config to set the repository-local value:
git config set --local status.showUntrackedFiles no
This does not override the (if any) local value of this Lisp variable, but it does override its global value.
See the last section in the git-status(1) manpage, to speed up the part
of the work Git is responsible for. Turning that list into sections is
also not free, so Magit only lists magit-status-file-list-limit files.
This option controls many files are listed at most in each section that lists files in the status buffer. For performance reasons, it is recommended that you do not increase this limit.
While the above function is a member of magit-status-section-hook by
default, the following functions have to be explicitly added by the
user. Because that negatively affects performance, it is recommended
that you don’t do that.
Insert a list of tracked files.
Insert a list of ignored files.
Insert a list of skip-worktree files.
Insert a list of files that are assumed to be unchanged.
Insert section showing unpulled or recent commits.
If an upstream is configured for the current branch and it is
ahead of the current branch, then show the missing commits.
Otherwise, show the last magit-log-section-commit-count
commits.
Insert section showing the last magit-log-section-commit-count
commits.
How many recent commits magit-insert-recent-commits and
magit-insert-unpulled-or-recent-commits (provided there are no
unpulled commits) show.
Insert section showing unpulled commits.
Like magit-insert-unpulled-commits but prefix each commit
that has not been applied yet (i.e., a commit with a patch-id
not shared with any local commit) with "+", and all others
with "-".
Insert section showing unpushed commits.
Like magit-insert-unpushed-commits but prefix each commit
which has not been applied to upstream yet (i.e., a commit with
a patch-id not shared with any upstream commit) with "+" and
all others with "-".
The contents of status buffers is controlled using the hook
magit-status-sections-hook (see Status Sections).
By default magit-insert-status-headers is the first member of that
hook variable.
Insert headers sections appropriate for magit-status-mode buffers.
The sections are inserted by running the functions on the hook
magit-status-headers-hook.
Hook run to insert headers sections into the status buffer.
This hook is run by magit-insert-status-headers, which in turn has
to be a member of magit-status-sections-hook to be used at all.
By default the following functions are members of the above hook:
Insert a header line showing the message about the Git error that just occurred.
This function is only aware of the last error that occur when Git was run for side-effects. If, for example, an error occurs while generating a diff, then that error won’t be inserted. Refreshing the status buffer causes this section to disappear again.
Insert a header line showing the effective diff filters.
Insert a header line about the current branch or detached HEAD.
Insert a header line about the branch that is usually pulled into the current branch.
Insert a header line about the branch that the current branch is usually pushed to.
Insert a header line about the current and/or next tag, along with
the number of commits between the tag and HEAD.
The following functions can also be added to the above hook:
Insert a header line showing the path to the repository top-level.
Insert a header line about the remote of the current branch.
If no remote is configured for the current branch, then fall back showing the "origin" remote, or if that does not exist the first remote in alphabetic order.
Insert a header line about the current user.
The contents of status buffers is controlled using the hook
magit-status-sections-hook (see Status Sections).
By default magit-insert-modules is not a member of that hook
variable.
Insert submodule sections.
Hook magit-module-sections-hook controls which module sections are
inserted, and option magit-module-sections-nested controls whether
they are wrapped in an additional section.
Hook run by magit-insert-modules.
This option controls whether magit-insert-modules wraps inserted
sections in an additional section.
If this is non-nil, then only a single top-level section is inserted.
If it is nil, then all sections listed in magit-module-sections-hook
become top-level sections.
Insert sections for all submodules. For each section insert the
path, the branch, and the output of git describe --tags,
or, failing that, the abbreviated HEAD commit hash.
Press RET on such a submodule section to show its own status buffer.
Press RET on the "Modules" section to display a list of submodules
in a separate buffer. This shows additional information not
displayed in the super-repository’s status buffer.
Insert sections for modules that haven’t been pulled from the upstream yet. These sections can be expanded to show the respective commits.
Insert sections for modules that haven’t been pulled from the push-remote yet. These sections can be expanded to show the respective commits.
Insert sections for modules that haven’t been pushed to the upstream yet. These sections can be expanded to show the respective commits.
Insert sections for modules that haven’t been pushed to the push-remote yet. These sections can be expanded to show the respective commits.
This option specifies whether the margin is initially shown in Magit-Status mode buffers and how it is formatted.
The value has the form (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).
nil, then the margin is shown initially.
age (to show the age of the commit), age-abbreviated (to
abbreviate the time unit to a character), or a string (suitable
for format-time-string) to show the actual date. Option
magit-log-margin-show-committer-date controls which date is being
displayed.
Also see the proceeding section for more options concerning status buffers.