[projects/git-slug] Zamiana HOWTO na README.md w formacie Markdown
arekm
arekm at pld-linux.org
Tue May 12 15:08:05 CEST 2026
commit b471068e36443b5b4caa0b0f41f7548a2b7c1137
Author: Arkadiusz Miśkiewicz <arekm at maven.pl>
Date: Mon Apr 6 19:13:21 2026 +0200
Zamiana HOWTO na README.md w formacie Markdown
Zastąpienie starego pliku HOWTO nowoczesnym README.md opisującym
aktualną architekturę git-pld: passthrough git, polecenia
slug-specific, inteligentne domyślne konfiguracje, filtrowanie
repozytoriów, konfiguracja przez gitconfig.
Zaktualizowano MANIFEST.in.
HOWTO | 56 ---------------------
MANIFEST.in | 2 +-
README.md | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 164 insertions(+), 57 deletions(-)
---
diff --git a/HOWTO b/HOWTO
deleted file mode 100644
index bf19527..0000000
--- a/HOWTO
+++ /dev/null
@@ -1,56 +0,0 @@
-How to work with slug.py
-========================
-
-*. Configuration
-
-Add your name and email to git configuration:
-
- git config --global user.email "you at example.com"
- git config --global user.name "Your Name"
-
-If you have and RW access to PLD repositories please use
-<your_login>@pld-linunx.org as email.
-
-
-*. Get initial copy of repositories
-
- slug.py clone <package>
-
-It will clone the chosen package to the ~/PLD_clone directory . You can clone more
-then one package in one go. For example to get all perl and python packages:
-
- slug.py clone perl\* python\*
-
-If you are interested in all existing packages:
-
- slug.py clone
-
-However be afraid that it will take some time to clone all of them.
-
-
-* Update all existing repositories
-
-If you have already cloned some repositories and you want to update them:
-
- slug.py pull
-
-It will fetch all branches and will store them in 'origin' remote. Afterwards
-it will rebase your local changes in current branch on top of corresponding
-remote-tracking branch You can look at it as an faster version of executing
-'git pull --rebase for every local repository.
-
-If you prefer only to update your remote-tracking branches you can run:
-
- slug.py fetch
-
-
-* Advanced usage
-
-If you want to save some disk space and potentially also some time (for large
-repositories like kernel), 'slug.py update' enables to work with only some of
-the branches and shallow clones. See
-
- slug.py update --help
-
-for more details.
-
diff --git a/MANIFEST.in b/MANIFEST.in
index 5b913ff..2886566 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1,4 @@
-include HOWTO
+include README.md
include Makefile
include slug.py.txt
recursive-include post-receive.python.d *.py
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b766340
--- /dev/null
+++ b/README.md
@@ -0,0 +1,163 @@
+# git-pld
+
+Run git commands across PLD Linux package repositories in parallel.
+
+`git pld <command>` works like `git <command>`, but executes it in every matching package repo at once. Any standard git command is supported -- arguments are passed through to git unmodified.
+
+```sh
+git pld pull # pull --rebase --autostash in all repos
+git pld status # short status across all repos
+git pld log --oneline -3 # recent commits across repos
+git pld --pattern 'perl-*' fetch # fetch only perl packages
+git pld checkout main # switch all repos to main
+```
+
+For operations that have no single-repo equivalent, there are slug-specific commands: `update`, `clone`, `list`, `init`.
+
+## Installation
+
+```sh
+python3 setup.py install
+```
+
+The package is also available as `git-core-slug` RPM in PLD Linux.
+
+## Setup
+
+Add your name and email to git configuration:
+
+```sh
+git config --global user.email "you at example.com"
+git config --global user.name "Your Name"
+```
+
+If you have RW access to PLD repositories, use `<your_login>@pld-linux.org` as email.
+
+## Usage
+
+### Getting packages
+
+Clone selected packages:
+
+```sh
+git pld clone perl-*
+git pld clone python-*
+```
+
+Clone all packages (takes a while):
+
+```sh
+git pld clone
+```
+
+### Keeping up to date
+
+Pull with rebase (default -- autostash handles dirty trees):
+
+```sh
+git pld pull
+```
+
+Fetch without touching working trees:
+
+```sh
+git pld fetch
+```
+
+Smart update using centralized Refs repo (faster for large sets, only fetches changed branches):
+
+```sh
+git pld update
+git pld update --new -p 'perl-*' # also init new and prune deleted repos
+```
+
+### Any git command works
+
+```sh
+git pld status
+git pld diff --stat
+git pld log --oneline -5
+git pld branch -a
+git pld push
+git pld stash
+```
+
+### Filtering repos
+
+```sh
+git pld --pattern 'perl-*' status
+git pld --pattern 'python-*' --pattern 'perl-*' pull
+```
+
+### Slug-specific commands
+
+| Command | Description |
+|---------|-------------|
+| `update` | Smart selective fetch via centralized Refs repo. Supports `--new`, `-p`/`--prune`, `-b`/`--branch`, `--depth`. |
+| `clone` | Batch clone matching packages from the PLD server. |
+| `list` | List upstream repositories matching patterns. |
+| `init` | Create new package repositories on the server. |
+
+## Global options
+
+Options before the command name are slug options. Options after go to git.
+
+```
+git pld [-d DIR] [-j N] [-q] [--pattern PAT] <command> [<git-args>...]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-d`, `--packagesdir DIR` | Local directory with repos (default: `~/rpm/packages`) |
+| `-j`, `--jobs N` | Number of parallel workers (default: CPU count) |
+| `-q`, `--quiet` | Suppress stdout from successful repos |
+| `--pattern PAT` | Repo name glob, repeatable (default: `*`) |
+| `--version` | Print version |
+
+## Smart defaults
+
+Slug passes sensible defaults via `git -c` flags, affecting only the `git pld` invocation (not your regular git settings):
+
+| Command | Defaults applied |
+|---------|-----------------|
+| `pull` | `pull.rebase=true`, `pull.autostash=true` |
+| `fetch` | `fetch.prune=true` |
+| `status`| `status.short=true` |
+
+Your CLI flags always override these (e.g. `git pld pull --no-rebase`).
+
+## Configuration
+
+All options can be set persistently in `~/.gitconfig` under the `[PLD]` section:
+
+```ini
+[PLD]
+ packagesdir = ~/work/pld-packages
+ jobs = 8
+```
+
+Per-command defaults can be overridden or disabled:
+
+```ini
+[PLD]
+ # Use merge instead of rebase for pull
+ pull-config = pull.rebase=false
+
+ # Disable slug's fetch defaults entirely
+ fetch-config =
+
+ # Add branch info to status
+ status-config = status.short=true status.branch=true
+```
+
+## Help
+
+```sh
+git pld --help # slug global options
+git pld pull --help # git pull man page
+git pld update --help # slug update options
+```
+
+## License
+
+See [COPYING](COPYING).
================================================================
---- gitweb:
http://git.pld-linux.org/gitweb.cgi/projects/git-slug.git/commitdiff/4a7e426b8f1a3571094b5dc89412bc49b8f29666
More information about the pld-cvs-commit
mailing list