Add forkFromBaseBranch support

Author: mheap

README.md

@@ -68,6 +68,27 @@ const commits = await octokit.rest.repos.createOrUpdateFiles({
 });
 ```
 
+By default the plugin will append commits to an existing branch. If you want to reset the branch to the state of `base` before adding any changes, set `forkFromBaseBranch: true`:
+
+```javascript
+const commits = await octokit.rest.repos.createOrUpdateFiles({
+  owner,
+  repo,
+  branch,
+  createBranch: true,
+  base: "main",
+  forkFromBaseBranch: true
+  changes: [
+    {
+      message: "Your commit message",
+      files: {
+        "test.md": `This example wiped out any previous commits on 'branch' before adding this change`,
+      },
+    },
+  ],
+});
+```
+
 In addition, you can set the `mode` of a file change. For example, if you wanted to update a submodule pointer:
 
 ```javascript

create-or-update-files.js

@@ -32,21 +32,24 @@ module.exports = function (octokit, opts) {
         author,
         changes,
         batchSize,
+        forkFromBaseBranch,
       } = opts;
 
       let branchAlreadyExists = true;
       let baseTree;
 
       // Does the target branch already exist?
       baseTree = await loadRef(octokit, owner, repo, branchName);
-      if (!baseTree) {
-        if (!createBranch) {
+      if (!baseTree || forkFromBaseBranch) {
+        if (!createBranch && !baseTree) {
           return reject(
             `The branch '${branchName}' doesn't exist and createBranch is 'false'`
           );
         }
 
-        branchAlreadyExists = false;
+        if (!baseTree) {
+          branchAlreadyExists = false;
+        }
 
         // If not we use the base branch. If not provided, use the
         // default from the repo

create-or-update-files.test.js

@@ -194,6 +194,22 @@ test(`success (branch exists)`, async () => {
   await expect(run(body)).resolves.toEqual(mockCommitList);
 });
 
+test(`success (branch exists, forkFromBaseBranch: true)`, async () => {
+  const body = {
+    ...validRequest,
+    forkFromBaseBranch: true,
+  };
+  mockGetRef(base, `sha-${base}`, true);
+  mockGetRef(branch, `sha-${branch}`, true);
+  mockCreateBlobFileOne();
+  mockCreateBlobFileTwo();
+  mockCreateTree(`sha-${base}`);
+  mockCommit(`sha-${base}`);
+  mockUpdateRef(branch);
+
+  await expect(run(body)).resolves.toEqual(mockCommitList);
+});
+
 test(`success (base64 encoded body)`, async () => {
   const body = {
     ...validRequest,