ci: add a check that the usage is up-to-date

.github/workflows/build_and_test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout sources
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Install stable toolchain
         uses: actions-rs/toolchain@v1
@@ -22,18 +22,46 @@ jobs:
 
       - name: Cache dependencies
         uses: Swatinem/rust-cache@v1
-
+      
       - name: Run cargo check
         uses: actions-rs/cargo@v1
         with:
           command: check
+
+      - name: Run cargo build
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+
+      - name: Append usage to the README.md
+        shell: bash
+        run: ./update-docs.sh
+
+      - name: Verify no unstaged changes
+        shell: bash
+        run: |
+          if [[ "$(git status --porcelain)" != "" ]]; then
+            echo ----------------------------------------
+            echo git status
+            echo ----------------------------------------
+            git status
+            echo ----------------------------------------
+            echo git diff
+            echo ----------------------------------------
+            git diff
+            echo ----------------------------------------
+            echo Troubleshooting
+            echo ----------------------------------------
+            echo "::error::Unstaged changes detected. You probably need to update the usage in the README.md.  Use `./update-docs`."
+            exit 1
+          fi
 
   lints:
     name: Lints
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout sources
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Install stable toolchain
         uses: actions-rs/toolchain@v1

.github/workflows/publish.yml

@@ -65,7 +65,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Rust
         uses: dtolnay/rust-toolchain@master

README.md

@@ -46,64 +46,74 @@ fqgrep -r 'GACGAGATTA' -a 'GACGTGATTA' --r1-fastq /data/testR1.fastq.gz  --r2-fa
 
 See the following for usage:
 
+<!-- start usage -->
 ```console
-$ fqgrep -h
-fqgrep 1.0.3
-The fqgrep utility searches any given input FASTQ files, selecting records whose bases match one or more patterns.  By
-default, a pattern matches the bases in a FASTQ record if the regular expression (RE) in the pattern matches the bases.
-An empty expression matches every line.  Each FASTQ record that matches at least one of the patterns is written to the
-standard output.
+
+OVERVIEW
+
+The fqgrep utility searches any given input FASTQ files, selecting records whose bases match one or more patterns.  By default, a pattern matches the bases in a FASTQ record if the regular expression (RE) in the pattern matches the bases.  An empty expression matches every line.  Each FASTQ record that matches at least one of the patterns is written to the standard output.
 
 INPUT COMPRESSION
 
-By default, the input files are assumed to be uncompressed with the following exceptions: (1) If the input files are
-real files and end with `.gz` or `.bgz`, they are assumed to be GZIP compressed, or (2) if they end with `.fastq` or
-`.fq`, they are assumed to be uncompressed, or (3) if the `-Z/--decompress` option is specified then any unrecongized
-inputs (including standard input) are assumed to be GZIP compressed.
+By default, the input files are assumed to be uncompressed with the following exceptions: (1) If the input files are real files and end with .gz or .bgz, they are assumed to be GZIP compressed, or (2) if they end with .fastq or .fq, they are assumed to be uncompressed, or (3) if the -Z/--decompress option is specified then any unrecongized inputs (including standard input) are assumed to be GZIP compressed.
 
 THREADS
 
-The `--threads` option controls the number of threads used to _search_ the reads. Independently, for single end reads or
-interleaved paired end reads, a single thread will be used to read each input FASTQ.  For paired end reads across pairs
-of FASTQs, two threads will be used to read the FASTQs for each end of a pair.  Finally, a single thread will be created
-for the writer.
+The --threads option controls the number of threads used to search the reads. Independently, for single end reads or interleaved paired end reads, a single thread will be used to read each input FASTQ.  For paired end reads across pairs of FASTQs, two threads will be used to read the FASTQs for each end of a pair.  Finally, a single thread will be created for the writer.
 
 EXIT STATUS
 
-The fqgrep utility exits with one of the following values: 0 if one or more lines were selected, 1 if no lines were
-selected, and >1 if an error occurred.
-
-USAGE:
-    fqgrep [FLAGS] [OPTIONS] [--] [args]...
-
-FLAGS:
-    -c, --count                 Only a count of selected lines is written to standard output
-    -F, --fixed-strings         Interpret pattern as a set of fixed strings
-    -v                          Selected lines are those not matching any of the specified patterns
-    -Z, --decompress            Assume all unrecognized inputs are GZIP compressed
-        --paired                Treat the input files as paired.  The number of input files must be a multiple of two,
-                                with the first file being R1, second R2, third R1, fourth R2, and so on.  If the pattern
-                                matches either R1 or R2, then both R1 and R2 will be output (interleaved).  If the input
-                                is standard input, then treat the input as interlaved paired end reads
-        --reverse-complement    Search the reverse complement for matches
-        --progress              Write progress information
-    -h, --help                  Prints help information
-    -V, --version               Prints version information
-
-OPTIONS:
-    -t, --threads <threads>     The number of threads to use for matching reads against pattern.  See the full usage for
-                                threads specific to reading and writing [default: 12]
-        --color <color>         Mark up the matching text.  The possible values of when are “never”, “always” and “auto”
-                                [default: never]
-    -e, --regexp <regexp>...    Specify a pattern used during the search of the input: an input line is selected if it
-                                matches any of the specified patterns.  This option is most useful when multiple `-e`
-                                options are used to specify multiple patterns
-    -f, --file <file>           Read one or more newline separated patterns from file.  Empty pattern lines match every
-                                input line.  Newlines are not considered part of a pattern.  If file is empty, nothing
-                                is matched
-
-ARGS:
-    <args>...    The first argument is the pattern to match, with the remaining arguments containing the files to
-                 match.  If `-e` is given, then all the arguments are files to match. Use standard input if either
-                 no files are given or `-` is given
+The fqgrep utility exits with one of the following values: 0 if one or more lines were selected, 1 if no lines were selected, and >1 if an error occurred.
+
+Usage: fqgrep [OPTIONS] [ARGS]...
+
+Arguments:
+  [ARGS]...
+          The first argument is the pattern to match, with the remaining arguments containing the files to match.  If -e is given, then all the arguments are files to match. Use standard input if either no files are given or - is given
+
+Options:
+  -t, --threads <THREADS>
+          The number of threads to use for matching reads against pattern.  See the full usage for threads specific to reading and writing
+
+          [default: 10]
+
+      --color <COLOR>
+          Mark up the matching text.  The possible values of when are “never”, “always” and “auto”
+
+          [default: never]
+          [possible values: never, always, auto]
+
+  -c, --count
+          Only a count of selected lines is written to standard output
+
+  -e, --regexp <REGEXP>
+          Specify a pattern used during the search of the input: an input line is selected if it matches any of the specified patterns.  This option is most useful when multiple -e options are used to specify multiple patterns
+
+  -F, --fixed-strings
+          Interpret pattern as a set of fixed strings
+
+  -f, --file <FILE>
+          Read one or more newline separated patterns from file.  Empty pattern lines match every input line.  Newlines are not considered part of a pattern.  If file is empty, nothing is matched
+
+  -v
+          Selected lines are those not matching any of the specified patterns
+
+  -Z, --decompress
+          Assume all unrecognized inputs are GZIP compressed
+
+      --paired
+          Treat the input files as paired.  The number of input files must be a multiple of two, with the first file being R1, second R2, third R1, fourth R2, and so on.  If the pattern matches either R1 or R2, then both R1 and R2 will be output (interleaved).  If the input is standard input, then treat the input as interlaved paired end reads
+
+      --reverse-complement
+          Search the reverse complement for matches
+
+      --progress
+          Write progress information
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
 ```
+<!-- end usage -->

update-docs.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -euo pipefail
+
+echo -e "<!-- start usage -->\n\`\`\`console\n" > usage.txt;
+# the `sed` is needed since the # of cores detected may differ across environments
+./target/debug/fqgrep --help | ./target/debug/fqgrep --help | sed -e '\/[default: [0-9]*\]/ s/\[default: [0-9]*\]/[default: 10]/' >> usage.txt;
+echo -e "\`\`\`\n<!-- end usage -->" >> usage.txt;
+sed -e '/<!-- start usage -->/,/<!-- end usage -->/!b' -e '/<!-- end usage -->/!d;r usage.txt' -e 'd' README.md > README.md.new;
+mv README.md.new README.md;
+rm usage.txt;