Photo by Alex Jackman on Unsplash

Git-Config: status.*

How to Customize the View of a Repository’s Present State

https://pragprog.com/newsletter/

The git status command provides the user-friendliest answer to a frequently asked question: “What the heck is going on in this repository right now?”

It’s such an essential, Git 101 command that it might surprise you to learn that git status can be configured at all. But it can, and this post will help you tailor git status’s output to better suit your preferences.

In keeping with this ongoing series of posts on Git configuration, we’ll of course be looking at using git config . But I think you’ll find that git status invites you to reason carefully about different ways to modify Git’s default behavior: when to use git config, when to write an alias, and when to just pass along a good, old-fashioned option to a Git command.

Output a Short, Subversion-Style Status

By default, git status is verbose. Even in a clean working tree—that is, a project with no new, changed, or removed files—the chatty default output looks something like this:

$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

When there are new and changed files, the output is chattier still:

$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:  README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    HELLO.md

no changes added to commit (use "git add" and/or "git commit -a")

If you’ve ever spent time working with Subversion (SVN), you might know that its equivalent svn status command is much more compact and no-nonsense (and opaque, especially to the uninitiated).

It’s possible to output SVN-style status messages in Git with either the --short or -s switches:

$ git status --short
 M README.md
?? HELLO.md

The docs for git-status include a list of the two-character short-form status codes. In this case, M indicates that README.md has been modified in the working tree, and HELLO.md is untracked, being unknown to both the index and the working tree: ??

If you’d prefer that output style from git status all the time, you’d run git config --global status.short "true". With your Git installation configured for the short, SVN-style status, you’d then need to pass in the --long or --no-short switch to see the default, long-form output.

Show Branch Information

One useful piece of information missing from the short-form git status output is information about your local branch and any remote branch you might have. By setting git config --global status.branch "true", git status will include branch information even in the short-form output:

$ git status --short
## main...origin/main [ahead 1]
 M README.md
?? HELLO.md

List Individual Tracked Files

A single untracked file in the root, like HELLO.md, always displays nicely. But by default, git status reveals only the path to any directory containing one or more untracked files. Here, for example, is an untracked directory of images (presumably):

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    images/

nothing added to commit but untracked files present (use "git add" to track)

That directory-only default can be cumbersome to work around if you want to craft commits containing only some of the untracked directory’s files. The default can also make life difficult if you’re trying to build up your .gitignore file to ignore certain files in a previously untracked directory, as might be introduced by certain package managers or test suites.

If you want git status to output the full path and file name for all of your untracked files, set status.showUntrackedFiles to "all", which overrides the default setting of "normal".

$ git config --global status.showUntrackedFiles "all"

Running git status on the same directory as before now provides a full listing of each individual untracked file:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    images/bat.png
    images/cat.png
    images/rat.png

nothing added to commit but untracked files present (use "git add" to track)

That "all" option works the same in the short-form status output, too:

$ git status -s
## main...origin/main
?? images/bat.png
?? images/cat.png
?? images/rat.png

As the Git documentation cautions, setting status.showUntrackedFiles to "all" can lead to sluggish performance on some systems, especially for very large repositories. And because on mature projects it’s rarer to add entire directories of untracked files, it can be better to manually invoke the behavior of status.showUntrackedFiles. You can invoke that behavior on a per-command basis by passing the -u switch to git status, or by crafting another alias for yourself, like git config --global alias.su "status -u". Or, if you’ve ever wanted to interact with Git and say “sup,” opt foralias.sup.

Re-run the git config command and set status.showUntrackedFiles to "normal" if you ever need to return to the default behavior of displaying only the name of an untracked directory:

$ git config --global status.showUntrackedFiles "normal"

Alternatively, as with any Git configuration value you’d just like to drop entirely, run git config along with the --unset option:

$ git config --global --unset status.showUntrackedFiles

Output a Stash Count

There’s one more piece of information you can opt to include with the long-form output on git status: a count of any Git stashes you might have. You can either pass in the --show-stash switch or configure Git to always show the stash count:

$ git config --global status.showStash "true"

The stash count will appear at the very end of only the long form of git status:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean
Your stash currently has 3 entries

We’ll look more closely at stashes and configuring Git’s behavior around them in a future post.

In this post, you’ve learned how to configure Git to display a short-form for git status and to display additional information about the branch you’re on, the untracked files you have — even the count of any stashes you might have tucked away.

While git status outputs information about a repository’s present state, git log outputs information about its past. In the next post, we’ll look at configuring git log to fine tune its output as well.

Karl Stolley

Karl’s book, Programming WebRTC: Build Real-Time Streaming Applications for the Web, is available from The Pragmatic Bookshelf:

Programming WebRTC

You can participate in conversations about the book and find a discount code on the book’s forum page.