psi-jack/yadm
1
0
Fork 0
mirror of synced 2024-12-22 06:31:07 -05:00
Code Issues Releases Wiki Activity

Run mandoc or groff instead of man.REAL to check man page

Browse source 
Also fix all warnings reported by mandoc and apply some of the recommendations
from https://liw.fi/manpages/.
This commit is contained in:
Erik Flodin 2024-11-24 20:51:45 +01:00
parent 24772e7b4b
commit 216d49ceef
No known key found for this signature in database
GPG key ID: 420A7C865EE3F85F
3 changed files with 105 additions and 100 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Makefile
View file

@ -176,7 +176,7 @@ man-ps:
@groff -man -Tps ./yadm.1 > yadm.ps @groff -man -Tps ./yadm.1 > yadm.ps
yadm.md: yadm.1 yadm.md: yadm.1
@groff -man -Tutf8 -Z ./yadm.1 | grotty -c | col -bx | sed 's/^[A-Z]/## &/g' | sed '/yadm(1)/d' > yadm.md @groff -man -Tutf8 -Z ./yadm.1 | grotty -c | col -bx | sed 's/^[A-Z]/## &/g' | sed '/YADM(1)/d' > yadm.md
.PHONY: contrib .PHONY: contrib
contrib: SHELL = /bin/bash contrib: SHELL = /bin/bash

9
test/test_syntax.py
View file

@ -1,6 +1,7 @@
"""Syntax checks""" """Syntax checks"""
import os import os
import shutil
import pytest import pytest
@ -77,7 +78,11 @@ def test_yamllint(pytestconfig, runner, yamllint_version):
def test_man(runner): def test_man(runner):
"""Check for warnings from man""" """Check for warnings from man"""
run = runner(command=["man.REAL", "--warnings", "./yadm.1"]) if shutil.which("mandoc"):
command = ["mandoc", "-T", "lint"]
else:
command = ["groff", "-ww", "-z"]
run = runner(command=command + ["-man", "./yadm.1"])
assert run.success assert run.success
assert run.out == ""
assert run.err == "" assert run.err == ""
assert "yadm - Yet Another Dotfiles Manager" in run.out

194
yadm.1
View file

@ -1,5 +1,5 @@
.\" vim: set spell so=8: .\" vim: set spell so=8:
.TH yadm 1 "8 November 2024" "3.3.0" .TH YADM 1 "November 8, 2024" "3.3.0"
.SH NAME .SH NAME
@ -15,55 +15,55 @@ yadm \- Yet Another Dotfiles Manager
.I git-command-or-alias .I git-command-or-alias
.RI [ options ] .RI [ options ]
.B yadm .B yadm init
init .RB [ \-f ]
.RB [ -f ] .RB [ \-w
.RB [ -w
.IR dir ] .IR dir ]
.B yadm .B yadm clone
.RI clone " url .I url
.RB [ -f ] .RB [ \-f ]
.RB [ -w .RB [ \-w
.IR dir ] .IR dir ]
.RB [ -b .RB [ \-b
.IR branch ] .IR branch ]
.RB [ --bootstrap ] .RB [ \-\-bootstrap ]
.RB [ --no-bootstrap ] .RB [ \-\-no\-bootstrap ]
.B yadm .B yadm config
.RI config " name .I name
.RI [ value ] .RI [ value ]
.B yadm .B yadm config
config .RB [ \-e ]
.RB [ -e ]
.B yadm .B yadm list
list .RB [ \-a ]
.RB [ -a ]
.BR yadm " bootstrap .B yadm bootstrap
.BR yadm " encrypt .B yadm encrypt
.BR yadm " decrypt .B yadm decrypt
.RB [ -l ] .RB [ \-l ]
.BR yadm " alt .B yadm alt
.BR yadm " perms .B yadm perms
.BR yadm " enter [ command ] .B yadm enter
.RI [ command ]
.BR yadm " git-crypt [ options ] .B yadm git\-crypt
.RI [ options ]
.BR yadm " transcrypt [ options ] .B yadm transcrypt
.RI [ options ]
.BR yadm " upgrade .B yadm upgrade
.RB [ -f ] .RB [ \-f ]
.BR yadm " introspect .B yadm introspect
.I category .I category
.SH DESCRIPTION .SH DESCRIPTION
@ -83,8 +83,7 @@ Any command not internally handled by yadm is passed through to
.BR git (1). .BR git (1).
Git commands or aliases are invoked with the yadm managed repository. Git commands or aliases are invoked with the yadm managed repository.
The working directory for Git commands will be the configured The working directory for Git commands will be the configured
.IR work-tree " (usually .IR work-tree \ (usually\ $HOME ).
.IR $HOME ).
Dotfiles are managed by using standard Dotfiles are managed by using standard
.B git .B git
@ -95,7 +94,7 @@ commands;
.IR pull , .IR pull ,
etc. etc.
.RI The " config .RI The\ config
command is not passed directly through. command is not passed directly through.
Instead use the Instead use the
.I gitconfig .I gitconfig
@ -114,7 +113,7 @@ Execute
.I $HOME/.config/yadm/bootstrap .I $HOME/.config/yadm/bootstrap
if it exists. if it exists.
.TP .TP
.BI clone " url .BI clone \ url
Clone a remote repository for tracking dotfiles. Clone a remote repository for tracking dotfiles.
After the contents of the remote repository have been fetched, a "check out" of After the contents of the remote repository have been fetched, a "check out" of
the remote HEAD branch is attempted. the remote HEAD branch is attempted.
@ -130,15 +129,15 @@ By default,
will be used as the will be used as the
.IR work-tree , .IR work-tree ,
but this can be overridden with the but this can be overridden with the
.BR -w " option. .BR \-w \ option.
yadm can be forced to overwrite an existing repository by providing the yadm can be forced to overwrite an existing repository by providing the
.BR -f " option. .BR \-f \ option.
If you want to use a branch other than the remote HEAD branch If you want to use a branch other than the remote HEAD branch
you can specify it using the you can specify it using the
.BR -b " option. .BR \-b \ option.
By default yadm will ask the user if the bootstrap program should be run (if it By default yadm will ask the user if the bootstrap program should be run (if it
exists). The options exists). The options
.BR --bootstrap " or " --no-bootstrap .BR \-\-bootstrap " or " \-\-no\-bootstrap
will either force the bootstrap to be run, or prevent it from being run, will either force the bootstrap to be run, or prevent it from being run,
without prompting the user. without prompting the user.
.TP .TP
@ -153,10 +152,9 @@ See the CONFIGURATION section for more details.
Decrypt all files stored in Decrypt all files stored in
.IR $HOME/.local/share/yadm/archive . .IR $HOME/.local/share/yadm/archive .
Files decrypted will be relative to the configured Files decrypted will be relative to the configured
.IR work-tree " (usually .IR work-tree \ (usually\ $HOME ).
.IR $HOME ).
Using the Using the
.B -l .B \-l
option will list the files stored without extracting them. option will list the files stored without extracting them.
.TP .TP
.B encrypt .B encrypt
@ -191,12 +189,12 @@ Emacs Tramp and Magit can manage files by using this configuration:
With this config, use (magit-status "/yadm::"). With this config, use (magit-status "/yadm::").
.RE .RE
.TP .TP
.BI git-crypt " options .BI git-crypt \ options
If git-crypt is installed, this command allows you to pass options directly to If git-crypt is installed, this command allows you to pass options directly to
git-crypt, with the environment configured to use the yadm repository. git-crypt, with the environment configured to use the yadm repository.
git-crypt enables transparent encryption and decryption of files in a git repository. git-crypt enables transparent encryption and decryption of files in a git
You can read repository. You can read
https://github.com/AGWA/git-crypt https://github.com/AGWA/git-crypt
for details. for details.
.TP .TP
@ -232,17 +230,17 @@ By default,
will be used as the will be used as the
.IR work-tree , .IR work-tree ,
but this can be overridden with the but this can be overridden with the
.BR -w " option. .BR \-w \ option.
yadm can be forced to overwrite an existing repository by providing the yadm can be forced to overwrite an existing repository by providing the
.BR -f " option. .BR \-f \ option.
.TP .TP
.B list .B list
Print a list of files managed by yadm. Print a list of files managed by yadm.
.RB The " -a .RB The \ \-a
option will cause all managed files to be listed. option will cause all managed files to be listed.
Otherwise, the list will only include files from the current directory or below. Otherwise, the list will only include files from the current directory or below.
.TP .TP
.BI introspect " category .BI introspect \ category
Report internal yadm data. Supported categories are Report internal yadm data. Supported categories are
.IR commands , .IR commands ,
.IR configs , .IR configs ,
@ -259,12 +257,12 @@ configuration
.I yadm.auto-perms .I yadm.auto-perms
to "false". to "false".
.TP .TP
.BI transcrypt " options .BI transcrypt \ options
If transcrypt is installed, this command allows you to pass options directly to If transcrypt is installed, this command allows you to pass options directly to
transcrypt, with the environment configured to use the yadm repository. transcrypt, with the environment configured to use the yadm repository.
transcrypt enables transparent encryption and decryption of files in a git repository. transcrypt enables transparent encryption and decryption of files in a git
You can read repository. You can read
https://github.com/elasticdog/transcrypt https://github.com/elasticdog/transcrypt
for details. for details.
.TP .TP
@ -283,7 +281,7 @@ your submodules cannot be de-initialized, the upgrade will fail. The most
common reason submodules will fail to de-initialize is because they have local common reason submodules will fail to de-initialize is because they have local
modifications. If you are willing to lose the local modifications to those modifications. If you are willing to lose the local modifications to those
submodules, you can use the submodules, you can use the
.B -f .B \-f
option with the "upgrade" command to force the de-initialization. option with the "upgrade" command to force the de-initialization.
After running "yadm upgrade", you should run "yadm status" to review changes After running "yadm upgrade", you should run "yadm status" to review changes
@ -306,33 +304,33 @@ For example, the following alias could be used to override the repository
directory. directory.
.RS .RS
alias yadm='yadm --yadm-repo /alternate/path/to/repo' alias yadm='yadm \-\-yadm\-repo /alternate/path/to/repo'
.RE .RE
The following is the full list of universal options. The following is the full list of universal options.
Each option should be followed by a path. Each option should be followed by a path.
.TP .TP
.B -Y,--yadm-dir .B \-Y, \-\-yadm\-dir
Override the yadm directory. Override the yadm directory.
yadm stores its configurations relative to this directory. yadm stores its configurations relative to this directory.
.TP .TP
.B --yadm-data .B \-\-yadm\-data
Override the yadm data directory. Override the yadm data directory.
yadm stores its data relative to this directory. yadm stores its data relative to this directory.
.TP .TP
.B --yadm-repo .B \-\-yadm\-repo
Override the location of the yadm repository. Override the location of the yadm repository.
.TP .TP
.B --yadm-config .B \-\-yadm\-config
Override the location of the yadm configuration file. Override the location of the yadm configuration file.
.TP .TP
.B --yadm-encrypt .B \-\-yadm\-encrypt
Override the location of the yadm encryption configuration. Override the location of the yadm encryption configuration.
.TP .TP
.B --yadm-archive .B \-\-yadm\-archive
Override the location of the yadm encrypted files archive. Override the location of the yadm encrypted files archive.
.TP .TP
.B --yadm-bootstrap .B \-\-yadm\-bootstrap
Override the location of the yadm bootstrap program. Override the location of the yadm bootstrap program.
.SH CONFIGURATION .SH CONFIGURATION
@ -377,7 +375,8 @@ manually to update permissions.
This feature is enabled by default. This feature is enabled by default.
.TP .TP
.B yadm.auto-private-dirs .B yadm.auto-private-dirs
Disable the automatic creating of private directories described in the section PERMISSIONS. Disable the automatic creating of private directories described in the section
PERMISSIONS.
.TP .TP
.B yadm.cipher .B yadm.cipher
Configure which encryption system is used by the encrypt/decrypt commands. Configure which encryption system is used by the encrypt/decrypt commands.
@ -426,7 +425,7 @@ Disable the permission changes to
.IR $HOME/.ssh/* . .IR $HOME/.ssh/* .
This feature is enabled by default. This feature is enabled by default.
.RE .LP
The following "local" configurations are not stored in the The following "local" configurations are not stored in the
.IR $HOME/.config/yadm/config, .IR $HOME/.config/yadm/config,
they are stored in the local repository. they are stored in the local repository.
@ -438,7 +437,7 @@ By default, no class will be matched.
The local host can be assigned multiple classes using command: The local host can be assigned multiple classes using command:
.RS .RS
yadm config --add local.class <additional-class> yadm config \-\-add local.class <additional-class>
.RE .RE
.TP .TP
.B local.arch .B local.arch
@ -486,22 +485,22 @@ Value is compared case-insensitive.
These are the supported attributes, in the order of the weighted precedence: These are the supported attributes, in the order of the weighted precedence:
.TP .TP
.BR template , " t .BR template ,\ t
Valid when the value matches a supported template processor. Valid when the value matches a supported template processor.
See the TEMPLATES section for more details. See the TEMPLATES section for more details.
.TP .TP
.BR user , " u .BR user ,\ u
Valid if the value matches the current user. Valid if the value matches the current user.
Current user is calculated by running Current user is calculated by running
.BR "id -u -n" . .BR "id \-u \-n" .
.TP .TP
.BR hostname , " h .BR hostname ,\ h
Valid if the value matches the short hostname. Valid if the value matches the short hostname.
Hostname is calculated by running Hostname is calculated by running
.BR "uname -n" , .BR "uname \-n" ,
and trimming off any domain. and trimming off any domain.
.TP .TP
.BR class , " c .BR class ,\ c
Valid if the value matches the Valid if the value matches the
.B local.class .B local.class
configuration. configuration.
@ -510,38 +509,38 @@ Class must be manually set using
See the CONFIGURATION section for more details about setting See the CONFIGURATION section for more details about setting
.BR local.class . .BR local.class .
.TP .TP
.BR distro , " d .BR distro ,\ d
Valid if the value matches the distro. Valid if the value matches the distro.
Distro is calculated by running Distro is calculated by running
.B "lsb_release -si" .B "lsb_release \-si"
or by inspecting the ID from or by inspecting the ID from
.BR "/etc/os-release" . .BR "/etc/os-release" .
.TP .TP
.BR distro_family , " f .BR distro_family ,\ f
Valid if the value matches the distro family. Valid if the value matches the distro family.
Distro family is calculated by inspecting the ID_LIKE line from Distro family is calculated by inspecting the ID_LIKE line from
.B "/etc/os-release" .B "/etc/os-release"
(or ID if no ID_LIKE line is found). (or ID if no ID_LIKE line is found).
.TP .TP
.BR os , " o .BR os ,\ o
Valid if the value matches the OS. Valid if the value matches the OS.
OS is calculated by running OS is calculated by running
.BR "uname -s" . .BR "uname \-s" .
.TP .TP
.BR arch , " a .BR arch ,\ a
Valid if the value matches the architecture. Valid if the value matches the architecture.
Architecture is calculated by running Architecture is calculated by running
.BR "uname -m" . .BR "uname \-m" .
.TP .TP
.B default .B default
Valid when no other alternate is valid. Valid when no other alternate is valid.
.TP .TP
.BR extension , " e .BR extension ,\ e
A special "condition" that doesn't affect the selection process. Its purpose is A special "condition" that doesn't affect the selection process. Its purpose is
instead to allow the alternate file to end with a certain extension to instead to allow the alternate file to end with a certain extension to
e.g. make editors highlight the content properly. e.g. make editors highlight the content properly.
.LP
.LP
.BR NOTE : .BR NOTE :
The OS for "Windows Subsystem for Linux" is reported as "WSL", even The OS for "Windows Subsystem for Linux" is reported as "WSL", even
though uname identifies as "Linux". though uname identifies as "Linux".
@ -587,7 +586,8 @@ which looks like this:
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##os.Darwin .IR $HOME/path/example.txt " -> " $HOME/path/example.txt##os.Darwin
Since the hostname doesn't match any of the managed files, the more generic version is chosen. Since the hostname doesn't match any of the managed files, the more generic
version is chosen.
If running on a Linux server named "host4", the link will be: If running on a Linux server named "host4", the link will be:
@ -667,9 +667,10 @@ To use the j2cli Jinja template processor, specify the value of "j2" or
"j2cli". "j2cli".
.TP .TP
.B envtpl .B envtpl
To use the envtpl Jinja template processor, specify the value of "j2" or "envtpl". To use the envtpl Jinja template processor, specify the value of "j2" or
.LP "envtpl".
.LP
.BR NOTE : .BR NOTE :
Specifying "j2" as the processor will attempt to use j2cli or envtpl, whichever Specifying "j2" as the processor will attempt to use j2cli or envtpl, whichever
is available. is available.
@ -681,15 +682,15 @@ During processing, the following variables are available in the template:
Default Jinja or ESH Description Default Jinja or ESH Description
------------- ------------- ---------------------------- ------------- ------------- ----------------------------
yadm.arch YADM_ARCH uname -m yadm.arch YADM_ARCH uname \-m
yadm.class YADM_CLASS Last locally defined class yadm.class YADM_CLASS Last locally defined class
yadm.classes YADM_CLASSES All classes yadm.classes YADM_CLASSES All classes
yadm.distro YADM_DISTRO lsb_release -si yadm.distro YADM_DISTRO lsb_release \-si
yadm.distro_family YADM_DISTRO_FAMILY ID_LIKE from /etc/os-release yadm.distro_family YADM_DISTRO_FAMILY ID_LIKE from /etc/os-release
yadm.hostname YADM_HOSTNAME uname -n (without domain) yadm.hostname YADM_HOSTNAME uname \-n (without domain)
yadm.os YADM_OS uname -s yadm.os YADM_OS uname \-s
yadm.source YADM_SOURCE Template filename yadm.source YADM_SOURCE Template filename
yadm.user YADM_USER id -u -n yadm.user YADM_USER id \-u \-n
env.VAR Environment variable VAR env.VAR Environment variable VAR
.BR NOTE : .BR NOTE :
@ -767,8 +768,7 @@ configuration.
To use this feature, a list of patterns must be created and saved as To use this feature, a list of patterns must be created and saved as
.IR $HOME/.config/yadm/encrypt . .IR $HOME/.config/yadm/encrypt .
This list of patterns should be relative to the configured This list of patterns should be relative to the configured
.IR work-tree " (usually .IR work-tree \ (usually\ $HOME ).
.IR $HOME ).
For example: For example:
.RS .RS
@ -785,11 +785,12 @@ Paths beginning with a "!" will be excluded.
The The
.B yadm encrypt .B yadm encrypt
command will find all files matching the patterns, and prompt for a password. Once a command will find all files matching the patterns, and prompt for a
password has confirmed, the matching files will be encrypted and saved as password. Once a password has confirmed, the matching files will be encrypted
and saved as
.IR $HOME/.local/share/yadm/archive . .IR $HOME/.local/share/yadm/archive .
The "encrypt" and "archive" files should be added to the yadm repository so they are The "encrypt" and "archive" files should be added to the yadm repository so
available across multiple systems. they are available across multiple systems.
To decrypt these files later, or on another system run To decrypt these files later, or on another system run
.B yadm decrypt .B yadm decrypt
@ -832,7 +833,6 @@ repository. See the following web sites for more information:
- https://github.com/elasticdog/transcrypt - https://github.com/elasticdog/transcrypt
- https://github.com/AGWA/git-crypt - https://github.com/AGWA/git-crypt
.LP
.SH PERMISSIONS .SH PERMISSIONS
@ -841,7 +841,7 @@ dependent upon the user's umask. Because of this, yadm will automatically
update the permissions of some file paths. The "group" and "others" permissions update the permissions of some file paths. The "group" and "others" permissions
will be removed from the following files: will be removed from the following files:
.RI - " $HOME/.local/share/yadm/archive .RI -\ $HOME/.local/share/yadm/archive
- All files matching patterns in - All files matching patterns in
.I $HOME/.config/yadm/encrypt .I $HOME/.config/yadm/encrypt
@ -991,7 +991,7 @@ to the Git index and create a new commit
.B yadm remote add origin <url> .B yadm remote add origin <url>
Add a remote origin to an existing repository Add a remote origin to an existing repository
.TP .TP
.B yadm push -u origin master .B yadm push \-u origin master
Initial push of master to origin Initial push of master to origin
.TP .TP
.B echo ".ssh/*.key" >> $HOME/.config/yadm/encrypt .B echo ".ssh/*.key" >> $HOME/.config/yadm/encrypt