Add sgit.1 man page, minor fixes in sgit
Something that is lacking from the man page is that there are no examples. This is currently being justified by the fact that the README.md has examples but since that might not always be available this doesn't hold very well. This will likely be fixed another time when I have more energy, time and patience for it. As it is not clear to me how any documentation should be 'installed' I have not updated the Makefile to address this. That can be done later - or not for that matter. The usage string has been improved a bit. There was one thing that could be more clear and there was something missing too. Fixed exit codes when command line error. README.md now refers to the man page and the usage string was updated to match the usage string change. New version 0.0.11-1 28-04-2023.
This commit is contained in:
Cody Boone Ferguson committed
1 parent
3a2829f98e
commit
90564ca6ae
3 files changed
+210
-20
No files matched your search
+25
-11
@@ -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] <glob...>
|
||||
usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option] [-s sed] [-e command] <glob...>
|
||||
|
||||
-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
|
||||
|
||||
+172
@@ -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> .
|
||||
+13
-9
@@ -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] <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
|
||||
-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
|
||||
Reference in new issue
Block a user