slug(1)
=======

NAME
----
slug - run git commands across PLD Linux package repositories


SYNOPSIS
--------
[verse]
'git pld' [<options>] <command> [<args>...]
'git pld' [-d <dir>] [-j <n>] [-q] [--pattern <glob>] <command> [<args>...]


DESCRIPTION
-----------

slug runs git commands across PLD Linux package repositories in
parallel.  It has two kinds of commands:

Slug-specific commands ('update', 'clone', 'list', 'init') provide
custom multi-repo orchestration with no single-repo git equivalent.

Everything else is treated as a git passthrough command: 'git <command>'
is run in each matching repo with arguments passed through unmodified,
just like running it manually in each directory.


GLOBAL OPTIONS
--------------

These options must appear *before* the command name.

-d <directory>::
--packagesdir <directory>::
    Local directory containing package repositories.  Defaults to
    the RPM '%_topdir' macro (usually '~/rpm/packages'), overridable
    via 'PLD.packagesdir' in gitconfig.

-j <n>::
--jobs <n>::
    Number of parallel workers.  Defaults to 'min(cpu_count * 4, 32)',
    overridable via 'PLD.jobs' in gitconfig.

-q::
--quiet::
    Suppress stdout from successful repos.  Stderr (warnings, errors)
    is always shown.

--pattern <glob>::
    Repo name glob.  Repeatable.  Defaults to '*' (all repos).
    Overridable via 'PLD.pattern' in gitconfig.

--version::
    Show version and exit.

--help::
    Show global help and exit.


SLUG-SPECIFIC COMMANDS
----------------------

update [<options>] [<pattern>...]::

Smart fetch using the centralized Refs repo.  Only fetches branches
that actually changed upstream, which is much faster than running
'git pld fetch' in every repo.
+
Options:
+
--
-b <pattern>;;
--branch <pattern>;;
    Branch pattern to fetch.  Repeatable.  Defaults to 'master'.

--new;;
    Initialize local repos for packages that exist upstream but not
    locally.

--no-new;;
    Do not initialize new repos (the default).

-p;;
--prune;;
    Remove local repos that were deleted upstream.

--depth <n>;;
    Shallow fetch depth.  0 means full history (the default).

<pattern>...;;
    Repo name globs.  Takes priority over the global '--pattern'.
--

clone [<options>] [<pattern>...]::

Batch clone matching packages from the PLD server.  Fetches all
branches and checks out 'master' in each new repo.
+
Options:
+
--
--depth <n>;;
    Shallow fetch depth.  0 means full history (the default).

<pattern>...;;
    Repo name globs.  Takes priority over the global '--pattern'.
--

list [-b <pattern>...] [<pattern>...]::

Print the names of upstream packages matching the given patterns,
one per line.  Output goes to stdout and is suitable for piping.
+
Options:
+
--
-b <pattern>;;
--branch <pattern>;;
    Only list packages that have a branch matching the pattern.
    Repeatable.  Defaults to '*' (any branch).

<pattern>...;;
    Repo name globs.  Takes priority over the global '--pattern'.
--

init <package>...::

Create new package repositories on the server and initialize
local repos to track them.


GIT PASSTHROUGH
---------------

Any command not listed above is treated as a git command and run in each
matching repo.  For example:

    git pld pull
    git pld status
    git pld log --oneline -5
    git pld checkout master

Arguments after the command name are passed through to git unmodified.
If '--help' or '-h' appears in the git arguments, git's own help page is
shown once instead of running the command in every repo.

Output from each repo is prefixed with the repo name and a progress
counter:

    [  42/20000] perl-Foo: Already up to date.

Built-in config overrides for passthrough commands:

    pull:   pull.rebase=true, pull.autostash=true
    fetch:  fetch.prune=true
    status: status.short=true

These are passed as 'git -c key=value' and can be overridden per-command
in gitconfig (see CONFIGURATION below).


CONFIGURATION
-------------

slug reads settings from the '[PLD]' section of '~/.gitconfig'
(or 'XDG_CONFIG_HOME/git/config').  CLI options take priority over
gitconfig values, which take priority over built-in defaults.

PLD.packagesdir::
    Local directory with package repositories.

PLD.jobs::
    Number of parallel workers.

PLD.pattern::
    Default repo name glob pattern.

PLD.<command>-config::
    Override built-in '-c' config pairs for a passthrough command.
    For example, to disable the built-in 'pull.rebase=true':
+
    [PLD]
        pull-config = pull.rebase=false
+
Setting to empty disables all built-in defaults for that command:
+
    [PLD]
        fetch-config =


EXIT STATUS
-----------

0::
    Success (all repos completed without error).

1::
    One or more repos failed, or a fatal error occurred.


AUTHOR
------

Written by Kacper Kornet and PLD Linux developers.


SEE ALSO
--------

linkgit:git[1]
