man/src.1

SPS · log · files · refs · tags · releases · people · languages · GitHub · file
.TH SRC 1 "2026-08-30" "SPS 1.0" "SPS Commands"
.SH NAME
src \- update and query SPS source repository indexes
.SH SYNOPSIS
.nf
src [-q|--quiet] update
src check RECIPE... [--deps]
src search PATTERN [--raw]
src show PACKAGE [--raw]
src which PACKAGE
src list [--raw]
src status [--raw]
.fi
.SH DESCRIPTION
.B src
manages source repository metadata. It never builds or installs packages.
It synchronizes configured Git repositories conservatively and indexes those
checkouts together with configured local directory repositories.
Splux writes core and extra into
.B repos.conf
by default. Community recipes
.RI ( https://github.com/RobertFlexx/sps-community.git ,
priority 50) are documented as a comment only; add
.B git community
to enable them.
.SH COMMANDS
.TP
.B update
Clone absent Git repositories with
.B --depth 1
and
.B --no-tags
(later fetches stay full and also skip tags), fetch existing clean Git
repositories, fast-forward safe tracking branches, scan configured trees,
validate recipes and the selected dependency graph, and atomically replace
the local package index. Invalid input leaves the previous index in place.
Recipe-only packages are hashed in one
.B sha256sum
batch; a repository is parsed in one AWK process rather than one process
per recipe. The definition digest is unchanged.
Progress is written to stderr for each repository, Git clone/fetch, and
index validation. Recipe hashing logs the first and last package plus every
25th in large trees so a long update does not look idle.
.B -q
keeps only the final summary line on stdout.
.TP
.BI check " recipe ..."
Validate each recipe with the same parser used by
.B update
without downloading sources or running any build phase. Each argument is a
recipe file or a directory containing a
.B recipe
file. Failed recipes are reported and the command exits nonzero, so it is safe
to gate automation on it. With
.B --deps
a temporary index of the checked recipes is also validated as a dependency
graph.
.TP
.BI search " pattern"
Search indexed names and descriptions.
.TP
.BI show " package"
Display the selected package record.
.TP
.BI which " package"
Show the selected repository and lower-priority candidates.
.TP
.B list
List configured repositories.
.TP
.B status
Show repository paths, priorities, and index state.
.PP
.B --raw
selects stable tab-separated output where supported.
.SH SELECTION
Higher numeric repository priority wins. Configuration order breaks equal
priority. Duplicate package names within one repository are rejected.
.SH GIT SAFETY
Git checkouts are created below
.BR $SPS_REPO_ROOT ,
which defaults to
.BR /usr/src/sps .
An existing checkout must be the expected top-level worktree and its
.B origin
URL must match the configured source exactly.
.PP
.B src update
refuses tracked or untracked local changes before fetching. It never runs
.BR "git reset" ,
.BR "git clean" ,
or an implicit checkout. A clean tracking branch is fast-forwarded only when
safe. Detached heads and branches without an origin upstream remain pinned;
locally ahead branches remain unchanged; divergent branches are refused.
Git prompts are disabled so a missing network fails instead of hanging.
.SH OPTIONS
.TP
.BR -q ", " --quiet
With
.B update ,
hide per-repository and per-recipe progress. The summary line still prints.
.SH FILES
.TP
.B /etc/sps/sps.conf
General SPS configuration.
.TP
.B /etc/sps/repos.conf
Repository declarations.
.TP
.B $SPS_CACHE/indexes/packages.index
Generated local package index.
.SH EXIT STATUS
Returns 0 on success, 2 for usage/configuration, 3 for missing index/package,
4 for malformed recipes/indexes, 5 for an invalid dependency graph, 6 for
hashing failure, 7 for a checkout conflict, 8 for permission failure, and 9 for
a Git network failure.
.SH SEE ALSO
.BR sget (1),
.BR mkpkg (1),
.BR sps.conf (5)