Organisation: | Copyright (C) 2008-2021 Olivier Boudeville |
Contact: | about (dash) hull (at) esperide (dot) com |
Creation date: | Sunday, August 17, 2008 |
Lastly updated: | Wednesday, March 3, 2021 |
Version: | 1.0.4 |
Dedication: | Users and maintainers of Ceylan-Hull, version 1.0. |
Abstract: | The role of Hull is to concentrate various, generic-purpose convenience shell scripts, on behalf of the Ceylan project. |
The latest version of this documentation is to be found at the official Ceylan-Hull website (http://hull.esperide.org).
This Hull documentation is also available in the PDF format (see Ceylan-Hull-technical-manual-english.pdf), and mirrored here.
Here are a few scripts, sorted by themes, that may be convenient for at least some users.
Many of them can display their intended usage on the console by specifying them the -h / --help command-line option.
In each category, scripts are roughly sorted by decreasing interest/update status. The scripts that we deem the most useful are described more precisely at the end of this document.
As much as possible, we try to name these scripts functionally rather than in terms of tools, so that the implementation they rely upon can be updated as transparently as possible (i.e. with as little change as possible in the user's habits).
Each script entry is a link pointing directly to the script itself.
Most of them are certainly not rocket science.
Note
Many of these scripts may be a bit outdated, as only a small subset of them are routinely used; rely on them with caution!
And tell us if you would like some of them to be updated.
- dci: assists efficiently and conveniently the commit of specified file(s)
- dci-all: selects recursively from current directory the files that should be committed (either added or modified), and commits them; for each of the modified files, shows the diff with previous version before requesting a commit message
- dif: shows on the console the differences between the current versions of the (possibly specified) files on the filesystem and the staged ones (i.e. the changes that might be added)
- difg: graphical version of dif
- dif-prev.sh: compares the current (committed) version of specified file(s) with their previous one
- difs: shows the differences between the staged files and their committed version
- st: shows the current VCS status of the specified files
- up: updates the current local version of the VCS repository
- show-branch-hierarchy.sh: shows the hierarchy of the branches in the current VCS repository
- crypt.sh: encrypts as strongly as reasonably possible the specified file(s), and removes their unencrypted sources
- decrypt.sh: decrypts specified file(s) (does not remove their encrypted version)
- for the management of credentials (i.e. sets of login/password):
- open-credentials.sh: unlocks (decrypts) the credential file whose path is read from the user environment, and opens it; once closed, re-locks it (with the same passphrase)
- lock-credentials.sh: locks (encrypts) the credential file whose path is read from the user environment
- unlock-credentials.sh: unlocks (decrypts) the credential file whose path is read from the user environment
- lock-screen.sh: locks immediately the screen
- inspect-opened-ports.sh: lists the local TCP/UDP ports that are currently opened
- adb-pull.sh: uploads specified local files, possibly based on expressions to the already connected and authorizing Android device
- adb-push.sh: downloads in the current directory, from the already connected and authorizing Android device, files and directories (recursively)
- set-usb-tethering.sh: sets (or stops) USB tethering on local host, typically so that a smartphone connected through USB and with such tethering enabled shares its Internet connectivity with this host
- archive-emails.sh: archives properly and reliably (compressed, cyphered, possibly transferred) the user emails
- Manages reference version of files, by storing them in a "vault":
- catch.sh: stores a file in a vault directory and makes a symbolic link to it, so that even if current tree is removed, this file will not be lost
- retrieve.sh: retrieves at least one file already stored in vault by creating link towards it, from current directory
- update-directory-from-vault.sh: updates all files in specified directory from their vault counterparts
- make-git-archive.sh: makes a backup (as an archived GIT bundle) of specified project directory, stored in specified archive directory
- snapshot.sh: performs a snapshot (tar.xz.gpg archive) of specified directory
- list-for-backup.sh: enumerates in current directory all files, specifies their name, size and MD5 sum, and stores the result in a relevant file
- notify.sh: notifies the user about specified message, possibly with a title and a category
- timer-at.sh: requests to trigger a timer notification at specified (absolute) timestamp
- timer-in.sh: requests to trigger a timer notification in specified duration
- timer-every.sh: requests to trigger (indefinitely, just use CTRL-C to stop) a timer notification every specified duration
- start-jam-session.sh: starts a jam session interrupted by a notification every period, to avoid remaining still for too long
- bong.sh: plays the specified number of bong sound(s)
- beep.sh: plays a beep to notify the user of an event
To facilitate shell sessions:
- mo: shorthand for a relevant version of more
- hide.sh: hides specified file or directory (simply by adding a -hidden suffix to its filename), while unhide.sh does the reverse operation
- set-display.sh: sets the X display to specified host; if none is specified, sets it to the local one
- get-date.sh: returns the current date in our standard short format (ex: 20210219)
- wh
wh (for "where"): searches (as a more user-friendly 'find') all files and directories matching <filePattern>, from <starting_directory> if specified, otherwise from current directory.
Usage: wh [-h|--help] [--verbose] [-q|--quiet] [--no-path] [--exclude-path <a directory>] <filePattern> [<startingDirectory>]
Options:
[-q|--quiet]: only returns file entries (no extra display); suitable for scripts (ex: for f in $(wh -q 'foo*'); do...)
--no-path: returns the filenames without any leading path
--exclude-path DIR: excludes specified directory DIR from search
- regrep
regrep: recursive grep for the ones that lack it.
Usage: regrep [-v|--verbose] [-q|--quiet] [-i|--insensitive] [-r|--restructured] <Expression to be found in files> [<Filter on files>]
Options:
-v or --verbose: be specifically verbose
-q or --quiet: be specifically quiet, just listing matches
-f or --filenames-only: display only filenames, not also the matched patterns, and if there are multiple matches in the same file, its filename will be output only once (implies quiet)
-i or --insensitive: perform case-insensitive searches in the content of files, and also when filtering any filenames
-r or --restructured: use ReStructured text mode (skip tmp-rst directories, search only
*.rst files)
Example: regrep -i 'little red rooster' '*.txt'
- srm
srm (for "secure rm"): stores deleted files in a trash instead of deleting them directly, in order to give one more chance of retrieving them if necessary. Ensures that no two filenames can collide in trash so that all contents are preserved.
Usage: srm <files to delete securely>
See also: emptyTrash.sh
- the tests subdirectory, for a few tests of specific facilities provided here
- the mostly-obsolete subdirectory, for the scripts we deprecated
Bugs, questions, remarks, patches, requests for enhancements, etc. are to be reported to the project interface (typically issues) or directly at the email address mentioned at the beginning of this longer document.
If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line! (for that, follow the Support guidelines).