mgitstatus.1

.\" Automatically generated by Pandoc 2.5
.\"
.TH "MGITSTATUS" "1" "Mar 2022" "" ""
.hy
.SH NAME
.PP
mgitstatus \- Show uncommitted, untracked and unpushed changes for
multiple Git repos.
.SH SYNOPSIS
.PP
\f[B]mgitstatus\f[R] [\f[B]\-\-version\f[R]] [\f[B]\-w\f[R]]
[\f[B]\-e\f[R]] [\f[B]\-f\f[R]] [\f[B]\-\-throttle\f[R] SEC]
[\f[B]\-c\f[R]] [\f[B]\-d/\-\-depth\f[R]=2] [\f[B]\-\-flatten\f[R]]
[\f[B]\-\-no\-X\f[R]] [\f[B]DIR\f[R] [\f[B]DIR\f[R]]\&...]
.SH DESCRIPTION
.PP
\f[B]mgitstatus\f[R] shows uncommitted, untracked and unpushed changes
in multiple Git repositories.
By default, \f[B]mgitstatus\f[R] scans two directories deep.
This can be changed with the \f[C]\-d\f[R] (\f[C]\-\-depth\f[R]) option.
If \f[B]DEPTH\f[R] is 0, the scan is infinitely deep.
.PP
mgitstatus shows:
.IP \[bu] 2
\f[B]Uncommitted changes\f[R] if there are unstaged or uncommitted
changes on the checked out branch.
.IP \[bu] 2
\f[B]Untracked files\f[R] if there are untracked files which are not
ignored.
.IP \[bu] 2
\f[B]Needs push (BRANCH)\f[R] if the branch is tracking a (remote)
branch which is behind.
.IP \[bu] 2
\f[B]Needs upstream (BRANCH)\f[R] if a branch does not have a local or
remote upstream branch configured.
Changes in the branch may otherwise never be pushed or merged.
.IP \[bu] 2
\f[B]Needs pull (BRANCH)\f[R] if the branch is tracking a (remote)
branch which is ahead.
This requires that the local git repo already knows about the remote
changes (i.e.\ you\[cq]ve done a fetch), or that you specify the \-f
option.
mgitstatus does NOT contact the remote by default.
.IP \[bu] 2
\f[B]X stashes\f[R] if there are stashes.
.PP
Since there are a lot of different states a git repository can be in,
mgitstatus makes no guarantees that all states are taken into account.
.SH OPTIONS
.TP
.B \f[B]\-\-version\f[R]
Show version
.TP
.B \f[B]\-w\f[R]
Warn about dirs that are not Git repositories
.TP
.B \f[B]\-e\f[R]
Exclude repos that are `ok'
.TP
.B \f[B]\-f\f[R]
Do a `git fetch' on each repo (slow for many repos)
.TP
.B \f[B]\-\-throttle SEC\f[R]
Wait SEC seconds between each `git fetch' (\-f option)
.TP
.B \f[B]\-c\f[R]
Force color output (preserve colors when using pipes)
.TP
.B \f[B]\-d, \-\-depth=2\f[R]
Scan this many directories deep.
Default is 2.
If \f[B]0\f[R], the scan is infinitely deep
.TP
.B \f[B]\-\-no\-depth\f[R]
Do not recurse into directories (incompatible with \-d)
.TP
.B \f[B]\-\-flatten\f[R]
Flatten output by only showing one status per line.
If a repo has multiple statuses, multiple lines are shown for that repo.
This aids in grepability.
.PP
You can limit output with the following options:
.TP
.B \f[B]\-\-no\-push\f[R]
Do not show branches that need a push.
.TP
.B \f[B]\-\-no\-pull\f[R]
Do not show branches that need a pull.
.TP
.B \f[B]\-\-no\-upstream\f[R]
Do not show branches that need an upstream.
.TP
.B \f[B]\-\-no\-uncommitted\f[R]
Do not show branches that have unstaged or uncommitted changes.
.TP
.B \f[B]\-\-no\-untracked\f[R]
Do not show branches that have untracked files.
.TP
.B \f[B]\-\-no\-stashes\f[R]
Do now show stashes
.TP
.B \f[B]\-\-no\-ok\f[R]
Do now show repos that are `ok' (same as \-e)
.SH EXAMPLES
.PP
The following command scans two directories deep for Git projects and
shows their status:
.IP
.nf
\f[C]
$ mgitstatus
\&./fboender/sla: ok
\&./fboender/multi\-git\-status: Needs push (master) Untracked files
\&./other/peewee: ok
\f[R]
.fi
.PP
To scan deeper (three dirs instead of two) in the current dir:
.IP
.nf
\f[C]
$ mgitstatus \-d 3
\f[R]
.fi
.PP
The following command scans three levels deep in \f[C]/opt/deploy/\f[R]
and hides repos that are `ok'.
It does not show stashes:
.IP
.nf
\f[C]
$ mgitstatus \-e \-\-no\-stashes \-d 3 /opt/deploy
\f[R]
.fi
.PP
To ignore a repo, set the \f[C]mgitstatus.ignore\f[R] git configuration
option for that repo to \f[C]true\f[R].
E.g.:
.IP
.nf
\f[C]
$ cd stupidrepo
$ git config \-\-local mgitstatus.ignore true
\f[R]
.fi
.PP
Sort output by repo name while retaining colors:
.IP
.nf
\f[C]
$ mgitstatus \-c | sort
\&./ansible: ok
\&./ansible\-cmdb: Needs push (master) Uncommitted changes Untracked files
\&./davis: ok
\&./espy: Uncommitted changes Untracked files
\&./garner: Untracked files
\&./garner\-chains: ok
\&./mdpreview: ok
\f[R]
.fi
.PP
Sort output by repo status while retaining colors:
.IP
.nf
\f[C]
$ mgitstatus \-c \-\-flatten \-e | sort \-k2
\&./fboender/ansible\-cmdb: Uncommitted changes
\&./fboender/espy: Uncommitted changes
\&./fboender/multi\-git\-status: Uncommitted changes
\&./fboender/ansible\-cmdb: Needs push (master)
\&./fboender/ansible\-cmdb: Untracked files
\&./fboender/espy: Untracked files
\&./fboender/garner: Untracked files
\&./fboender/multi\-git\-status: Untracked files
\f[R]
.fi
.PP
Force color output and flatten the output so we can grep for things:
.IP
.nf
\f[C]
$ mgitstatus \-\-flatten \-c | grep Uncommitted
\&./fboender/multi\-git\-status: Uncommitted changes
\&./fboender/ansible\-cmdb: Uncommitted changes
\&./fboender/espy: Uncommitted changes
\f[R]
.fi
.SH COPYRIGHT
.PP
Copyright 2016\-2022, Ferry Boender (et al).
.PP
Licensed under the MIT license.
For more information, see the LICENSE.txt file.
.SH AUTHORS
Ferry Boender.