gitsum 1.1.0

Summarize the status of multiple Git repositories.

gitsum

gitsum is a command-line tool that provides a summary of multiple Git repositories.

Installation

Ensure you have Python 3.8+ and pip installed. Then run

pip install gitsum

Basic Usage

Move to a directory in which there are Git repositories and then run gitsum.

This will print out an overview of the status of each repository within the current directory (or its subdirectories). For example:

Found 7 Git repositories.
!  deleted                        master        *  local repo
!  modified                       (d02092)      *  local repo
   remote/empty                   (no commits)     local branch
!  remote/not empty/ahead behind  main             >1 <3
!  remote/not empty/staged        feature       *
!  unmerged                       main          *  local repo
!  untracked                      (no commits)  *  local repo

The standard output includes:

• The flag ! if there are local changes or if the current branch is ahead of or behind its upstream branch
• The directory path (relative to the current working directory)
• The current branch (or the current commit hash if the repo is in detached HEAD mode)
• The flag * if there are local changes (e.g., untracked files, modified files, deleted files)
• The remote status, which can be:
  • local repo if the repository has no remotes
  • local branch if the repository has at least one remote but the current branch has no upstream
  • The number of commits ahead and behind the upstream branch (e.g., >1 <3 say that the given repo is 1 commit ahead and 3 commits behind)

General Usage

Getting Help

Run

gitsum --help

Listing Files Outside Git Repos

In some cases you might want to know if there are files or directories which are not in a Git repository (e.g., to know if you forgot to make a Git repo for any of your local projects).

To see a list of files and directories that are not inside a Git repository (in addition to the normal output), run

gitsum --outside-files

To see only these outside files (without the normal output), run

gitsum --only-outside-files

Fetching Beforehand

To fetch from each remote repository before displaying the repository statuses, run

gitsum --fetch

Note that this option is currently limited to public repositories. If gitsum is unable to fetch (e.g., because the repository is private), then a warning will simply be displayed.

Running the Tests

Before running the tests, clone the repository and install the test dependencies using pip install -r test-requirements.txt. You must also build the project with python -m build and then install the package with pip install --find-links=dist gitsum.

The tests can be run by issuing the command pytest (or python -m unittest, if you prefer). This must be done from the root of the repository.

gitsum is verified by a few integration tests which create Git repos and check that the command's output is as expected. To avoid the gitsum repo itself interfering with the output, the repo is temporarily disabled by renaming the .git/ folder to .git.bak/. This might not be possible if your IDE is using the .git/ folder. If you get errors, you might need to disable your IDE's Git integration for this project. For example, in VS Code, you can add a file .vscode/settings.json in the root of the repo with the following contents:

{
    "git.enabled": false
}