diff --git a/src/sgit/README.md b/src/sgit/README.md index 48920572a..458d0b5b5 100644 --- a/src/sgit/README.md +++ b/src/sgit/README.md @@ -25,9 +25,10 @@ Note that you **MUST** pass the `-` to the option and for long options like `sed` but prefixing it with `-o` first. This was a stylistic choice but it allows one to quote the option arg to pass more than one option instead of having to use `sgit -o` more than once. Note that not all options to `sed` have -been tested. +been tested. If the option requires an arg or you want to pass more than one +option you must quote it. -By default it does **in-place editing it does NOT backup files**. If you +By default it does **in-place editing; it does NOT backup files**. If you wish to not edit the file in place (see examples later in this file) you can use the `sgit -I` option. Note that the `-n` option (`sgit -o -n`) without `sgit -I` can, depending on the sed commands, empty files! This is analogous to using both @@ -48,7 +49,7 @@ evolution of the script. ## Usage ```sh -usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option(s)] [-s sed] [-e command] +usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option] [-s sed] [-e command] -h print help and exit -V print version and exit @@ -60,17 +61,19 @@ usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option(s)] [-s WARNING: sed -i overwrites existing files WARNING: this will create another file for each file changed - -o append sed options to options list + -o sed_option append sed options to options list WARNING: use of '-o -n' without '-I', can depending on sed commands, empty files as if both sed -i and sed -n were used together - NOTE: you must pass the '-' or '--' for long options! + NOTE: you must pass the '-' for short options and '--' for long options! + NOTE: if you pass more than one option or it takes an option arg you must + quote it! -s sed set path to sed -e command append sed command to list of commands to execute on globs -sgit version: 0.0.10-1 24-04-2023 +sgit version: 0.0.11-1 28-04-2023 ``` You **MUST** specify at least one `sed` command and one glob: the sed command by @@ -114,6 +117,22 @@ sgit -o -n -e 's/.//g' sgit because it would empty `sgit`! +## More about options and the tool itself + +A man page exists for this tool with more about the tool and the options. Since +this file has a number of examples there are no additional examples in it. To +render it: + +```sh +man sgit +``` + +if installed. Otherwise if it's not installed you can do: + +```sh +man ./sgit.1 +``` + ## Examples @@ -236,11 +255,6 @@ you have make installed you can just run `make install` either as root or via sudo make install ``` -## Documentation? - -Right now this is it but the Makefile is set up so that if a man page is added -it can easily install it as well. - ## Limitations One that comes to mind is you cannot specify `git ls-files` options but this diff --git a/src/sgit/sgit.1 b/src/sgit/sgit.1 new file mode 100644 index 000000000..219eb45ac --- /dev/null +++ b/src/sgit/sgit.1 @@ -0,0 +1,172 @@ +.\" section 1 man page for sgit +.\" +.\" sgit was written by Cody Boone Ferguson in 2023. +.\" +.\" Dedicated to my wonderful Mum and to my dear cousin Dani. +.\" +.TH sgit 1 "28 September 2023" "sgit" "IOCCC tools" +.SH NAME +.B sgit +\- run +.BR sed (1) +(by default with +.BR \-i ) +on one or more globs under +.BR git (1) +control +.SH SYNOPSIS +.B sgit +.RB [\| \-h \|] +.RB [\| \-V \|] +.RB [\| \-v +.IR level \|] +.RB [\| \-x \|] +.RB [\| \-I \|] +.RB [\| \-i +.IR extension \|] +.RB [\| \-o +.IR sed_option \|] +.RB [\| \-s +.IR sed \|] +.RB [\| \-e +.IR command \|] +.SH DESCRIPTION +.B sgit +allows one to run +.BR sed (1) +on one or more globs under +.BR git (1) +control. +By default it uses the in-place editing option +.B \-i (WITHOUT A BACKUP EXTENSION!) +but in place editing can be disabled with the +.B \-I +option. +If you wish to specify a backup extension use the +.B \-i +option but be aware that it will create a file for each file modified and it will overwrite any previously made backups. +Of course since it only acts on files under +.BR git (1) +control that shouldn't be a big problem but it is worth noting. +.PP +With the option +.B \-s +you can specify an alternative +.BR sed (1) +to use. +To specify +.BR sed (1) +options use +.BR \-o . +If it requires an option arg or you specify more than one option you need to quote it. +To specify a +.BR sed (1) +command use +.BR \-e . +.PP +If you want shell tracing enabled use the +.B \-x +option. +This is not very useful in most cases but it is good for debugging. +If you want verbose output to see what the script is doing you can specify a debug level with +.BR \-v . +.PP +Any text after the final option is considered a glob. +At least one +.BR sed (1) +command and one glob must be specified. +If you run the command from a directory that is not a +.BR git (1) +repo it is an error. +.SH OPTIONS +.TP +.B \-h +Show help and exit. +.TP +.B \-V +Show version and exit. +.TP +.BI \-v\ level +Set verbosity level. +.TP +.B \-x +Turn on tracing (set \-x) +.TP +.B -I +Disable in place editing +.TP +.BI \-i\ extension +Set backup extension (default none) +.RS +.PP +WARNING: sed \-i overwrites existing files +.br +WARNING: this will create another file for each file changed +.RE +.TP +.BI \-o\ sed_option +Append +.BR sed (1) +options to options list +.RS +.PP +WARNING: use of +.B \-o \-n +without +.BR \-I , +can depending on +.BR sed (1) +commands, empty files as if both +.BR sed (1) +options +.B \-i +and +.B \-n +were used together +.br +NOTE: you must pass the '-' for short options and '--' for long options! +.RE +.TP +.BI \-s\ sed +Set path to +.BR sed (1) +.TP +.BI \-e\ command +Append +.BR sed (1) +command to list of commands to execute on globs +.SH EXIT STATUS +.TP +0 +command succeeded, whether modifying any file or not +.TQ +1 +command not run in a +.BR git (1) +repository +.TQ +2 +.B \-h +and help string printed or +.B \-V +and version string printed +.TQ +3 +invalid command line, invalid option or option missing an argument +.SH NOTES +.PP +This tool was written by Cody Boone Ferguson due to a persistent problem where it was needed to modify with +.BR sed (1) +files but only those under +.BR git (1) +control and with certain globs, without having to first extract the paths and passing them all to +.BR sed (1). +It was finally written when he was helping the judges of the IOCCC, the International Obfuscated C Code Contest. +.SH BUGS +.PP +Cody Boone Ferguson wrote it! :) ) +.PP +On a more serious note there are no known bugs but if you have an issue with the tool please report it at the GitHub issues page. +You can find it at +.br +.IR . diff --git a/src/sgit/sgit.sh b/src/sgit/sgit.sh index a06890680..57ec0003b 100755 --- a/src/sgit/sgit.sh +++ b/src/sgit/sgit.sh @@ -21,9 +21,9 @@ # - Cody Boone Ferguson (@xexyl) # -export SGIT_VERSION="0.0.10-1 24-04-2023" # format: major.minor.patch-release DD-MM-YYYY +export SGIT_VERSION="0.0.11-1 28-04-2023" # format: major.minor.patch-release DD-MM-YYYY -USAGE="usage: $(basename "$0") [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option(s)] [-s sed] [-e command] +USAGE="usage: $(basename "$0") [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option] [-s sed] [-e command] -h print help and exit -V print version and exit @@ -35,12 +35,14 @@ USAGE="usage: $(basename "$0") [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o WARNING: sed -i overwrites existing files WARNING: this will create another file for each file changed - -o append sed options to options list + -o sed_option append sed options to options list WARNING: use of '-o -n' without '-I', can depending on sed commands, empty files as if both sed -i and sed -n were used together - NOTE: you must pass the '-' or '--' for long options! + NOTE: you must pass the '-' for short options and '--' for long options! + NOTE: if you pass more than one option or it takes an option arg you must + quote it! -s sed set path to sed -e command append sed command to list of commands to execute on globs @@ -110,7 +112,7 @@ if [[ -z "${SED_COMMANDS[*]}" ]]; then echo "$(basename "$0"): ERROR: you must specify at least one sed command and one glob" 1>&2 echo 1>&2 echo "$USAGE" 1>&2 - exit 2 + exit 3 fi # check that sed is executable @@ -118,17 +120,17 @@ if [[ -z "$SED" ]]; then echo "$(basename "$0"): ERROR: sed cannot be empty" 1>&2 echo 1>&2 echo "$USAGE" 1>&2 - exit 2 + exit 3 elif [[ ! -f "$SED" ]]; then echo "$(basename "$0"): ERROR: sed is not a regular file: $SED" 1>&2 echo 1>&2 echo "$USAGE" 1>&2 - exit 2 + exit 3 elif [[ ! -x "$SED" ]]; then echo "$(basename "$0"): ERROR: sed is not an executable file: $SED" 1>&2 echo 1>&2 echo "$USAGE" 1>&2 - exit 2 + exit 3 fi # also check number of remaining args @@ -136,7 +138,7 @@ if [[ "$#" -eq 0 ]]; then echo "$(basename "$0"): ERROR: you must specify at least one glob" 1>&2 echo 1>&2 echo "$USAGE" 1>&2 - exit 2 + exit 3 fi # then check that this is a git repo! @@ -229,3 +231,5 @@ while [[ "$i" -lt "$GLOBS" ]]; do fi done + +exit 0