patchy-cli 0.0.3 → 0.0.4-pr.154.e427e8f

package/README.md

@@ -1,98 +1,188 @@
-# patchy
+# Patchy
 
-An opinionated command-line tool for managing Git patch workflows.
+A CLI for generating and applying patches to git repositories.
 
-## How it works
+## Patches vs forks
 
-1. Clone repo → `~/target-1`
-2. Make some edits (the patches!)
-3. Create a repo for your patches → `~/my-patches`
-3. `patchy generate --repo ~/target-1` → Creates `~/my-patches/patches/*.diff`
+A traditional fork means maintaining a separate repository or long-lived branch. Over time, your history diverges from upstream, which can make updates painful.
 
-Then reapply your changes later with:
+With patches, you store changes as `.diff` files alongside the upstream repo. You can inspect them, edit them, and apply them to a fresh clone of the repo.
 
-5. `patchy apply --repo ~/target-1` → `~/target-1` (patches applied)
+## What is Patchy?
 
+Patchy helps you **generate** and **apply** `.diff` patches for a git repo you've cloned on your machine.
 
-### `patches/` folder structure
+It's opinionated and has [conventions](#patch-file-layout) about how the `.diff` files are stored.
 
-Patch files are stored in the same folder structure as the target repo:
+## Example
 
+Starting a patch-based fork of https://github.com/octocat/spoon-knife.
+
+### Setup Patchy
+
+Create a folder for the fork: `mkdir spoon-knife-fork && cd spoon-knife-fork`
+
+- [Install Patchy](#install)
+- Run `patchy init`
+  - press enter to select all the default options
+
+`patchy init` creates your config: `./patchy.json` ([full reference](#patchyjson))
+```json5
+{
+  "repo_url": "https://github.com/octocat/spoon-knife",
+  "patches_dir": "./patches/",
+  "clones_dir": "./clones/",
+  "repo_dir": "spoon-knife",
+  "ref": "main"
+}
 ```
-~/target-1/
-└── path/in/repo/existingFile.txt
-```
+
+`patchy init` also creates an empty `./patches` folder and clones the spoon-knife repo into `./clones`:
 
 ```
-my-patch-repo/
+./
 ├── patches/
-│   ├── path/in/repo/existingFile.txt.diff
-│   └── path/in/repo/newFile.txt
+├── clones/
+│   └── spoon-knife/
+│       └── path/to/existingFile.txt
 └── patchy.json
 ```
 
-- **Edits** are stored as `.diff` files e.g. `existingFile.txt.diff`.
-- **New files** are stored as regular files e.g. `newFile.txt`. 
+### Make changes to the cloned repo
 
-### `patchy.json`
+We can now make changes directly in the cloned spoon-knife repo:
 
-```jsonc
-{
-  // Git URL to clone from.
-  "repo_url": "https://github.com/example/repo.git", // Override: --repo-url | env: PATCHY_REPO_URL
+```bash
+echo "edit existing file" >> clones/spoon-knife/path/to/existingFile.txt 
+echo "new file" > clones/spoon-knife/path/to/newFile.txt 
+```
 
-  // Path to repo you're generating patches from or applying patches to.
-  "repo_dir": "~/repos/repo", // Override: --repo-dir | env: PATCHY_REPO_DIR
+### Generate patches:
 
-  // Directory containing patch files.
-  "patches_dir": "./patches/", // Override: --patches-dir | env: PATCHY_PATCHES_DIR
+To generate the patches for the changes run `patchy generate`:
 
-  // Parent directory for cloning repos. You can easily clone more repos here from repo_url.
-  "clones_dir": "./clones/", // Override: --clones-dir | env: PATCHY_CLONES_DIR
 
-  // Git ref to checkout (branch, tag, SHA).
-  "ref": "main" // Override: --ref | env: PATCHY_REF
-}
 ```
+./
+├── clones/
+│   └── spoon-knife/
+│       ├── path/to/existingFile.txt
+│       └── path/to/newFile.txt
+├── patches/
+│   ├── path/to/existingFile.txt.diff
+│   └── path/to/newFile.txt
+└── patchy.json
+```
+- **Edits** are stored as `.diff` files e.g. `existingFile.txt.diff`.
+- **New files** are copied as regular files e.g. `newFile.txt` (easier to inspect and edit directly). 
 
-Precedence: CLI flags > Environment variables > `patchy.json`
+### Reapplying patches:
 
-## Getting started 
+Reset the current upstream repo `patchy repo reset main`, which will reset everything to `main`:
 
-### Installation
+```
+./
+├── clones/
+│   └── spoon-knife/  <<< reset
+│       ├── path/to/existingFile.txt
+├── patches/
+│   ├── path/to/existingFile.txt.diff
+│   └── path/to/newFile.txt
+└── patchy.json
+```
+
+Apply the patches back to the cloned repo with: `patchy apply`
 
-```sh
-curl -fsSL https://raw.githubusercontent.com/richardgill/patchy/main/install | bash
+```
+./
+├── clones/
+│   └── spoon-knife/
+│       ├── path/to/existingFile.txt (modified)
+│       └── path/to/newFile.txt (added)
+├── patches/
+│   ├── path/to/existingFile.txt.diff
+│   └── path/to/newFile.txt
+└── patchy.json
 ```
 
-Or via npm:
+## Getting started 
 
-**Install script (recommended):**
+### Installation
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/richardgill/patchy/main/install | bash
+# follow instructions
+patchy
 ```
 
-**Via npm:**
+Or via npm:
+
 
 ```sh
 npm install -g patchy-cli
+patchy-cli
 ```
 
 Or use directly without installing:
 
 ```sh
-npx patchy-cli --version
+npx patchy-cli@latest
 ```
 
-### Initialize patchy
+### Initialize Patchy
 
-Run this command to initialize patchy in your project:
+Run this command to initialize Patchy in your project folder:
 
 ```sh
 patchy init
 ```
 
+## `patchy.json` reference
+
+```jsonc
+{
+  // Git URL to clone from.
+  "repo_url": "https://github.com/example/repo.git", // Override: --repo-url | env: PATCHY_REPO_URL
+
+  // Path to repo you're generating patches from or applying patches to.
+  "repo_dir": "~/repos/repo", // Override: --repo-dir | env: PATCHY_REPO_DIR
+
+  // Directory containing patch files.
+  "patches_dir": "./patches/", // Override: --patches-dir | env: PATCHY_PATCHES_DIR
+
+  // Parent directory for cloning repos. You can easily clone more repos here from repo_url.
+  "clones_dir": "./clones/", // Override: --clones-dir | env: PATCHY_CLONES_DIR
+
+  // Git ref to checkout (branch, tag, SHA).
+  "ref": "main" // Override: --ref | env: PATCHY_REF
+}
+```
+Precedence: CLI flags > Environment variables > `patchy.json`
+
+`patchy.json` use jsonc, so comments are allowed.
+
+## Patch file layout
+
+The `patches/` directory (customizable via [`patches_dir`](#patchyjson)) uses the same folder structure as `repo_dir`:
+
+```
+./
+├── patches/
+│   ├── path/to/existingFile.txt.diff
+│   └── path/to/newFile.txt
+├── clones/
+│   └── repo-clone-1/
+│       ├── path/to/existingFile.txt (modified)
+│       └── path/to/newFile.txt (added)
+└── patchy.json
+```
+
+**Two types of patch files:**
+- **`.diff` files** — For modified existing files (generated via `git diff HEAD`)
+- **Plain files** — For newly added files (copied verbatim for easier inspection and editing)
+
+`patchy generate` automatically removes stale files in `patches/` that no longer correspond to changes in `repo_dir`.
+
 ## Commands
 
 ### `patchy generate`
@@ -103,6 +193,8 @@ Generate `.diff` files and new files into `./patches/` based on current `git dif
 patchy generate [--repo-dir] [--patches-dir] [--dry-run]
 ```
 
+Note: `patchy generate` is destructive and will remove any unneeded files in your `./patches/` folder.
+
 ### `patchy apply`
 
 Apply patch files from `patches/` into `repo_dir`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchy-cli",
-  "version": "0.0.3",
+  "version": "0.0.4-pr.154.e427e8f",
   "description": "A CLI tool for managing Git patch workflows.",
   "type": "module",
   "bin": {
@@ -60,11 +60,11 @@
     "url": "https://github.com/richardgill/patchy"
   },
   "optionalDependencies": {
-    "patchy-cli-linux-x64": "0.0.3",
-    "patchy-cli-linux-arm64": "0.0.3",
-    "patchy-cli-darwin-x64": "0.0.3",
-    "patchy-cli-darwin-arm64": "0.0.3",
-    "patchy-cli-windows-x64": "0.0.3"
+    "patchy-cli-linux-x64": "0.0.4-pr.154.e427e8f",
+    "patchy-cli-linux-arm64": "0.0.4-pr.154.e427e8f",
+    "patchy-cli-darwin-x64": "0.0.4-pr.154.e427e8f",
+    "patchy-cli-darwin-arm64": "0.0.4-pr.154.e427e8f",
+    "patchy-cli-windows-x64": "0.0.4-pr.154.e427e8f"
   },
   "publishConfig": {
     "access": "public"