5.1 Status Buffer

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)

C-x g     (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.

• If that option specifies any existing repositories, then the user is asked to select one of them.
• Otherwise the user is asked to select an arbitrary directory using regular file-name completion. If the selected directory is the top-level directory of an existing working tree, then the status buffer for that is shown.
• Otherwise the user is offered to initialize the selected directory as a new repository. After creating the repository its status buffer is shown.

These fallback behaviors can also be forced using one or more prefix arguments:

• With two prefix arguments (or more precisely a numeric prefix value of 16 or greater) an arbitrary directory is read, which is then acted on as described above. The same could be accomplished using the command magit-init.
• With a single prefix argument an existing repository is read from the user, or if no repository can be found based on the value of magit-repository-directories, then the behavior is the same as with two prefix arguments.

User Option: magit-repository-directories

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).

Command: magit-status-quick

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.

Command: ido-enter-magit-status

From an Ido prompt used to open a file, instead drop into magit-status. This is similar to ido-magic-delete-char, which, despite its name, usually causes a Dired buffer to be created.

To make this command available, use something like:

(add-hook 'ido-setup-hook
          (lambda ()
            (define-key ido-completion-map
              (kbd \"C-x g\") 'ido-enter-magit-status)))

Starting with Emacs 25.1 the Ido keymaps are defined just once instead of every time Ido is invoked, so now you can modify it like pretty much every other keymap:

(define-key ido-common-completion-map
  (kbd \"C-x g\") 'ido-enter-magit-status)