sgit.1

.\" section 1 man page for sgit
.\"
.\" sgit was written by Cody Boone Ferguson in 2023.
.\"
.\" This is dedicated to the IOCCC (https://www.ioccc.org), the IOCCC judges
.\" (https://www.ioccc.org/judges.html), especially Landon Curt Noll
.\" (http://www.isthe.com/chongo/) for the friendship, telling me stories and
.\" jokes, telling me history of different things about Unix, C and other things
.\" and giving me the wonderful opportunity to help so much with the IOCCC -
.\" prompting me to write this tool - and above all my dear Mum Dianne and my
.\" wonderful cousin Dani.
.\"
.TH sgit 1 "06 November 2024" "sgit" ""
.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 [\| \-g
.IR git \|]
.RB [\| \-X
.IR xargs \|]
.RB [\| \-e
.IR command \|]
.RB [\| \-n \|]
.RB [\| \-t \|]
.RB [\| \-0 \|]
.IR glob...
.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)
and with
.B \-g
you can specify an alternate
.BR git (1)
and with
.B \-X
you can specify an alternate
.BR xargs (1)
to use, all of which are required.
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
The
.B \-n
option will enable dry\-run mode.
If there is a verbosity level greater than or equal to 1 it will show the
.BR sed (1)
command that would have been done on each file if the
.B \-n
option was not used.
Otherwise it will only show the files that would be acted on if the
.B \-n
option was not used.
.PP
If you wish to just test the
.BR sed (1)
commands without doing anything else, say to debug the commands before you perform them on any files, use the
.B \-t
option.
It will act on an empty string, redirecting standard output to /dev/null but any error will be shown.
With verbosity level 1 or greater it will show which
.BR sed (1)
command is being tested to help you identify which command has an error.
.PP
Any text after the final option is considered a glob.
At least one
.BR sed (1)
command and one glob must be specified unless
.B \-t
is used in which case a glob is not required.
A glob of
.I .
will match all files under git control from the current working directory.
.PP
If you require using the
.B \-z
option to
.B git ls\-files
along with
.B xargs \-0
then use the
.B \-0
option.
.PP
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 backup files
.br
WARNING: this will create or update a 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!
.br
NOTE: if you need a space in an option you should quote it!
.RE
.TP
.BI \-s\  sed
Set path to
.BR sed (1).
.TP
.BI \-g\  git
Set path to
.BR git (1).
.TP
.BI \-X\  xargs
Set path to
.BR xargs (1).
.TP
.BI \-e\  command
Append
.BR sed (1)
command to commands list to execute on globs.
.TP
.B \-n
Enable dry-mode.
If verbosity is set to greater than or equal to 1 it will show what
.BR sed (1)
commands would have been run on each file if the
.B \-n
option was not used; otherwise it will only show the files that would have been touched if the
.B \-n
option was not used.
.RS
.PP
Note that use of
.B \-n
prevents
.BR sed (1)
commands from being run.
.RE
.TP
.B \-t
Test the
.BR sed (1)
command or commands without performing them on any glob.
This can be useful to check for syntax errors before worrying about modifying files.
It acts on an empty string and will show only errors if any, exiting non-zero if there is an error and 0 if there is not.
Using
.B \-v
with a verbosity level greater than or equal to 1 can help you identify which sed command or commands have an error.
.TP
.B \-0
Use
.B git ls\-files \-z
and
.B xargs \-0\c
\&.

.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.
.PP
.BR sgit (1)
does not act on symlinks as this has, in my experience, caused a type change; edit the target file, not the symlink.
.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> .
.SH EXAMPLES
.PP
Change references (\c
.B IN MEMORY ONLY
i.e. \fBWITHOUT in\-place editing\fP\c
) of the exact word
.B sed
(as in \c
.BR \\\\<sed\\\\> )
in the
.B sgit
script to
.B used
but only show changed lines:
.IR
.sp
.RS
.ft B
sgit -I -o -n -e 's/\<sed\>/used/p' sgit
.ft R
.RE
.PP
Print out matches of the exact word
.B sed
(as in \c
.BR \\\\<sed\\\\> )
in all files under
.BR git (1)
control from the current working directory:
.IR
.sp
.RS
.ft B
sgit -I -o -n -e '/\<sed\>/p' .
.ft R
.sp
.RE
The above is a simpler way of running:
.IR
.sp
.RS
.ft B
git --no-pager grep -h -E '\<sed\>'|sed 's/^[0-9]*://g'
.ft R
.RE
.sp
.PP
With tracing enabled, change references of the exact word
.B sed
(as in \c
.BR \\\\<sed\\\\> )
in this file and save it:
.sp
.RS
.ft B
sgit -e 's/\<sed\>/used/g' -x sgit.1
.ft R
.RE
.PP
For more examples see the following link:
.IR \<https://github.com/xexyl/sgit#examples\>
.SH AUTHOR
Cody Boone Ferguson
.SH SEE ALSO
For additional details including the history, script history and other things about the tool, see:
.IR \<https://github.com/xexyl/sgit#readme\>