@octokit/plugin-create-or-update-text-file
TypeScript icon, indicating that this package has built-in type declarations

5.1.0 • Public • Published

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

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

@latest Build Status

Table of contents

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

  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
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

Readme

Keywords

Package Sidebar

Install

npm i @octokit/plugin-create-or-update-text-file

Weekly Downloads

267

Version

5.1.0

License

MIT

Unpacked Size

29.1 kB

Total Files

16

Last publish

Collaborators

  • kfcampbell
  • nickfloyd
  • gr2m
  • octokitbot