Multidir ("muld
"): run tasks in multiple directories
This application exists to run tasks in several directories
sequentially. The motivating use is to view the status of, or fetch
remote changes to, multiple version control repositories.
The design differs from some other superficially similar applications
in that it is designed to be flexible: if you maintain a set of
repositories using several different version control systems,
requiring completely different commands to achieve analogous ends in
each directory, one can easily do so (and, in particular, there is no
built-in git-centric behaviour).
Getting started (without explanations)
- Clone the repository, and run
stack install
in it.
- Copy
tasks.toml
and recipes.toml
from examples/
to
~/.config/muld/
.
- Run
muld discover
on the directory containing all your projects.
- Inspect
~/.config/muld/projs.toml
by hand to remove anything
unwanted, and to add extra tags as desired.
- Now you can run
muld status
, and muld fetch
to fetch changes.
Steps 1 and 2 above can be replaced by:
- Run
cabal update
and cabal install multidir
.
- Copy and paste
tasks.toml
and recipes.toml
from the repository
on Github to ~/.config/muld
.
Getting started (with explanations)
You can build it from source by cloning the repository and running
stack install
in it. This of course requires you to have installed
Haskell/stack.
Configuration consists of providing three
TOML files:
-
projs.toml
lists the directories to be acted upon (together with
tags which classify them).
-
tasks.toml
lists the tasks which may be run upon those
directories, and explains how to do them; differing implementations
can be given for differing tags.
-
recipes.toml
is used for autodiscovery; it contains instructions
on what makes a directory suitable for discovery.
Vaguely useful samples of recipes.toml
and tasks.toml
can be found
in the examples/
directory and copied in. Once recipes.toml
is in
place, one can generate a projs.toml
by running muld discover
(see
below).
These configuration files are each searched for in the following
order:
- Their locations can be supplied on the command-line (see below);
- Failing that, their locations are deduced from the environment
variables
$MULD_TASK_FILE
$MULD_PROJ_FILE
and
$MULD_RECIPE_FILE
, if set;
- Failing that, their locations are taken as
tasks.toml
,
projs.toml
and recipes.toml
in $XDG_CONFIG_HOME/muld
(if that
environment variable is set);
- Failing that, their locations are taken as
tasks.toml
,
projs.toml
and recipes.toml
in $HOME/.config/muld
(if that
environment variable is set);
- Failing that, an error is raised.
For most users, steps 3 and 4 have the same results.
Command-line syntax
The following commands are built in. In every case there is
command-line assistance (type muld COMMAND --help
):
-
muld discover
finds all subdirectories of the given directory
matching the patterns in recipes.toml
, and adds them to
projs.toml
.
-
muld register
adds the given directory to projs.toml
.
-
muld list
lists the directories in projs.toml
.
-
muld run
runs a supplied command in every directory.
-
muld where
list the locations of config files (useful for
debugging, perhaps).
In addition, every task in tasks.toml
gives another command which
can be called; that task is run in every directory.
Selecting directories
Those commands listed above which operate on a collection of
directories (list
, run
and the task commands) can be put to work
on a user-defined set of directories. By default, it is those with the
default
tag, but this can be adjusted using the -s
flag.
The syntax is as follows:
-
muld list -s important
will list those repositories with the
important
tag;
-
muld list -s {/home/fred}
will list those repositories which are
under /home/fred
;
-
these can be combined with the binary operators &
(and), |
(or)
and, \
(difference). Hence muld list -s important\scary
will
list the repositories which are important
but not scary
;
-
parentheses are permitted for complex expressions;
-
for ease, if a specification starts with an operator, it is treated
as though default
was specified first. So muld list -s &interesting
lists the directories which are both default
and
interesting
.
There is an all
tag, which by default is added to all
repositories. One can remove the all
tag from a repository, if
desired, but maybe that's not a very good idea.
Defining tasks
User-defined tasks are in tasks.toml
. They are listed by name, and
by what tag they operate on (allowing the same task to be run
differently for different types of directory).
The rule is that, for each directory, the tags are gone through in
order; the first tag with an implementation for that task is the one
which is used.
Here's an example:
[fetch]
description = "Downloads changes"
[fetch.git]
run = "git -c color.ui=always fetch"
[fetch.jj]
run = "TERM=xterm-color jj git fetch"
This defines a task which can be run on any directory with tags git
or jj
.
Defining recipes
Recipes for registering directories are in recipes.toml
. Each recipe
consists of:
-
the files required to trigger that recipe;
-
the tags added if that recipe is triggered;
-
the discover
flag (which defaults to True
) which says whether
this recipe is enough on its own to discover a directory (or merely
add extra tags to it if discovered for other reasons).
General advice
In most setups, the default shell is not a login shell (dash
rather
than bash
under Debian, for example), and has not had read .bashrc
or anything. Hence one might need to be careful in defining tasks:
-
specifying paths exactly if they're in $PATH
in a login shell but
not in the default shell;
-
reassuring processes that they're okay to assume colour features for
output (for example, prefacing jujutsu commands with
TERM=xterm-color
, and replacing git
with git -c color.ui=always
).
Prior art
There are many other applications which do vaguely similar jobs. Examples
include:
-
Mani is
heavyweight, fairly git-centric, and written in go.
-
Myrepos is nice, but old and
unloved; it is written in javascript for node.js.
Development
The projects in TODO.md are probably all achievable, and I
will do them when I can be bothered (or when someone else can be
bothered).
I'd be happy to take suggestions for extra recipes or extra
implementations of tasks. I'm happy to take suggestions of extra tasks
(and if they're a bit specialist in nature, I may start a new
directory containing suggestions for more niche tasks).
Several of the other available applications support parallelism, which
we don't (at least not yet, and it's not high on my list of
priorities).
Bug reports are very welcome (just email me); there probably are some!