Configuration
The template source and synchronization point recorded by Patchworks
Configuration
Patchworks stores its state in .patchworks.json at the repository root.
patchworks create writes a file similar to:
{
"version": "0.1.3",
"template": {
"repository": "https://github.com/original/template",
"branch": "main"
},
"commit": "0123456789abcdef0123456789abcdef01234567"
}Fields
| Field | Description |
|---|---|
version | Patchworks version that created the repository; optional for older configurations |
template.repository | Git repository used as the template; HTTPS, SSH, SCP-style, and local paths are supported |
template.branch | Branch whose first-parent history is followed; defaults to main when omitted |
commit | Full 40- or 64-character object ID of the last prepared template commit |
Unknown top-level fields are preserved when Patchworks advances the commit.
For a local template, create records the resolved absolute repository path.
HTTP URLs containing embedded credentials are rejected. Use a Git credential
helper locally or the GitHub Action's token input instead of storing secrets in
this file.
How the commit advances
Each normal patchworks update prepares exactly one commit after commit on
the configured branch's first-parent path. The configuration advances in the
same unstaged working-tree diff as the template changes, including when reject
artifacts require manual resolution.
Review and commit the configuration with the resolved update. Do not advance it independently: the object ID is the base tree Patchworks needs for the next diff.
If the recorded commit exists but is no longer on the branch's first-parent
history, the CLI requires an explicit --rebase. If the object was pruned and
is not fetchable, Patchworks cannot recover its tree from the configuration
alone.
File safety
.patchworks.json must be a regular file no larger than 1 MiB. Symbolic links
are not allowed. Patchworks validates the JSON and its repository, branch, and
commit fields before fetching anything, then replaces the file atomically while
preserving its permission mode.
Templates may not supply .patchworks.json; the path is reserved for the child
repository's synchronization state.