.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "AERC-PATCH" "7" "2024-07-30" .PP .SH NAME .PP aerc-patch - local patch management for \fBaerc\fR(1) .PP .SH SYNOPSIS .PP \fBaerc\fR 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, \fBaerc\fR facilitates this bookkeeping process.\& .PP When applying a patch set, \fBaerc\fR creates a tag for those commits.\& With this tag, the patch set can be tracked and later dropped 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.\& .PP .SH COMMANDS .PP The following \fB:patch\fR sub-commands are supported: .PP \fB:patch init\fR [\fB-f\fR] [\fI\fR] .RS 4 Creates a new project \fI\fR.\& If \fI\fR is not defined, \fBaerc\fR will use the last element of the current directory path.\& It also performs a search for a supported repository in the current directory.\& .PP \fB-f\fR: Overwrite an existing project.\& .PP .RE \fB:patch list\fR [\fB-a\fR] .br \fB:patch ls\fR [\fB-a\fR] .RS 4 Lists the current project with the tracked patch sets.\& .PP \fB-a\fR: Lists all projects.\& .PP .RE \fB:patch apply\fR [\fB-c\fR \fI\fR] [\fB-w\fR \fI\fR] \fI\fR .RS 4 Applies the selected message(s) to the repository of the current project.\& It uses the \fB:pipe\fR command for this and keeps track of the applied patch.\& .PP Completions for the \fI\fR are available based on the subject lines of the selected or marked messages.\& .PP \fB-c\fR \fI\fR: Apply patches with the provided \fI\fR.\& Any occurence of \&'\&%r'\& in the command string will be replaced with the root directory of the current project.\& Note that this approach is not recommended in general and should only be used for very specific purposes, i.\&e.\& when a maintainer is applying a patch set via a separate script to deal with git trailers.\& .PP \fBaerc\fR will propose completions for the \fI\fR based on the subject lines of the selected or marked messages.\& .PP Example: .nf .RS 4 :patch apply -c "git -C %r am -3" fix_v2 .fi .RE .PP \fB-w\fR \fI\fR: Create a linked worktree for the current project at \fI\fR and apply the patches to the linked worktree.\& A new project is created to store the worktree information.\& When this project is deleted, the worktree will be deleted as well.\& .PP Example: .nf .RS 4 :patch apply -w origin/master fix_v2 .fi .RE .PP .RE \fB:patch drop\fR \fI\fR .RS 4 Drops the patch \fI\fR from the repository.\& .PP .RE \fB:patch rebase\fR [\fI\fR] .RS 4 Rebases the patch data on commit \fI\fR.\& .PP If the \fI\fR is omitted, \fBaerc\fR will use the base commit of the current project for the rebase.\& .PP .RE \fB:patch find\fR [\fB-f\fR] \fI\fR .RS 4 Searches the messages in the current folder of the current account for the message associated with this \fIcommit hash\fR based on the subject line.\& .PP If a Message-ID is linked to a commit (i.\&e.\& when \fB:patch apply\fR was used) then \fBfind\fR will first perform a search for the Message-ID.\& .PP \fB-f\fR: Filter the message list instead of just showing the search results.\& Only effective when search for Message-ID was not successful.\& .PP .RE \fB:patch cd\fR .RS 4 Changes the working directory to the root directory of the current project.\& .PP .RE \fB:patch term\fR [\fI\fR] .RS 4 Opens a shell (or runs \fI\fR) in the working directory of the current project.\& .PP .RE \fB:patch switch\fR \fI\fR .RS 4 Switches the context to \fI\fR.\& .PP .RE \fB:patch unlink\fR [\fI\fR] .RS 4 Deletes all patch tracking data for \fI\fR and unlinks it from a repository.\& If no project is provided, the current project is deleted.\& .PP .RE \fB:patch\fR .RS 4 Root command for path management.\& Use it to run the sub-commands.\& .PP .RE .SH GETTING STARTED .PP Make sure you have an initialized project (see \fB:patch init\fR).\& .PP Now, there are two ways to get patches under the local patch management system: .PP .PD 0 .IP \(bu 4 Apply patches with the \fB:patch apply\fR command.\& This will automatically create a new tag for the applied commits.\& .PD .PP .PD 0 .IP \(bu 4 Use \fB:patch rebase\fR.\& If there are some existing local patches in the commit history that should be managed by \fBaerc\fR, you can run \fB:patch rebase \fR and set the \fI\fR to the commit before the first patch that you want to include.\& For a \fBgit\fR repository which has an upstream called \fBorigin\fR, you would run \fB:patch rebase origin/master\fR.\& .PD .PP .SH EXAMPLE .PP The following example demonstrates how to manage the local patch sets.\& .PP 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 \fIbar\fR in the directory \fI/home/user/foo/bar\fR.\& .PP .nf .RS 4 :cd /home/user/foo/bar .fi .RE .PP and then creating a new project with .PP .nf .RS 4 :patch init .fi .RE .PP If no name is provided to \fB:patch init\fR, \fBaerc\fR will use the last element of the working directory path (here: \fIbar\fR).\& .PP Now the patch tracking is ready for action.\& Go to the message list, mark a patch series and apply it: .PP .nf .RS 4 :patch apply fix_v2 .fi .RE .PP This will apply the selected patch set and assigns the \fIfix_v2\fR tag to those commits.\& The tag helps to keep the commits grouped together, and will be helpful when we want to drop this exact patch set at a later point.\& .PP With \fB:patch list\fR you can verify that the patch set was correctly applied.\& .PP If there is a change in the underlying repository (e.\&g.\& by rebasing to upstream), the hashes of the applied local commits can change.\& \fB:patch list\fR can detect such a change and will then propose to rebase the internal data.\& To do this, run .PP .nf .RS 4 :patch rebase .fi .RE .PP 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 \fIHEAD~3\fR or \fIorigin/master\fR, etc.\&).\& .PP To drop a patch set, use the tag that was assigned during applying: .PP .nf .RS 4 :patch drop fix_v2 .fi .RE .PP And to delete the project data in \fBaerc\fR: .PP .nf .RS 4 :patch unlink bar .fi .RE .PP .SH SUPPORTED REVISION CONTROL SYSTEMS .PP The supported revision control systems are currently: \fBgit\fR.\& .PP .SH SEE ALSO .PP \fBaerc\fR(1) .PP .SH AUTHORS .PP 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 \fIhttps://sr.\&ht/~rjarry/aerc/\fR.\&