May CLI

pacman-inspired tool to easily list and manage git repositories all across your system. It was created to ease the pain of managing an ever-increasing number of repositories and allow easy access to any of them, no matter the directory your shell happens to be in. may is also designed to be easily integrated into shell scripts dealing with repositories.

Installation

may is available either as a binary for download or as an AUR package for Arch-based distributions - or just build it yourself.

For detailed instruction see /doc/Install.md or click here.

Features

• Get a list of all git repositories on your system (plain may)
• Get a filtered list of your repositories (may -f <subpath>)
• Run build tools on repository selection from one central place (may -R / may -Rf <subpath>)
• View all repositories and check their status (may -S)
• Update all your git repositories from one central command-line interface (may -U)
• Use may in pipes to receive or send git repository lists (e.g. may | fzf | may -U)

Available operations:

may                 # Lists all repositories available in your home directory
may -R              # `Run`: Runs a build-tool command on an auto-detected build tool. Takes a required positional argument at the end.
may -I              # `Inspect`: Shows commands available for a repository from auto-detected build tool
may -S              # `Status`: Runs `git status` on all repositories may can find
may -U              # `Update`: Allows updating (aka pulling) all repositories at once

may -V              # `Version`: (Helper) Prints the version of `may` currently in use
may --help          # `Help`: (Helper) Prints helpful information

Options:

may -d <path>       # `--directory`: Specify path that should be searched (overrides MAY_BASEPATH env variable, default $HOME + WSL mounted user directory if available)
may -f <substring>  # `--filter`: Filter repository path list by the given substring
may -v              # `--verbose`: Verbose output
may -a              # `--all`: All directories are searched, including dotfiles and uncommon directories such as $HOME/Pictures

Every call to may can consist of 0..1 operations and 0..n options. This means that all of the following are permitted: may, may -Uvf subpath, may -Iv, may -vI. The following are NOT permitted: may -IU, may --U.

Viewing repositories: may, may -S (Status) , may -I (Inspect)

In order to view all repositories available in your home directory, simply run:

may

In order to check the state of all those repositories, use:

may -S

Behind the scenes, this asynchronously executes git status -sb for all repositories.

To inspect your repositories further and see which build tools may would be able to use when running may -R, use:

may -I

The inspection output is very useful for writing scripts. Aside from possible command runners available to may, the output also contains information regarding the date of the latest commit and the repository shortname.

Updating repositories: may -U (Update)

To pull updates for all repositories, run:

may -U

To, for example, only update vim plugins, the following are two handy variant:

may -Uaf ".vim" // Update all with filter .vim
may -Uad $HOME/.vim // Update all in directory $HOME/.vim

Running in repositories: may -R (Run)

This is very useful to execute build and run commands on multiple or distant repositories. It is recommended to only use this command in combination with a strict filter (-f <subpath>) as, e.g., building a large number of repositories can be an extremely lengthy task.

may -Rf <repositorypath> <task>

The <task> and other following parameters are forwarded to an auto-selected build tool. In order to find out which build tool would be selected, use may -I. It is recommended to add a Makefile to your project to concretely define available tasks.

Currently supported are the following tools:

• make (highest priority)
• gradle
• npm
• yarn

Limited/Beta support is available for these tools:

• Docker
• go

Note that by adding a Makefile, any command/build tool is easily supported.

Help: may --help, may -V (Version)

Two helper commands are available, may --help to view a short list of generally available commands and may -V to check which version you are currently using.

Customizing

Per default, may uses the entire content in $HOME for its find operations. You can change this behaviour by setting MAY_BASEPATH to your chosen path.

Scripting

may can read paths from stdin that then replace the default list of available git repositories. Its output can also easily be used in standard commands such as awk, grep, ...

The following is a very simple, fzf-based example to have a multi-select of git repositories to pull.

may | fzf -m | may -U

The following builds all gradle projects on your system, making use of the responsible gradlew in each repository.

may -I | grep "gradle" | awk '{ print $1 }' | may -R build