diff --git a/Cargo.lock b/Cargo.lock index efcae96..7bed80a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -479,9 +479,9 @@ checksum = "23fb14cb19457329c82206317a5663005a4d404783dc74f4252769b0d5f42856" [[package]] name = "log" -version = "0.4.26" +version = "0.4.27" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "30bde2b3dc3671ae49d8e2e9f044c7c005836e7a023ee57cffa25ab82764bb9e" +checksum = "13dc2df351e3202783a1fe0d44375f7295ffb4049267b0f3018346dc122a1d94" [[package]] name = "memchr" diff --git a/man/refractr.1 b/man/refractr.1 index e69de29..6f41719 100644 --- a/man/refractr.1 +++ b/man/refractr.1 @@ -0,0 +1,101 @@ +.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 (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