101 lines
5.1 KiB
Groff
101 lines
5.1 KiB
Groff
.TH REFRACTR 1 "Updated 2025-03-25" "Bryson Steck"
|
|
.SH NAME
|
|
refractr \- an automated push mirroring utility for Git repositories
|
|
.SH SYNOPSIS
|
|
.B refractr
|
|
[\fBOPTIONS\fR]
|
|
.SH DESCRIPTION
|
|
refractr is an automated push mirroring utility for Git repositories.
|
|
|
|
With no options, refractr will attempt to load the config located at /etc/refractr/config.toml and run with that configuration.
|
|
For details for configuration files, see CONFIGURATION OPTIONS.
|
|
.SH OPTIONS
|
|
.sp
|
|
.TP 0.5i
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
Display a brief help message on the command line.
|
|
.TP 0.5i
|
|
\fB\-v\fR, \fB\-\-version\fR
|
|
Display the version of refractr on the command line.
|
|
.TP 0.5i
|
|
\fB\-c\fR, \fB\-\-config\fR [FILE]
|
|
Specify the absolute or relative path to a configuration file. Multiple configuration files can be specified by using multiple flags.
|
|
.P
|
|
.TP 0.5i
|
|
\fB\-v\fR, \fB\-\-verbose...\fR
|
|
Specify the level of verbose messages for refractr to output.
|
|
The functionality of this flag is similar to ssh(1); adding multiple flags will increase the amount of output with specific messages to what refractr is doing.
|
|
The more flags specified, the more low-level messages will appear.
|
|
.TP 0.5i
|
|
\fB\-e\fR, \fB\-\-create\fR
|
|
Print a full, commented config file to the standard output and exit. You can use this to generate config files that you can fill in and pass to refractr with the -c flag.
|
|
Information on the values for a refractr configuration can be found in the CONFIGURATION section.
|
|
.TP 0.5i
|
|
\fB\-s\fR, \fB\-\-strict\fR
|
|
Enable strict mode.
|
|
|
|
By design, refractr will ignore problems that occur when pushing to remotes and verifying host signatures when using SSH remotes.
|
|
Some of these errors may include networking issues and a host missing from your SSH known_hosts file, but refractr takes your configurations as
|
|
implicit trust that the remotes you pull/push from are correct and reachable. This also makes it so refractr will continuously try to
|
|
update the remotes with changes from the upstream repository to avoid synchronization issues.
|
|
|
|
If you wish for refractr to exit on these kinds of errors as a way to know of these issues, you can use this flag to enable "strict" mode.
|
|
Doing so will make refractr exit instead of continue or loop forever when encountering these problems.
|
|
.TP 0.5i
|
|
\fB\-p\fR, \fB\-\-persist\fR
|
|
Do not recursively delete the working directory as defined in your configuration file(s).
|
|
This can be helpful for troubleshooting issues with your repository, a potential bug with refractr, or general development.
|
|
.P
|
|
.SH CONFIGURATION
|
|
Below are the values for defining a refractr configuration.
|
|
.TP 0.5i
|
|
\fBfrom (string, REQUIRED)\fR
|
|
The original/upstream repository URI. This field MUST START with "https://" or "ssh://".
|
|
.TP 0.5i
|
|
\fBto (array, REQUIRED)\fR
|
|
The list of remotes you wish to push the repo to as cloned from the "from" field.
|
|
This field must be SSH remotes and the repository must exist on the remotes.
|
|
.TP 0.5i
|
|
\fBbranches (array, REQUIRED)\fR
|
|
The list of branches from the original/upstream repository you wish to push to the remotes.
|
|
.TP 0.5i
|
|
\fBwork_dir (string, OPTIONAL)\fR
|
|
The path on the filesystem refractr will clone this repository to and work from.
|
|
If omitted, this field defaults to "/tmp/refractr" on UNIX(-like) systems and "$env:TEMP\\refractr" on Windows.
|
|
.TP 0.5i
|
|
\fBpush_tags (boolean, REQUIRED)\fR
|
|
Push tags pulled from the original/upstream repository to the remotes.
|
|
.TP 0.5i
|
|
\fBgit.ssh_identity_file (string, REQUIRED)\fR
|
|
The path to your SSH private key for authenticating to the remotes specified in the "from" (if using SSH) and "to" fields.
|
|
|
|
If using Docker, you will need to copy your private key to your container or build it in an image using secrets in your Dockerfile.
|
|
.TP 0.5i
|
|
\fBschedule.enabled (bool, REQUIRED)\fR
|
|
Enable the schedule feature of refractr. This allows you to regularly pull updates and push them out on a regular basis.
|
|
.TP 0.5i
|
|
\fBschedule.interval (integer, DEPENDS ON schedule.enabled)\fR
|
|
The amount of time in seconds to pull updates and push them out to remotes.
|
|
To avoid creating unneeded stress on servers, this value must be greater than or equal to 60.
|
|
|
|
If "schedule.enabled" is false, refractr will not check for this value.
|
|
If "scheduled.enabled" is true, refractr will check this value. If it does not exist or is less than 60, refractr will return an error.
|
|
.SH AUTHORS
|
|
.B Bryson Steck <me@brysonsteck.xyz> (https://brysonsteck.xyz)
|
|
.P
|
|
.SH CONTRIBUTE
|
|
refractr is free and open source! Please report any bugs in, provide feedback for, or contribute to refractr by visiting the Codeberg repository:
|
|
.IR https://codeberg.org/brysonsteck/refractr
|
|
|
|
The Codeberg repository is proof of refractr at work. An upstream, read-only version of the repository is also available at:
|
|
.IR https://git.brysonsteck.xyz/brysonsteck/refractr
|
|
.P
|
|
.SH LICENSE
|
|
Copyright 2025 Bryson Steck
|
|
|
|
The binaries and source code of refractr is distributed under and subject to the terms of the Mozilla Public License v2 (MPL-2.0).
|
|
A copy of this license should have been distributed with this software. If you did not receive a copy, you can view the license at:
|
|
.IR https://www.mozilla.org/en-US/MPL/2.0/
|
|
|
|
License violations can be reported by creating an issue in the Codeberg repository under the CONTRIBUTE section.
|
|
.EFRATR
|