From f75d4b7bb615df6c20546961870672c0f1680999 Mon Sep 17 00:00:00 2001 From: Koni Marti Date: Fri, 24 Nov 2023 16:02:55 +0100 Subject: 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 Acked-by: Robin Jarry --- doc/aerc-patch.7.scd | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 doc/aerc-patch.7.scd (limited to 'doc/aerc-patch.7.scd') 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*] [__] + Creates a new project __. If __ 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* __ + 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 __ based on the subject lines + of the selected or marked messages. + +*:patch remove* __ + Removes the patch __ from the repository. + +*:patch rebase* [__] + Rebases the patch data on commit __. + + If the __ 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* [__] + Opens a shell (or runs __) in the working directory of the + current project. + +*:patch switch* __ + Switches the context to __. + +*:patch delete* [__] + Deletes all patch tracking data for __. 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 + * and set the __ 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/_. -- cgit