plugin-create-or-update-text-file.js

Convenience method to create/edit/delete a text file based on its current content

• Usage
  • Create custom Octokit constructor with plugin
  • Create or update existing file with static content
  • deleting a file is possible by setting content to null
  • set content dynamically based on current content using a content function
  • Direct usage (not as plugin)
• Options
• Types
• Contributing
• License

Usage

Browsers

Load @octokit/plugin-create-or-update-text-file and @octokit/core (or core-compatible module) directly from esm.sh

<script type="module">
  import { Octokit } from "https://esm.sh/@octokit/core";
  import {
    createOrUpdateTextFile,
    composeCreateOrUpdateTextFile,
  } from "https://esm.sh/@octokit/plugin-create-or-update-text-file";
</script>

Node

Install with npm install @octokit/core @octokit/plugin-create-or-update-text-file. Optionally replace @octokit/core with a compatible module

const { Octokit } = require("@octokit/core");
const {
  createOrUpdateTextFile,
  composeCreateOrUpdateTextFile,
} = require("@octokit/plugin-create-or-update-text-file");

Create custom Octokit constructor with plugin

const MyOctokit = Octokit.plugin(createOrUpdateTextFile);
const octokit = new MyOctokit({ auth: "secret123" });

Create or update existing file with static content

const {
  updated,
  data: { commit },
} = await octokit.createOrUpdateTextFile({
  owner: "octocat",
  repo: "hello-world",
  path: "test.txt",
  content: "content here",
  message: "update test.txt",
});

if (updated) {
  console.log("test.txt updated via %s", data.commit.html_url);
} else {
  console.log("test.txt already up to date");
}

deleting a file is possible by setting content to null

const { deleted } = await octokit.createOrUpdateTextFile({
  owner: "octocat",
  repo: "hello-world",
  path: "test.txt",
  content: null,
  message: "delete test.txt",
});

if (deleted) {
  console.log("test.txt deleted via %s", data.commit.html_url);
} else {
  console.log("test.txt does not exist");
}

set content dynamically based on current content using a content function

const { updated, deleted, data } = await octokit.createOrUpdateTextFile({
  owner: "octocat",
  repo: "hello-world",
  path: "test.txt",
  content({ exists, content }) {
    // do not create file
    if (!exists) return null;

    return content.toUpperCase();
  },
  message: "update test.txt",
});

Direct usage (not as plugin)

const octokit = new Octokit({ auth: "secret123" });

await { updated, deleted, data } = await composeCreateOrUpdateTextFile(octokit, {
  owner: "octocat",
  repo: "hello-world",
  path: "test.txt",
  content: "content here",
  message: "update test.txt",
});

Options

Required.

Set to a string in order to set the new content of the file.

Set to null in order to delete the file (if it exists).

Set to a function that either returns string, null, or a Promise that resolves to the same. The function receives one options argument

1. options.exists: true if a file exists at the given path, false if it does not.
2. options.content: A string in case the file exists, otherwise null

Types

You can import the method options and response types as well as the type of the content update function

export {
  Options,
  ContentUpdateFunction,
  Response,
} from "@octokit/plugin-create-or-update-text-file";

Contributing

See CONTRIBUTING.md

License

MIT