diff options
| -rw-r--r-- | commands/help.go | 1 | ||||
| -rw-r--r-- | config/binds.conf | 7 | ||||
| -rw-r--r-- | doc/aerc-patch.7.scd | 161 | ||||
| -rw-r--r-- | doc/aerc.1.scd | 4 |
4 files changed, 173 insertions, 0 deletions
diff --git a/commands/help.go b/commands/help.go index a3cfff40..3d8d5ecf 100644 --- a/commands/help.go +++ b/commands/help.go @@ -24,6 +24,7 @@ var pages = []string{ "stylesets", "templates", "tutorial", + "patch", "keys", } diff --git a/config/binds.conf b/config/binds.conf index 58d81508..76457bc4 100644 --- a/config/binds.conf +++ b/config/binds.conf @@ -74,6 +74,13 @@ N = :prev-result<Enter> s = :split<Enter> S = :vsplit<Enter> +pl = :patch list<Enter> +pa = :patch apply <Tab> +pr = :patch remove <Tab> +pb = :patch rebase<Enter> +pt = :patch term<Enter> +ps = :patch switch <Tab> + [messages:folder=Drafts] <Enter> = :recall<Enter> 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 |