https://github.com/octokit/plugin-create-or-update-text-file.js
Convenience method to create/edit/delete a text file based on its current content
https://github.com/octokit/plugin-create-or-update-text-file.js
hacktoberfest octokit-js plugin
Last synced: 7 months ago
JSON representation
Convenience method to create/edit/delete a text file based on its current content
- Host: GitHub
- URL: https://github.com/octokit/plugin-create-or-update-text-file.js
- Owner: octokit
- License: mit
- Created: 2021-03-08T20:35:45.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-26T02:46:53.000Z (8 months ago)
- Last Synced: 2025-06-03T22:40:27.247Z (7 months ago)
- Topics: hacktoberfest, octokit-js, plugin
- Language: TypeScript
- Homepage:
- Size: 2.02 MB
- Stars: 18
- Watchers: 5
- Forks: 9
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# plugin-create-or-update-text-file.js
> Convenience method to create/edit/delete a text file based on its current content
[](https://www.npmjs.com/package/@octokit/plugin-create-or-update-text-file)
[](https://github.com/octokit/plugin-create-or-update-text-file.js/actions?query=workflow%3ATest+branch%3Amain)
Table of contents
- [Usage](#usage)
- [Create custom Octokit constructor with plugin](#create-custom-octokit-constructor-with-plugin)
- [Create or update existing file with static content](#create-or-update-existing-file-with-static-content)
- [deleting a file is possible by setting content to null](#deleting-a-file-is-possible-by-setting-content-to-null)
- [set content dynamically based on current content using a content function](#set-content-dynamically-based-on-current-content-using-a-content-function)
- [Direct usage (not as plugin)](#direct-usage-not-as-plugin)
- [Options](#options)
- [Types](#types)
- [Contributing](#contributing)
- [License](#license)
## Usage
Browsers
Load `@octokit/plugin-create-or-update-text-file` and [`@octokit/core`](https://github.com/octokit/core.js) (or core-compatible module) directly from [esm.sh](https://esm.sh)
```html
import { Octokit } from "https://esm.sh/@octokit/core";
import {
createOrUpdateTextFile,
composeCreateOrUpdateTextFile,
} from "https://esm.sh/@octokit/plugin-create-or-update-text-file";
```
Node
Install with `npm install @octokit/core @octokit/plugin-create-or-update-text-file`. Optionally replace `@octokit/core` with a compatible module
```js
const { Octokit } = require("@octokit/core");
const {
createOrUpdateTextFile,
composeCreateOrUpdateTextFile,
} = require("@octokit/plugin-create-or-update-text-file");
```
### Create custom Octokit constructor with plugin
```js
const MyOctokit = Octokit.plugin(createOrUpdateTextFile);
const octokit = new MyOctokit({ auth: "secret123" });
```
### Create or update existing file with static content
```js
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
```js
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
```js
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)
```js
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
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
```ts
export {
Options,
ContentUpdateFunction,
Response,
} from "@octokit/plugin-create-or-update-text-file";
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
[MIT](LICENSE)