doc: add aerc-patch

Document the local patch management. Adjust the help command. Add
default key binds.

Changelog-added: Patch management with `:patch`.
Signed-off-by: Koni Marti <koni.marti@gmail.com>
Acked-by: Robin Jarry <robin@jarry.cc>

2 files changed, 165 insertions, 0 deletions

diff --git a/doc/aerc-patch.7.scd b/doc/aerc-patch.7.scd
new file mode 100644
index 00000000..4209b493
--- /dev/null
+++ b/doc/aerc-patch.7.scd
@@ -0,0 +1,161 @@
+AERC-PATCH(7)
+
+# NAME
+
+aerc-patch - local patch management for *aerc*(1)
+
+# SYNOPSIS
+
+*aerc* provides support for managing local patch sets. In an email-based
+software development workflow, there are usually many different locally applied
+patch series for testing and reviewing. Managing the local repository can thus
+be challenging. With the local patch management system, *aerc* facilitates this
+bookkeeping process.
+
+When applying a patch set, *aerc* creates a tag for those commits. With this
+tag, the patch set can be tracked and later removed if needed. Patches are
+stored in a project data structure which also keeps track of the directory where
+the repository is. Multiple code bases can be tracked by defining a separate
+project for each.
+
+# COMMANDS
+
+The following *:patch* sub-commands are supported:
+
+*:patch init* [*-f*] [_<project>_]
+	Creates a new project _<project>_. If _<project>_ is not defined, *aerc*
+	will use the last element of the current directory path. It also
+	performs a search for a supported repository in the current directory.
+
+	*-f*: Overwrite an existing project.
+
+*:patch list* [*-a*]++
+*:patch ls* [*-a*]
+	Lists the current project with the tracked patch sets.
+
+	*-a*: Lists all projects.
+
+*:patch apply* _<tag>_
+	Applies the selected message(s) to the repository of the current
+	project. It uses the *:pipe* command for this and keeps track of the
+	applied patch.
+
+	*aerc* will propose completions for _<tag>_ based on the subject lines
+	of the selected or marked messages.
+
+*:patch remove* _<tag>_
+	Removes the patch _<tag>_ from the repository.
+
+*:patch rebase* [_<commit-ish>_]
+	Rebases the patch data on commit _<commit-ish>_.
+
+	If the _<commit-ish>_ is omitted, *aerc* will use the base commit of
+	the current project for the rebase.
+
+*:patch cd*
+	Changes the working directory to the root directory of the current
+	project.
+
+*:patch term* [_<cmd>_]
+	Opens a shell (or runs _<cmd>_) in the working directory of the
+	current project.
+
+*:patch switch* _<project>_
+	Switches the context to _<project>_.
+
+*:patch delete* [_<project>_]
+	Deletes all patch tracking data for _<project>_. If no project is
+	provided, the current project is deleted.
+
+*:patch*
+	Root command for path management. Use it to run the sub-commands.
+
+
+# GETTING STARTED
+
+Make sure you have an initialized project (see *:patch init*).
+
+Now, there are two ways to get patches under the local patch management system:
+
+- Apply patches with the *:patch apply* command. This will automatically create
+  a new tag for the applied commits.
+
+- Use *:patch rebase*. If there are some existing local patches in the commit
+  history that should be managed by *aerc*, you can run *:patch rebase
+  <commit-ish>* and set the _<commit-ish>_ to the commit before the first patch
+  that you want to include. For a *git* repository which has an upstream called
+  *origin*, you would run *:patch rebase origin/master*.
+
+# EXAMPLE
+
+The following example demonstrates how to manage the local patch sets.
+
+First, a project needs to be initialized. This is done by changing into the
+working directory where the project's repository is located. For this example,
+let's assume we have a project called _bar_ in the directory
+_/home/user/foo/bar_.
+
+```
+:cd /home/user/foo/bar
+```
+
+and then creating a new project with
+
+```
+:patch init
+```
+
+If no name is provided to *:patch init*, *aerc* will use the last element of the
+working directory path (here: _bar_).
+
+Now the patch tracking is ready for action. Go to the message list, mark a patch
+series and apply it:
+
+```
+:patch apply fix_v2
+```
+
+This will apply the selected patch set and assigns the _fix_v2_ tag to those
+commits. The tag helps to keep the commits grouped together, and will be helpful
+when we want to remove this exact patch set at a later point.
+
+With *:patch list* you can verify that the patch set was correctly applied.
+
+If there is a change in the underlying repository (e.g. by rebasing to
+upstream), the hashes of the applied local commits can change. *:patch list* can
+detect such a change and will then propose to rebase the internal data. To
+do this, run
+
+```
+:patch rebase
+```
+
+This will open an editor where you can adjust the correct tags again. You could
+also change the rebase point by providing an optional argument (e.g. a commit
+hash, or even _HEAD~3_ or _origin/master_, etc.).
+
+To remove a patch set, use the tag that was assigned during applying:
+
+```
+:patch remove fix_v2
+```
+
+And to delete the project data in *aerc*:
+
+```
+:patch delete bar
+```
+
+# SUPPORTED REVISION CONTROL SYSTEMS
+
+The supported revision control systems are currently: *git*.
+
+# SEE ALSO
+
+*aerc*(1)
+
+# AUTHORS
+
+Originally created by Drew DeVault and maintained by Robin Jarry who is assisted
+by other open source contributors. For more information about aerc development,
+see _https://sr.ht/~rjarry/aerc/_.
diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index 1a7afc46..63ce6345 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -276,6 +276,9 @@ message list, the message in the message viewer, etc).
 
 	*-p*: Create the _<target>_ folder if it does not exist.
 
+*:patch* _<args ...>_
+	Patch management sub-commands. See *aerc-patch*(7) for more details.
+
 *:pipe* [*-bmp*] _<cmd>_
 	Downloads and pipes the selected message into the given shell command
 	(executed with _sh -c "<cmd>"_), and opens a new terminal tab to show
@@ -784,6 +787,7 @@ in _aerc.conf_.
 *aerc-config*(5) *aerc-imap*(5) *aerc-jmap*(5) *aerc-notmuch*(5) *aerc-smtp*(5)
 *aerc-maildir*(5) *aerc-sendmail*(5) *aerc-search*(1) *aerc-stylesets*(7)
 *aerc-templates*(7) *aerc-accounts*(5) *aerc-binds*(5) *aerc-tutorial*(7)
+*aerc-patch*(7)
 
 # AUTHORS