From 084dc7c42a10ad639e2edfbbb7cde1a023959f23 Mon Sep 17 00:00:00 2001 From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com> Date: Fri, 29 Sep 2023 04:23:54 -0700 Subject: [PATCH] sgit updates (man page, usage string, README.md) Usage string improved a bit. Updated man page - added examples. Not all from the README.md have been added but it refers to the README.md (that section). Some of the examples refer to different files. Slightly changed formatting/wording of some of the examples. Clarify what the '.' glob means for those who do not know. There possibly were other things as well. New version 0.0.12-1 29-04-2023. --- src/sgit/README.md | 55 ++++++++++++++++++---------------- src/sgit/sgit.1 | 75 ++++++++++++++++++++++++++++++++++++++++++++-- src/sgit/sgit.sh | 11 ++++--- 3 files changed, 106 insertions(+), 35 deletions(-) diff --git a/src/sgit/README.md b/src/sgit/README.md index 458d0b5b5..94ac21ac0 100644 --- a/src/sgit/README.md +++ b/src/sgit/README.md @@ -1,13 +1,13 @@ # sgit - run sed on files under git control `sgit` runs `sed(1)` on files that are under git control, based on one or more -globs (either a pattern or an exact file name). Files not under git control in -the directory and any subdirectories will not be touched. Depending on the globs -specified it might or might not recurse into subdirectories. That is the shell -at work, of course. Running it in a directory that is not a git repository is an -error. +globs (either a pattern or an exact file name). Running this from a directory +that is not a git repository is an error and any files not under git control in +the directory will not be touched. Depending on the globs specified it might or +might not recurse into subdirectories. That is the shell at work, of course. +Running it in a directory that is not a git repository is an error. -This is extremely useful because one need not run extra commands to determine +`sgit` is extremely useful because one need not run extra commands to determine the list of files (which might be very long) and then pass them directly to `sed(1)`. @@ -24,21 +24,25 @@ Note that you **MUST** pass the `-` to the option and for long options like `--posix` you must pass `--`! In other words use the options like you would with `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. If the option requires an arg or you want to pass more than one -option you must quote it. +having to use `sgit -o` more than once though you can certainly use the option +more than once. Note that not all options to `sed` have been tested. If the +option requires a space (say for an arg) or you want to pass more than one +option separated by a space and you only use one `-o` 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 and 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 `-n` and `-i` to `sed` which would do in-place editing without automatic -printing of the pattern space. +printing of the pattern space. An example is provided later. If you wish to provide a backup extension for editing files use `sgit -i`. See example below. Note that using `-i` overwrites existing backup files and it will -also create a file for each file edited. This means that if it ends up editing -50 files there will be 50 new files created. +also create or update a file for each file edited. This means that if it ends up +editing 50 files without a backup file (with the extension provided) there will +be 50 new files created. Using this option might be of limited use, of course, +since files under git control can be restored, compared etc. but it's there in +case one wants it. See the usage below or run `sgit` by itself (or with the `-h` option) to see the rest of the options. @@ -58,28 +62,27 @@ usage: sgit [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o sed_option] [-s se -I disable in place editing -i extension set backup extension (default none) - WARNING: sed -i overwrites existing files - WARNING: this will create another file for each file changed + WARNING: sed -i overwrites existing backup files + WARNING: this will create or update a file for each file changed - -o sed_option append sed options to options list + -o sed_option append sed option or 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 '-' 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! + NOTE: if you need a space in an option you should 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.11-1 28-04-2023 +sgit version: 0.0.12-1 29-04-2023 ``` -You **MUST** specify at least one `sed` command and one glob: the sed command by -way of the `-e` option (just like with `sed`); anything after the last option is -a glob. You may specify more than one of each. Specify `-e` for each command. -The sed commands is an array just like the sed options. +You **MUST** specify at least one `sed` command and one glob: the `sed` command +by way of the `-e` option (just like with `sed`); anything after the last option +is a glob. You may specify more than one of each. Specify `-e` for each command. +The `sed` commands is an array just like the `sed` options. ## A note about the `-i` option and backup extensions @@ -93,7 +96,7 @@ option .. I'm looking at you, BSD/macOS `sed`). ## `sgit -i` WARNING: each file edited will result in another file in the working directory Of course if you have 50 files that are edited then 50 new files will be -created just like with `sed` itself. +created (or otherwise updated) just like with `sed` itself. # `sgit -i` WARNING: this **WILL OVERWRITE EXISTING BACKUP FILES**! @@ -136,13 +139,13 @@ man ./sgit.1 ## Examples -### Change in this file (_IN MEMORY ONLY_) `\` to `used` but only show lines changed: +### Change references (_**IN MEMORY ONLY**_ i.e. WITHOUT in-place editing) of the exact word `sed` (as in `\`) in this file but only show changed lines ```sh sgit -I -o -n -e 's/\/used/p' README.md ``` -### Print out matches of `\` in all files under git control +### Print out matches of the EXACT word `sed` (as in `\`) in all files under git control from the current working directory This is a simpler way of running `git --no-pager grep -h -E '\'|sed 's/^[0-9]*://g'` which itself might or might not be more complicated than it diff --git a/src/sgit/sgit.1 b/src/sgit/sgit.1 index 219eb45ac..92fa9d3b5 100644 --- a/src/sgit/sgit.1 +++ b/src/sgit/sgit.1 @@ -4,7 +4,7 @@ .\" .\" Dedicated to my wonderful Mum and to my dear cousin Dani. .\" -.TH sgit 1 "28 September 2023" "sgit" "IOCCC tools" +.TH sgit 1 "29 September 2023" "sgit" "IOCCC tools" .SH NAME .B sgit \- run @@ -75,6 +75,9 @@ Any text after the final option is considered a glob. At least one .BR sed (1) command and one glob must be specified. +A glob of +.I . +will match all files under git control from the current working directory. If you run the command from a directory that is not a .BR git (1) repo it is an error. @@ -99,9 +102,9 @@ Disable in place editing Set backup extension (default none) .RS .PP -WARNING: sed \-i overwrites existing files +WARNING: sed \-i overwrites existing backup files .br -WARNING: this will create another file for each file changed +WARNING: this will create or update a file for each file changed .RE .TP .BI \-o\ sed_option @@ -125,6 +128,8 @@ and 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 @@ -170,3 +175,67 @@ On a more serious note there are no known bugs but if you have an issue with the You can find it at .br .IR . +.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 \\\\ ) +in the +.B sgit +script to +.B used +but only show changed lines: +.IR +.sp +.RS +.ft B +sgit -I -o -n -e 's/\/used/p' sgit +.ft R +.RE +.PP +Print out matches of the exact word +.B sed +(as in \c +.BR \\\\ ) +in all files under +.BR git (1) +control from the current working directory: +.IR +.sp +.RS +.ft B +sgit -I -o -n -e '/\/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 's/^[0-9]*://g' +.ft R +.RE +.sp +.PP +With tracing enabled, change references of the exact word +.B sed +(as in \c +.BR \\\\ ) +in this file and save it: +.sp +.RS +.ft B +sgit -e 's/\/used/g' -x sgit.1 +.ft R +.RE +.PP +For more examples see the following link: +.IR \ +.SH SEE ALSO +For additional details including the history, script history and other things about the tool, see: +.IR \ diff --git a/src/sgit/sgit.sh b/src/sgit/sgit.sh index 57ec0003b..573781283 100755 --- a/src/sgit/sgit.sh +++ b/src/sgit/sgit.sh @@ -21,7 +21,7 @@ # - Cody Boone Ferguson (@xexyl) # -export SGIT_VERSION="0.0.11-1 28-04-2023" # format: major.minor.patch-release DD-MM-YYYY +export SGIT_VERSION="0.0.12-1 29-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 sed] [-e command] @@ -32,17 +32,16 @@ USAGE="usage: $(basename "$0") [-h] [-V] [-v level] [-x] [-I] [-i extension] [-o -I disable in place editing -i extension set backup extension (default none) - WARNING: sed -i overwrites existing files - WARNING: this will create another file for each file changed + WARNING: sed -i overwrites existing backup files + WARNING: this will create or update a file for each file changed - -o sed_option append sed options to options list + -o sed_option append sed option or 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 '-' 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! + NOTE: if you need a space in an option you should quote it! -s sed set path to sed -e command append sed command to list of commands to execute on globs