Add error trapping

.editorconfig

@@ -0,0 +1,36 @@
+# EditorConfig is awesome: https://editorconfig.org
+
+root = true
+# top-most EditorConfig file
+# root: special property that should be specified at the top of the file outside of any sections.
+# Set to "true" to stop .editorconfig files search on current file.
+
+[*]
+# Defaults
+
+indent_style= tab
+# set to "tab" or "space" to use hard tabs or soft tabs respectively.
+
+indent_size = 2
+# a whole number defining the number of columns used for each indentation level and the width of soft tabs (when supported).
+# When set to "tab", the value of tab_width (if specified) will be used.
+
+# tab_width = 2
+# a whole number defining the number of columns used to represent a tab character.
+# This defaults to the value of indent_size and doesn't usually need to be specified.
+
+end_of_line = lf
+# set to "lf", "cr", or "crlf" to control how line breaks are represented.
+
+charset = utf-8
+# set to "latin1", "utf-8", "utf-8-bom", "utf-16be" or "utf-16le" to control the character set.
+
+insert_final_newline = true
+# set to "true" to ensure file ends with a newline when saving and "false" to ensure it doesn't.
+
+trim_trailing_whitespace = true
+# set to "true" to remove any whitespace characters preceding newline characters and "false" to ensure it doesn't.
+
+max_line_length = 80
+# Forces hard line wrapping after the amount of characters specified.
+# "unset" to turn off this feature (use the editor settings).

.gitattributes

@@ -0,0 +1,11 @@
+# Use LF on checkout across all platforms (Linux, MacOSX, Windows)
+#   as most text files work well with LF on Windows.
+#   Exceptions can be added below.
+*      text eol=lf
+
+# Files that should have their EOL on checkout changed to CRLF.
+
+# Files that should retain their EOL on checkout but may be diff'ed.
+
+# Files that are truly binary - no EOL change on checkout and no diff.
+*.png  binary

.gitignore

@@ -0,0 +1,2 @@
+# vim
+*.swp

CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog]
+and this project adheres to [Semantic Versioning].
+
+## [Unreleased]
+### Added
+### Changed
+* 2026-04-21 8fa6c8b 💥 __BREAKING__ install: use [UAPI](https://uapi-group.org/specifications/specs/linux_file_system_hierarchy/#locallib)
+LIB directory [go2null]
+  standard.
+### Deprecated
+### Removed
+### Fixed
+* 2026-04-21 a32cb26 🐛 fix: ensure ssh agent is loaded before using ssh [go2null]
+* 2026-01-03 a53c3a9 🐛 fix logic bug - exit with success status if already sourced [go2null]
+### Security
+* 2026-04-21 e643931 🥅 add error trapping to sshag_ssh_* [go2null]
+* 2026-01-03 fa4dc98 🥅 use explicit return codes [go2null]
+
+## [3.0.3] - 2025-04-23
+### Added
+* _go2null_: 🔨 devex: set git EOL and EditorConfig defaults
+
+## [3.0.2] - 2025-04-04
+### Changed
+* _go2null_: 💄 removed extra whitespace from keys list
+* _go2null_: ⬆️ pearl: update to new standard
+
+## [3.0.1] - 2025-04-03
+### Fixed
+* _go2null_: ✏️ removed example code
+
+## [3.0.0] - 2025-04-03
+### Added
+* _go2null_: ✨ runs ssh-add automatically when shell starts
+* _go2null_: ✨ migrate existing installs to the new location
+### Changed
+* _go2null_: __BREAKING__: 💥 install to XDG_DATA_DIR/lib Directory
+### Fixed
+* _go2null_: 🐛 fix detecting when sourced in ZSH
+
+## [2.0.0] - 2022-04-01
+### Fixed
+* _go2null_: Fix bug #2 path to LICENSE.
+### Added
+* _go2null_: Ability to uninstall.
+### Changed
+* _go2null_: __BREAKING__: install now defaults to _system_ only if running as `root`.
+* _go2null_: __BREAKING__: install now defaults to `~/.local/lib` per `systemd` standard.
+
+## [1.3.1] - 2018-02-19
+### Added
+* _go2null_: Added support for [pearl] shell package manager.
+### Changed
+* _go2null_: Replaced regular `git` tags with annotated tags with changelog.
+* _go2null_: Moved __History__ section from `README.markdown` to `CHANGELOG.md`.
+* _go2null_: Renamed `README.markdown` to `README.md`.
+
+## [1.3.0] - 2018-01-17
+### Added
+* _go2null_: Allow passing arguments/options to `ssh`.
+* _go2null_: New `install` and `update` functions.
+
+## [1.2.1] - 2017-10-07
+## Added
+* _go2null_: Check if `ssh` supports `AddKeysToAgent` flag.
+## Changed
+* _go2null_: Fixed detection of identity files.
+* _go2null_: Fixed grep error when config file not found.
+
+## [1.2.0] - 2016-08-25
+### Added
+* _go2null_: Search `$TMPDIR` for agents as well, per OpenSSH man page.
+* _go2null_: Accept socket passed in.
+* _go2null_: Can now use `sshag user@domain` instead of `ssh user@domain`.
+### Changed
+* _go2null_: Make script POSIX compliant.
+
+## [1.1.0] - 2011-02-20
+### Added
+* _intuited_: Made it convenient to run the script in a subshell.
+
+## [1.0.0] - 2010-07-26
+### Added
+* _intuited_: Add readme and license documents.
+### Changed
+* _intuited_: __BREAKING__: Renamed from `sagent` to `sshag`.
+
+## [0.0.0] - 2010-05-14
+### Added
+* _Zed_: http://superuser.com/a/141241
+
+
+[Keep a Changelog]:    http://keepachangelog.com
+[Semantic Versioning]: http://semver.org
+[pearl]:               https://github.com/pearl-core/pearl#installation
+
+[Unreleased]: https://github.com/go2null/sshag/compare/3.0.3...HEAD
+[3.0.3]:      https://github.com/go2null/sshag/compare/3.0.2...3.0.3
+[3.0.2]:      https://github.com/go2null/sshag/compare/3.0.1...3.0.2
+[3.0.1]:      https://github.com/go2null/sshag/compare/3.0.0...3.0.1
+[3.0.0]:      https://github.com/go2null/sshag/compare/2.0.0...3.0.0
+[2.0.0]:      https://github.com/go2null/sshag/compare/1.3.0...2.0.0
+[1.3.1]:      https://github.com/go2null/sshag/compare/1.3.0...1.3.1
+[1.3.0]:      https://github.com/go2null/sshag/compare/1.2.1...1.3.0
+[1.2.1]:      https://github.com/go2null/sshag/compare/1.2.0...1.2.1
+[1.2.0]:      https://github.com/go2null/sshag/compare/1.1.0...1.2.0
+[1.1.0]:      https://github.com/go2null/sshag/compare/1.0.0...1.1.0
+[1.0.0]:      https://github.com/go2null/sshag/compare/0.0.0...1.0.0
+[0.0.0]:      https://github.com/go2null/sshag/releases/tag/0.0.0

README.markdown → README.md

@@ -1,48 +1,86 @@
-`sshag`
-=======
+# `sshag`
 
 ## "Socket to me, baby!"
 
-This is a sourceable shell include file which provides a `sshag` function
-to conveniently hook up with an operating ssh-agent.
+This is a sourceable shell include file which provides a `sshag` function to
+conveniently hook up with an operating `ssh-agent`.
 
 It will start a new agent session if it doesn't find an agent to connect with.
 
-You might want to source it from within your `~/.bashrc` file
-or other profile script.
+You might want to source it from within your `~/.bashrc` file or other profile
+script.
 
-It can also be run as an executable script,
-and its output stored in the relevant environment variable.
-This is particularly useful
-when it is desired to configure a non-shell environment,
-for example that of a text editor.
+It can also be run as an executable script, and its output stored in the
+relevant environment variable.  This is particularly useful when it is desired
+to configure a non-shell environment, for example, that of a text editor.
 
 Messages are emitted on standard out;
 the output will always consist of just the socket location.
 
-## Usage:
 
-Sourced:
-
-    $ ssh alotta@fagina.example.com
-    Enter passphrase for key '/home/austin/.ssh/id_dsa': ^C
-    $ source sshag.sh
-    $ sshag
-    Keys:
-        2048 0d:db:a1:1a:cc:01:ad:ec:ab:00:d1:ed:eb:ac:1e:00 /home/austin/.ssh/id_dsa (DSA)
-    /tmp/ssh-5ock3tt0m3/agent.6969
-    $ ssh alotta@fagina.example.com
-    ...
-
-Invoked:
-
-    $ export SSH_AGENT_SOCK=`sshag.sh`
-    Output should be assigned to the environment variable $SSH_AUTH_SOCK.
-    Keys:
-        2048 0d:db:a1:1a:cc:01:ad:ec:ab:00:d1:ed:eb:ac:1e:00 /home/austin/.ssh/id_dsa (DSA)
-
-Appended to `~/.bashrc`:
-    source ~/lib/sshag/sshag.sh; sshag &>/dev/null
+## Installation
+
+### Recommended installation method
+
+Use the [pearl] package manager.
+```sh
+# install
+pearl_conf="${XDG_CONFIG_HOME:-$HOME/.config}/pearl/pearl.conf"
+if grep '^}$' >/dev/null 2>&1 "$pearl_conf"; then
+  sed -i.bak 's/^}$//' "$pearl_conf"
+else
+  printf '%s\n' 'PEARL_PACKAGES = {' > "$pearl_conf"
+fi
+printf '"%s": {\n' 'sshag' >>"$pearl_conf"
+printf '"%s": "%s"\n' \
+	'url' 'https://github.com/go2null/sshag.git' \
+	>>"$pearl_conf"
+printf '"%s": "%s"\n' \
+	'description' 'Hook up with an operating or new SSH agent' \
+	>>"$pearl_conf"
+printf '{\n' >>"$pearl_conf"
+pearl install sshag
+
+# update
+pearl update sshag
+```
+
+### Manual installation
+
+```sh
+# install
+wget https://raw.githubusercontent.com/go2null/sshag/stable/sshag.sh
+sh sshag.sh install
+
+# update
+sshag update
+
+# uninstall/remove
+sshag remove
+```
+
+## Usage
+
+Sourced
+```sh
+$ ssh alotta@fagina.example.com
+Enter passphrase for key '/home/austin/.ssh/id_ed25519': ^C
+$ sshag alotta@fagina.example.com
+Keys:
+    256 SHA256:2TWr3x/H6eGvE+vx9Ur8uFQWBIXTBH3jT12yHBB4TJY austin@powers (ED25519)
+```
+
+Invoked
+```sh
+$ export SSH_AGENT_SOCK=$(sh ~/.local/share/lib/sshag/sshag.sh)
+Output should be assigned to the environment variable SSH_AUTH_SOCK.
+Keys:
+    256 SHA256:2TWr3x/H6eGvE+vx9Ur8uFQWBIXTBH3jT12yHBB4TJY austin@powers (ED25519)
+```
+
+## History
+
+See [CHANGELOG.md].
 
 ## Licensing
 
@@ -52,7 +90,7 @@ Creative Commons Attribution-Sharealike License,
 so I'm attributing it to the superuser.com user [Zed].
 SU currently links to [version 2.5] of the license.
 
-A copy of [the full license] is distributed herein in the file COPYING.
+A copy of [the full license] is distributed herein in the file [LICENSE].
 
 ### The basic gist of the license
 
@@ -90,12 +128,16 @@ A copy of [the full license] is distributed herein in the file COPYING.
     to others the license terms of this work. The best way to do this
     is with a link to this web page.
 
-[response]: http://superuser.com/questions/141044/sharing-the-same-ssh-agent-among-multiple-login-sessions#answer-141241
+
+[CHANGELOG.md]: https://github.com/go2null/sshag/blob/master/CHANGELOG.md
+[LICENSE]: https://github.com/go2null/sshag/blob/master/LICENSE
 [Zed]: http://superuser.com/users/33648/zed
-[version 2.5]: http://creativecommons.org/licenses/by-sa/2.5/
-[the full license]: http://creativecommons.org/licenses/by-sa/2.5/legalcode
-[waived]: http://wiki.creativecommons.org/Frequently_Asked_Questions#Can_I_change_the_terms_of_a_CC_license_or_waive_some_of_its_conditions.3F
-[public domain]: http://wiki.creativecommons.org/Public_domain
 [fair use]: http://wiki.creativecommons.org/Frequently_Asked_Questions#Do_Creative_Commons_licenses_affect_fair_use.2C_fair_dealing_or_other_exceptions_to_copyright.3F
 [moral]: http://wiki.creativecommons.org/Frequently_Asked_Questions#I_don.E2.80.99t_like_the_way_a_person_has_used_my_work_in_a_derivative_work_or_included_it_in_a_collective_work.3B_what_can_I_do.3F
+[pearl]: https://github.com/pearl-core/pearl#installation
+[public domain]: http://wiki.creativecommons.org/Public_domain
 [publicity]: http://wiki.creativecommons.org/Frequently_Asked_Questions#When_are_publicity_rights_relevant.3F
+[response]: http://superuser.com/questions/141044/sharing-the-same-ssh-agent-among-multiple-login-sessions#answer-141241
+[the full license]: http://creativecommons.org/licenses/by-sa/2.5/legalcode
+[version 2.5]: http://creativecommons.org/licenses/by-sa/2.5/
+[waived]: http://wiki.creativecommons.org/Frequently_Asked_Questions#Can_I_change_the_terms_of_a_CC_license_or_waive_some_of_its_conditions.3F

pearl-config/config.sh

@@ -0,0 +1,4 @@
+# shellcheck shell=sh
+
+# load `sshag` into current environment
+. "$PEARL_PKGDIR/sshag.sh"

pearl-config/hooks.sh

@@ -0,0 +1,9 @@
+# shellcheck shell=sh
+
+post_install() {
+	. "$PEARL_PKGDIR/pearl-config/config.sh"
+}
+
+post_update() {
+	post_install
+}