mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #982 from xexyl/sgit-man-page

Browse Source 
Add sgit.1 man page, minor fixes in sgit
This commit is contained in:
Landon Curt Noll authored and GitHub committed 2023-09-29 00:15:13 -07:00
2 parents 0c815a072f 90564ca6ae
commit d6b227130a
3 files changed
+210 -20
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/sgit/README.md
+25 -11
View File
@@ -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 `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 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 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 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` 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 can, depending on the sed commands, empty files! This is analogous to using both
@@ -48,7 +49,7 @@ evolution of the script.
## Usage ## Usage
```sh ```sh
usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option(s)] [-s sed] [-e command] <glob...> usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option] [-s sed] [-e command] <glob...>
-h print help and exit -h print help and exit
-V print version 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: sed -i overwrites existing files
WARNING: this will create another file for each file changed 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 WARNING: use of '-o -n' without '-I', can depending on
sed commands, empty files as if both sed -i and sed -n were sed commands, empty files as if both sed -i and sed -n were
used together 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 -s sed set path to sed
-e command append sed command to list of commands to execute on globs -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 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`! 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 ## Examples
@@ -236,11 +255,6 @@ you have make installed you can just run `make install` either as root or via
sudo make install 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 ## Limitations
One that comes to mind is you cannot specify `git ls-files` options but this One that comes to mind is you cannot specify `git ls-files` options but this
src/sgit/sgit.1
+172
View File
@@ -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 <https://github.com/xexyl/sgit/issues> .
src/sgit/sgit.sh
+13 -9
View File
@@ -21,9 +21,9 @@
# - Cody Boone Ferguson (@xexyl) # - 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] <glob...> USAGE="usage: $(basename "$0") [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option] [-s sed] [-e command] <glob...>
-h print help and exit -h print help and exit
-V print version 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: sed -i overwrites existing files
WARNING: this will create another file for each file changed 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 WARNING: use of '-o -n' without '-I', can depending on
sed commands, empty files as if both sed -i and sed -n were sed commands, empty files as if both sed -i and sed -n were
used together 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 -s sed set path to sed
-e command append sed command to list of commands to execute on globs -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 "$(basename "$0"): ERROR: you must specify at least one sed command and one glob" 1>&2
echo 1>&2 echo 1>&2
echo "$USAGE" 1>&2 echo "$USAGE" 1>&2
exit 2 exit 3
fi fi
# check that sed is executable # check that sed is executable
@@ -118,17 +120,17 @@ if [[ -z "$SED" ]]; then
echo "$(basename "$0"): ERROR: sed cannot be empty" 1>&2 echo "$(basename "$0"): ERROR: sed cannot be empty" 1>&2
echo 1>&2 echo 1>&2
echo "$USAGE" 1>&2 echo "$USAGE" 1>&2
exit 2 exit 3
elif [[ ! -f "$SED" ]]; then elif [[ ! -f "$SED" ]]; then
echo "$(basename "$0"): ERROR: sed is not a regular file: $SED" 1>&2 echo "$(basename "$0"): ERROR: sed is not a regular file: $SED" 1>&2
echo 1>&2 echo 1>&2
echo "$USAGE" 1>&2 echo "$USAGE" 1>&2
exit 2 exit 3
elif [[ ! -x "$SED" ]]; then elif [[ ! -x "$SED" ]]; then
echo "$(basename "$0"): ERROR: sed is not an executable file: $SED" 1>&2 echo "$(basename "$0"): ERROR: sed is not an executable file: $SED" 1>&2
echo 1>&2 echo 1>&2
echo "$USAGE" 1>&2 echo "$USAGE" 1>&2
exit 2 exit 3
fi fi
# also check number of remaining args # 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 "$(basename "$0"): ERROR: you must specify at least one glob" 1>&2
echo 1>&2 echo 1>&2
echo "$USAGE" 1>&2 echo "$USAGE" 1>&2
exit 2 exit 3
fi fi
# then check that this is a git repo! # then check that this is a git repo!
@@ -229,3 +231,5 @@ while [[ "$i" -lt "$GLOBS" ]]; do
fi fi
done done
exit 0