add docs for multiple patches

README.md

@@ -61,13 +61,15 @@ files.
 
 ### yarn v2+
 
-yarn 2+ have native support for patching dependencies via [`yarn patch`](https://yarnpkg.com/cli/patch).
-You do not need to use patch-package on these projects.
+yarn 2+ have native support for patching dependencies via
+[`yarn patch`](https://yarnpkg.com/cli/patch). You do not need to use
+patch-package on these projects.
 
 ### pnpm
 
-pnpm has native support for patching dependencies via [`pnpm patch`](https://pnpm.io/cli/patch).
-You do not need to use patch-package on these projects.
+pnpm has native support for patching dependencies via
+[`pnpm patch`](https://pnpm.io/cli/patch). You do not need to use patch-package
+on these projects.
 
 ### Heroku
 
@@ -88,30 +90,36 @@ details.
  Otherwise if you update a patch then the change may not be reflected on
  subsequent CI runs.
 
-
 ### CircleCI
-Create a hash of your patches before loading/saving your cache. If using a Linux machine, run `md5sum patches/* > patches.hash`. If running on a macOS machine, use `md5 patches/* > patches.hash`
+
+Create a hash of your patches before loading/saving your cache. If using a Linux
+machine, run `md5sum patches/* > patches.hash`. If running on a macOS machine,
+use `md5 patches/* > patches.hash`
+
 ```yaml
 - run:
  name: patch-package hash
  command: md5sum patches/* > patches.hash
 ```
 
 Then, update your hash key to include a checksum of that file:
+
 ```yaml
 - restore_cache:
- key: app-node_modules-v1-{{ checksum "yarn.lock" }}-{{ checksum "patches.hash" }}
-``` 
+ key:
+ app-node_modules-v1-{{ checksum "yarn.lock" }}-{{ checksum "patches.hash" }}
+```
 
 As well as the save_cache
+
 ```yaml
 - save_cache:
- key: app-node_modules-v1-{{ checksum "yarn.lock" }}-{{ checksum "patches.hash" }}
+ key:
+ app-node_modules-v1-{{ checksum "yarn.lock" }}-{{ checksum "patches.hash" }}
  paths:
  - ./node_modules
 ```
 
-
 ## Usage
 
 ### Making patches
@@ -248,6 +256,92 @@ to
 This will allow those patch files to be safely ignored when
 `NODE_ENV=production`.
 
+### Creating multiple patches for the same package
+
+_💡 This is an advanced feature and is not recommended unless you really, really
+need it._
+
+Let's say you have a patch for react-native called
+
+- `patches/react-native+0.72.0.patch`
+
+If you want to add another patch file to `react-native`, you can use the
+`--append` flag while supplying a name for the patch.
+
+Just make you changes inside `node_modules/react-native` then run e.g.
+
+ npx patch-package react-native --append 'fix-touchable-opacity'
+
+This will create a new patch file while renaming the old patch file so that you
+now have:
+
+- `patches/react-native+0.72.0+001+initial.patch`
+- `patches/react-native+0.72.0+002+fix-touchable-opacity.patch`
+
+The patches are ordered in a sequence, so that they can build on each other if
+necessary. **Think of these as commits in a git history**.
+
+#### Updating a sequenced patch file
+
+If the patch file is the last one in the sequence, you can just make your
+changes inside e.g. `node_modules/react-native` and then run
+
+ npx patch-package react-native
+
+This will update the last patch file in the sequence.
+
+If the patch file is not the last one in the sequence **you need to use the
+`--rebase` feature** to un-apply the succeeding patch files first.
+
+Using the example above, let's say you want to update the `001+initial` patch
+but leave the other patch alone. You can run
+
+ npx patch-package react-native --rebase patches/react-native+0.72.0+001+initial.patch
+
+This will undo the `002-fix-touchable-opacity` patch file. You can then make
+your changes and run
+
+ npx patch-package react-native
+
+to finish the rebase by updating the `001+initial` patch file and re-apply the
+`002-fix-touchable-opacity` patch file, leaving you with all patches applied and
+up-to-date.
+
+#### Inserting a new patch file in the middle of an existing sequence
+
+Using the above example, let's say you want to insert a new patch file between
+the `001+initial` and `002+fix-touchable-opacity` patch files. You can run
+
+ npx patch-package react-native --rebase patches/react-native+0.72.0+001+initial.patch
+
+This will undo the `002-fix-touchable-opacity` patch file. You can then make any
+changes you want to insert in a new patch file and run
+
+ npx patch-package react-native --append 'fix-console-warnings'
+
+This will create a new patch file while renaming any successive patches to
+maintain the sequence order, leaving you with
+
+- `patches/react-native+0.72.0+001+initial.patch`
+- `patches/react-native+0.72.0+002+fix-console-warnings.patch`
+- `patches/react-native+0.72.0+003+fix-touchable-opacity.patch`
+
+To insert a new patch file at the start of the sequence, you can run
+
+ npx patch-package react-native --rebase 0
+
+Which will un-apply all patch files in the sequence. Then follow the process
+above to create a new patch file numbered `001`.
+
+#### Deleting a sequenced patch file
+
+To delete a sequenced patch file, just delete it, then remove and reinstall your
+`node_modules` folder.
+
+If you deleted one of the patch files other than the last one, you don't need to
+update the sequence numbers in the successive patch file names, but you might
+want to do so to keep things tidy.
+
 ## Benefits of patching over forking
 
 - Sometimes forks need extra build steps, e.g. with react-native for Android.