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

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

Table of contents

• 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 createOrUpdateTextFile(octokit, {
  owner: "octocat",
  repo: "hello-world",
  path: "test.txt",
  content: "content here",
  message: "update test.txt",
});

Options

name	type	description
owner	string	Required. Repository owner login
repo	string	Required. Repository repository name
path	string	Required. Path to repository file within the repository
path	string	Required. Path to repository file within the repository
message	string	Required. Commit message in case an update is necessary
content	string | null | function	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 options.exists: true if a file exists at the given path, false if it does not. options.content: A string in case the file exists, otherwise null
branch	string	The repository branch on which to update the file. Defaults to the repository's default branch
committer	object	Same as the committer object from the PUT /repos/{owner}/{repo}/contents/{path} REST API endpoint
author	object	Same as the author object from the PUT /repos/{owner}/{repo}/contents/{path} REST API endpoint

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