shsh.1

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH SHSH "1" "July 2024" "shell script handler v3.1.3" "User Commands"
.SH NAME
shsh \- manual page for shsh v3.1.3
.SH SYNOPSIS
.B shsh
\fI\,<command> \/\fR[\fI\,<command args>\/\fR] [\fI\,--verbose\/\fR] [\fI\,--help\/\fR]
.SH DESCRIPTION
A versatile shell scripts handler
.SS "Some useful shsh commands are:"
.TP
cleanup
Cleanup all broken links
.TP
commands
List all available shsh commands
.TP
completions
List completions for a command.
.TP
echo
A versatile shell scripts handler
.TP
edit
Edits the auto\-amending shshrc file with $EDITOR
.TP
get
Get the install command from $SHSHRC
.TP
help
Display help for a command
.TP
init
Configure the shell environment for shsh
.TP
install
Installs a package from github, custom site, or any arbitrary recipes.
.TP
junest
A transparently wrapper of junest with custom ignoring bins
.TP
link
Installs a local directory as a shsh package
.TP
list
List installed packages
.TP
outdated
Displays a list of outdated packages
.TP
package\-path
Outputs the path for a package
.TP
refresh
Refresh a package by unlinking and relinking everything
.TP
self\-linking
Link shsh's completion and man files to shsh's own cellar
.TP
self\-upgrade
Upgrades to latest version of shsh
.TP
uninstall
Uninstalls a package
.TP
upgrade
Upgrades a package
.PP
See `shsh <command> \fB\-\-help\fR` or `man shsh\-<command>` for specific help.
.SH OPTIONS
.TP
\fB\-\-help\fR
display help message for any commands
.TP
\fB\-\-version\fR
output version information and exit
.TP
\fB\-\-verbose\fR
display more info for some commands
.SH "SUBCMD: SHSH CLEANUP"
.B shsh
\fI\,cleanup \/\fR[\fI\,-d|--dry\/\fR]
.SS DESCRIPTION
Cleanup all broken links
.PP
Check all links within the cellar directories and remove all broken
links, i.e., delete all broken links in cellar/{bin,completions,man}
.SS OPTIONS
.TP
\fB\-d\fR, \fB\-\-dry\fR
perform a dry run of echoing what will be done
but do not perform any actual removal
.SH "SUBCMD: SHSH COMMANDS"
.B shsh
\fI\,commands\/\fR
.SS DESCRIPTION
List all available shsh commands
.PP
List out all the available commands that are intended to
be public. This does not contains any underscored (private)
commands.
.SH "SUBCMD: SHSH COMPLETIONS"
.B shsh
\fI\,completions <command>\/\fR
.SS DESCRIPTION
List completions for a command.
.PP
In order to support completions, a command must have a comment
with the 'completions' TAG and provide a '\-\-completions' argument.
.SH "SUBCMD: SHSH ECHO"
.B shsh
\fI\,<command> \/\fR[\fI\,<command args>\/\fR] [\fI\,--verbose\/\fR] [\fI\,--help\/\fR]
.SS DESCRIPTION
A versatile shell scripts handler
.SS "Some useful shsh commands are:"
.TP
cleanup
Cleanup all broken links
.TP
commands
List all available shsh commands
.TP
completions
List completions for a command.
.TP
echo
A versatile shell scripts handler
.TP
edit
Edits the auto\-amending shshrc file with $EDITOR
.TP
get
Get the install command from $SHSHRC
.TP
help
Display help for a command
.TP
init
Configure the shell environment for shsh
.TP
install
Installs a package from github, custom site, or any arbitrary recipes.
.TP
junest
A transparently wrapper of junest with custom ignoring bins
.TP
link
Installs a local directory as a shsh package
.TP
list
List installed packages
.TP
outdated
Displays a list of outdated packages
.TP
package\-path
Outputs the path for a package
.TP
refresh
Refresh a package by unlinking and relinking everything
.TP
self\-linking
Link shsh's completion and man files to shsh's own cellar
.TP
self\-upgrade
Upgrades to latest version of shsh
.TP
uninstall
Uninstalls a package
.TP
upgrade
Upgrades a package
.PP
See `shsh <command> \fB\-\-help\fR` or `man shsh\-<command>` for specific help.
.SS OPTIONS
.TP
\fB\-\-help\fR
display help message for any commands
.TP
\fB\-\-version\fR
output version information and exit
.TP
\fB\-\-verbose\fR
display more info for some commands
.SS ENVIRONMENT
The following environment variables has effects in `shsh` of
changing the default directories of stored files.
.TP
SHSH_ROOT
directory of shsh's root
.SH "DEFAULT: $XDG_DATA_HOME/SHSH"
.TP
SHSH_PREFIX
directory to store everything
.SH "DEFAULT: $SHSH_ROOT/CELLAR"
.TP
SHSH_PACKAGES_PATH
directory to store packages
.SH "DEFAULT: $SHSH_PREFIX/PACKAGES"
.TP
SHSH_INSTALL_BIN
directory to store bins
.SH "DEFAULT: $SHSH_PREFIX/BIN"
.TP
SHSH_INSTALL_MAN
directory to store mans
.SH "DEFAULT: $SHSH_PREFIX/MAN"
.PP
The following variables changes `shsh`'s linking behaviour by
overriding/customising the list of files to be linked into cellar.
They can be specified by 'package.sh' (see homepage), or with the
\fB\-\-variable\fR flag in `shsh install`, but setting them as environmental
variables will has no effect.
Note that all of the following variables can be a colon separated
list that follows the PATH variable convention, e.g. FOO:BAR
.TP
BINS
list of binary/script files to link
.SH "DEFAULT: ALL EXECUTABLE FILES IN ROOT AND BIN/*"
.TP
MANS
list of man pages to link
[default: all files in man/*.[0\-9] and
man/man.[0\-9]/*.[0\-9]]
.TP
MANS_ROOT
directory to search for mans. This has higher
priority than MANS.
[default: all files in man/*.[0\-9] and
man/man.[0\-9]/*.[0\-9]]
.TP
BASH_COMPLETIONS
list of bash shell completion files to link
.TP
.SS_COMPLETIONS
list of zsh shell completion files to link
.TP
FISH_COMPLETIONS
list of fish shell completion files to link
[default: all files in completions/*.fish and
completions/fish/*.fish]
.TP
DEPS
list of dependent packages to install beforehand
.TP
ROOT
specify a subfolder within the repo\-root to act
as where all operations are performed
.SS FILES
SHSHRC: The file `$XDG_CONFIG_HOME/shshrc` shall be a plain\-text file
that store all installed packages. Whenever shsh install a package, it
will add the package to SHSHRC. If there is an existing entry, it will
update that entry with the new flags/argunment instead. It will search
for all lines within SHSHRC that begins with `shsh install`, ignoring
all preceeding whitespace. For more details, visit project homepage.
.SS EXAMPLES
.TP
shsh install user/repo
install 'user/repo' as a package
.TP
shsh list
list all installed packages
.TP
shsh outdated
check against upstream on repos' status
.TP
shsh upgrade \-\-all
upgrade all installed packages
.TP
shsh uninstall user/repo
uninstall the package 'user/repo'
.SH "SUBCMD: SHSH EDIT"
.B shsh
\fI\,edit\/\fR
.SS DESCRIPTION
Edits the auto\-amending shshrc file with $EDITOR
.PP
Edits the auto\-amending shshrc file with $EDITOR
.SH "SUBCMD: SHSH GET"
.B shsh
\fI\,get <package>\/\fR
.SS DESCRIPTION
Get the install command from $SHSHRC
.PP
Get the install command from $SHSHRC
.SH "SUBCMD: SHSH HELP"
.B shsh
\fI\,help \/\fR[\fI\,--usage\/\fR] \fI\,COMMAND\/\fR
.SS DESCRIPTION
Display help for a command
.PP
Parses and displays help contents from a command's source file.
.PP
A command is considered documented if it starts with a comment block
that has a `Summary:' or `Usage:' section. Usage instructions can
span multiple lines as long as subsequent lines are indented.
The remainder of the comment block is displayed as extended
documentation.
.SH "SUBCMD: SHSH INIT"
.B eval
\fI\,"$(shsh init SHELL)"\/\fR
.SS DESCRIPTION
Configure the shell environment for shsh
.PP
SHELL: sh, bash, zsh, fish, etc.
.SH "SUBCMD: SHSH INSTALL"
.B shsh
\fI\,install \/\fR[\fI\,site\/\fR]\fI\,/<package>\/\fR[\fI\,@ref\/\fR] [\fI\,<folder>/<folder>\/\fR]
.SS DESCRIPTION
Installs a package from github, custom site, or any arbitrary recipes.
.TP
[\-h|\-\-hook <hook>] [\-v|\-\-variable <VAR>=<VAL>] [\-\-ssh]
[\-\-nocleanup] [\-f|\-\-force]
.TP
or:
shsh install \fB\-\-plain\fR <folder>/<folder>
.TP
[\-h|\-\-hook <hook>] [\-v|\-\-variable <VAR>=<VAL>]
[\-\-nocleanup] [\-f|\-\-force]
.SS OPTIONS
.HP
\fB\-h\fR, \fB\-\-hook\fR <HOOK_TYPE>[=<CONTENT>]
.IP
add HOOK to this package, which is triggered while
installing or upgrading a package
.HP
\fB\-r\fR, \fB\-\-recipe\fR interpret the given package name as a hosted recipt at
.IP
github.com/soraxas/shsh\-recipes.
.HP
\fB\-v\fR \fB\-\-variable\fR <VAR>=<VAL>
.IP
set a variable VAR with value VAL,
useful for setting up files for linking
.TP
\fB\-\-nocleanup\fR
do not perform cleanup (shsh uninstall <package>)
even if something failed in the installination process
.TP
\fB\-\-plain\fR
do not clone from a git repository; useful to use hooks
script to build a package from the ground up
.HP
\fB\-\-gh\-release\fR download binary assets from a github release; this
.IP
flag implies \fB\-\-plain\fR
TODO: currently it is bias towards linux and amd64;
.IP
to\-be generalised towards detecting current arch.
.TP
\fB\-f\fR, \fB\-\-force\fR
force the installation even if the package exists
.TP
\fB\-\-ssh\fR
use ssh protocal instead of https
.TP
\fB\-\-verbose\fR
display more info for some commands
.SS "Hook types:"
.TP
pre=<SCRIPT>
Any arbitrary POSIX script that runs before linking.
.TP
post=<SCRIPT>
Any arbitrary POSIX script that runs after linking.
.TP
uninstall=<...>
Any arbitrary POSIX script that runs before uninstalling.
For the above hooks, if multiples are given, the older
one will be overriden.
.TP
+x=<FILE>
Before linking, adds executable bit to the FILE. If
multiples are given, they will be run in sequential order.
.TP
a+x
Before linking, add executable bit to all files.
.SS EXAMPLES
.IP
shsh install soraxas/dot\-reminder
.IP
install 'soraxas/dot\-reminder' as a package
.IP
shsh install soraxas/git\-utils git/tools
.IP
install 'soraxas/git\-utils' to a folder within 'git/tools'
.IP
shsh install \-\-ssh <package>
.IP
install with ssh protocal (rather than https)
.IP
shsh install <package> \-v FISH_COMPLETIONS=synoservice.fish:forgit.fish
.IP
link 'synoservice.fish' and 'forgit.fish' as fish
completion files
.IP
shsh install <package> \-\-hook pre="mv bin/foo bin/bar"
.IP
Execute the script "mv bin/foo bin/bar" before `shsh`
performs linking (e.g. this script renames the binary)
.IP
shsh install <package> \-\-hook +x=foobar
.IP
add a hook that add executable bits to the file 'foobar',
before linking is performed
.IP
shsh install <package> \-h pre='make all' \-h post='rm \-r build/*'
.IP
add a hook that runs 'make all' to build binaries, right
after cloning and before linking is performed. Then,
linking is performed with its usual rules (i.e. all
executable files in root and in bin/). Finally,
\&'rm \-r build/*' is ran to remove leftovers.
.IP
shsh install \-\-plain wsl\-tools/win32yank \-h pre='curl \-sLo out.zip \e
.IP
https://<..>/releases/<..>.zip && unzip out.zip' \-h +x=win32yank.exe
.IP
add a plain package by using curl to download pre\-built
binary from upstream release page.
.SH "SUBCMD: SHSH JUNEST"
.B shsh
\fI\,junest \/\fR[\fI\,-h|--help\/\fR] \fI\,<sub_command>\/\fR
.SS DESCRIPTION
A transparently wrapper of junest with custom ignoring bins
.IP
shsh junest enter [argunments for junest...]
shsh junest link <executable_name>
shsh junest unlink <executable_name>
shsh junest linkable [package] [\-d|\-\-details]
shsh junest linked [\-d|\-\-details]
shsh junest packages [\-d|\-\-details]
shsh junest lookup <executable_name>
.PP
This can automatically bootstrap junest, which brings a lot of
packages from the arch linux community AUR via yay.
After bootstrapping, you can directly install packages via yay.
.SH "SUBCMD: SHSH LINK"
.B shsh
\fI\,link \/\fR[\fI\,--no-deps\/\fR] \fI\,<directory> <package> \/\fR[\fI\,-h|--hook <hook>\/\fR] [\fI\,-v|--variable <VAR>=<VAL>\/\fR]
.SS DESCRIPTION
Installs a local directory as a shsh package
.PP
Installs a local directory as a shsh package
.SH "SUBCMD: SHSH LIST"
.B shsh
\fI\,list \/\fR[\fI\,-d|--details\/\fR] [\fI\,-a|--all\/\fR] [\fI\,-i|--installed\/\fR]
.SS DESCRIPTION
List installed packages
.IP
.SH "\-S|\-\-SAVED"
.SS OPTIONS
.TP
\fB\-d\fR, \fB\-\-details\fR
display the URL of the repository
.TP
\fB\-i\fR, \fB\-\-installed\fR
display only the installed packages (default: true)
.TP
\fB\-s\fR, \fB\-\-saved\fR
display only the saved packages inside $SHSHRC
.TP
\fB\-a\fR, \fB\-\-all\fR
display both of the above
.SH "SUBCMD: SHSH OUTDATED"
.B shsh
\fI\,outdated \/\fR[\fI\,-q|--quiet\/\fR]
.SS DESCRIPTION
Displays a list of outdated packages
.PP
Displays a list of outdated packages
.SH "SUBCMD: SHSH PACKAGE PATH"
.B source
\fI\,"$(shsh package-path <package>)/file.sh"\/\fR
.SS DESCRIPTION
Outputs the path for a package
.PP
Outputs the path for a package
.SH "SUBCMD: SHSH REFRESH"
.B shsh
\fI\,refresh <package> \/\fR[\fI\,--verbose\/\fR] [\fI\,-a|--all\/\fR]
.SS DESCRIPTION
Refresh a package by unlinking and relinking everything
.PP
Note: verbose has no effect if \fB\-\-all\fR is specified, as they run in subshells
.SH "SUBCMD: SHSH SELF LINKING"
.B shsh
\fI\,self-linking\/\fR
.SS DESCRIPTION
Link shsh's completion and man files to shsh's own cellar
.PP
Link shsh's completion and man files to shsh's own cellar
.SH "SUBCMD: SHSH SELF UPGRADE"
.B shsh
\fI\,self-upgrade\/\fR
.SS DESCRIPTION
Upgrades to latest version of shsh
.PP
Upgrades to latest version of shsh
.SH "SUBCMD: SHSH UNINSTALL"
.B shsh
\fI\,uninstall <package>\/\fR
.br
.B shsh
\fI\,uninstall --use-rc \/\fR[\fI\,--noconfirm\/\fR]
.SS DESCRIPTION
Uninstalls a package
.SS OPTIONS
.TP
\fB\-\-use\-rc\fR
uninstall all packages that is not present in SHSHRC file
.TP
\fB\-\-noconfirm\fR
do not prompt to confirm uninstalling each package
.SH "SUBCMD: SHSH UPGRADE"
.B shsh
\fI\,upgrade <package> \/\fR[\fI\,-f|--force\/\fR]
.br
.B shsh
\fI\,upgrade <-a|--all>\/\fR
.SS DESCRIPTION
Upgrades a package
.SS OPTIONS
.TP
\fB\-a\fR, \fB\-\-all\fR
upgrade all packages, instead of invidivual package
.TP
\fB\-f\fR, \fB\-\-force\fR
force upgrade a package even if the cloned repository is
up\-to\-date
.TP
\fB\-\-nohooks\fR
supress the evaluation of existing hooks in SHSHRC file
(default is executing all previously saved hooks)
.SH ENVIRONMENT
The following environment variables has effects in `shsh` of
changing the default directories of stored files.
.TP
SHSH_ROOT
directory of shsh's root
[default: $XDG_DATA_HOME/shsh]
.TP
SHSH_PREFIX
directory to store everything
[default: $SHSH_ROOT/cellar]
.TP
SHSH_PACKAGES_PATH
directory to store packages
[default: $SHSH_PREFIX/packages]
.TP
SHSH_INSTALL_BIN
directory to store bins
[default: $SHSH_PREFIX/bin]
.TP
SHSH_INSTALL_MAN
directory to store mans
[default: $SHSH_PREFIX/man]
.PP
The following variables changes `shsh`'s linking behaviour by
overriding/customising the list of files to be linked into cellar.
They can be specified by 'package.sh' (see homepage), or with the
\fB\-\-variable\fR flag in `shsh install`, but setting them as environmental
variables will has no effect.
Note that all of the following variables can be a colon separated
list that follows the PATH variable convention, e.g. FOO:BAR
.TP
BINS
list of binary/script files to link
[default: all executable files in root and bin/*]
.TP
MANS
list of man pages to link
[default: all files in man/*.[0\-9] and
man/man.[0\-9]/*.[0\-9]]
.TP
MANS_ROOT
directory to search for mans. This has higher
priority than MANS.
[default: all files in man/*.[0\-9] and
man/man.[0\-9]/*.[0\-9]]
.TP
BASH_COMPLETIONS
list of bash shell completion files to link
.TP
ZSH_COMPLETIONS
list of zsh shell completion files to link
.TP
FISH_COMPLETIONS
list of fish shell completion files to link
[default: all files in completions/*.fish and
completions/fish/*.fish]
.TP
DEPS
list of dependent packages to install beforehand
.TP
ROOT
specify a subfolder within the repo\-root to act
as where all operations are performed
.SH FILES
SHSHRC: The file `$XDG_CONFIG_HOME/shshrc` shall be a plain\-text file
that store all installed packages. Whenever shsh install a package, it
will add the package to SHSHRC. If there is an existing entry, it will
update that entry with the new flags/argunment instead. It will search
for all lines within SHSHRC that begins with `shsh install`, ignoring
all preceeding whitespace. For more details, visit project homepage.
.SH EXAMPLES
.TP
shsh install user/repo
install 'user/repo' as a package
.TP
shsh list
list all installed packages
.TP
shsh outdated
check against upstream on repos' status
.TP
shsh upgrade \-\-all
upgrade all installed packages
.TP
shsh uninstall user/repo
uninstall the package 'user/repo'
.SH AUTHOR
Written by Tin Lai (@soraxas)
.SH "REPORTING BUGS"
Report bugs to <oscar@tinyiu.com>, or https://github.com/soraxas/shsh
.SH COPYRIGHT
Copyright \(co 2014 Juan Ibiapina, 2020 Tin Lai (@soraxas)
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B shsh (1),
.B shsh-cleanup (1),
.B shsh-commands (1),
.B shsh-completions (1),
.B shsh-echo (1),
.B shsh-edit (1),
.B shsh-get (1),
.B shsh-help (1),
.B shsh-init (1),
.B shsh-install (1),
.B shsh-junest (1),
.B shsh-link (1),
.B shsh-list (1),
.B shsh-outdated (1),
.B shsh-package-path (1),
.B shsh-refresh (1),
.B shsh-self-linking (1),
.B shsh-self-upgrade (1),
.B shsh-uninstall (1),
.B shsh-upgrade (1)