From ace6a0faf9f9f08172fae755526547752036987c Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Thu, 23 Mar 2023 16:12:03 +0000
Subject: [PATCH] Add readme

---
 .gitignore |   1 +
 README.md  | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+)
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
index c849890..57556c0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 /target
 dist/
+input.txt
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bda2f76
--- /dev/null
+++ b/README.md
@@ -0,0 +1,140 @@
+# skip
+
+Skip part of a file.
+
+As `head` will show the top of a file after a number of line,
+ so `skip` will do the opposite, and not show the top of the file,
+ but will show the rest.
+
+Additionally, it can check for whole lines matching,
+ or for a token being present on the line.
+
+## Usage
+
+### Skip a fixed number of lines
+
+This example reads the file from stdin.
+
+```bash
+echo "line 1
+line 2
+line 3
+line 4" > input.txt
+
+skip 2 < input.txt
+```
+
+Will output:
+
+```text
+line 3
+line 4
+```
+
+### Skip until a number of matching lines
+
+The whole line must match.
+
+This example reads the named file.
+
+```bash
+echo "alpha
+beta
+alpha
+alpha
+gamma
+alpha" > input.txt
+
+skip 2 --line alpha input.txt
+```
+
+Will output:
+
+```text
+alpha
+gamma
+alpha
+```
+
+### Skip lines until a number of tokens are seen
+
+Looks for a string within a line, counting each occurance.
+
+This example reads the file from stdin.
+
+```bash
+echo "Lorem ipsum dolor sit amet, 
+consectetur adipiscing elit, 
+sed do eiusmod tempor incididunt 
+ut labore et dolore magna aliqua. 
+Ut enim ad minim veniam, 
+quis nostrud exercitation ullamco 
+laboris nisi ut aliquip ex ea 
+commodo consequat." > input.txt
+
+cat input.txt | skip 2 --token dolor
+```
+
+Will output:
+
+```text
+Ut enim ad minim veniam, 
+quis nostrud exercitation ullamco 
+laboris nisi ut aliquip ex ea 
+commodo consequat.
+```
+
+It matches the first `dolor` on line 1,
+ and the second on line 4 as part of the word `dolore`.
+
+### Skip lines until a lines with tokens are seen
+
+Looks for a string within a line, only counting each matching line once.
+
+This example reads the file from stdin.
+
+```bash
+echo "Lorem ipsum dolor sit amet, 
+consectetur adipiscing elit, 
+sed do eiusmod tempor incididunt 
+ut labore et dolore magna aliqua. 
+Ut enim ad minim veniam, 
+quis nostrud exercitation ullamco 
+laboris nisi ut aliquip ex ea 
+commodo consequat." > input.txt
+
+cat input.txt | skip 4 --token m --ignore-extras
+```
+
+Will output:
+
+```text
+quis nostrud exercitation ullamco 
+laboris nisi ut aliquip ex ea 
+commodo consequat. 
+```
+
+Without `--ignore-extras`, it would have found the fourth `m` on line 3.
+
+```bash
+echo "Lorem ipsum dolor sit amet, 
+consectetur adipiscing elit, 
+sed do eiusmod tempor incididunt 
+ut labore et dolore magna aliqua. 
+Ut enim ad minim veniam, 
+quis nostrud exercitation ullamco 
+laboris nisi ut aliquip ex ea 
+commodo consequat." > input.txt
+
+cat input.txt | skip 4 --token m
+```
+
+Outputing:
+
+```text
+ut labore et dolore magna aliqua. 
+Ut enim ad minim veniam, 
+quis nostrud exercitation ullamco 
+laboris nisi ut aliquip ex ea 
+commodo consequat. 
+```