Skip to main content

CommitBuilder

Use a CommitBuilder to apply multiple changes to different files using a single commit.

The CommitBuilder exposes methods that are very similar to the Repository, with the main difference being that they're mostly synchronous.

A given file path can only have one type of action (create/update/delete) applied to it per CommitBuilder.

createFile()​

Adds a pending creation of a file to be committed later.

commitBuilder.createFile(path: string, content: string): void;
caution

Due to API limitations, the GitHub implementation treats creating and updating a file as the same. Creating a file that already exists will overwrite it.

Throws:​

  • AlreadyCommittedError: If createCommit() has already been called.
  • MultipleFileActionsError: If the given file path is already set to be created, updated, or deleted.
tip

The updateFile method requires you to pass in the whole file content, just like a traditional file-system API. You cannot pass in a diff/patch/delta like you would with a Git API.

caution

Due to API limitations, the GitHub implementation treats creating and updating a file as the same. Updating a file that does not exist will create it.

updateFile()​

Adds a pending change to a file to be committed later.

commitBuilder.updateFile(path: string, content: string): void;

Throws:​

  • AlreadyCommittedError: If createCommit() has already been called.
  • MultipleFileActionsError: If the given file path is already set to be created, updated, or deleted.

readFile()​

Reads the content of a file.

If the file does have a pending creation or update on the current CommitBuilder then the file content will be read directly from the CommitBuilder.

If the file will not be created or updated using the current CommitBuilder then the file content will be read from the remote repository.

commitBuilder.readFile(path: string): Promise<string>;
commitBuilder.readFile(path: string, tagName: string): Promise<string>;

Throws:​

  • AlreadyCommittedError: If createCommit() has already been called.
  • FileNotFoundError: If the file does not exist.

deleteFile()​

Adds a pending deletion of a file to be committed later.

commitBuilder.deleteFile(path: string): void;

Throws:​

  • AlreadyCommittedError: If createCommit() has already been called.
  • MultipleFileActionsError: If the given file path is already set to be created, updated, or deleted.

createCommit()​

Applies the configured changes in a single commit to the remote repository.

Once createCommit has been called, the CommitBuilder should not be used any further.

commitBuilder.createCommit(commitMessage: string): Promise<string>;

Throws:​

  • AlreadyCommittedError: If createCommit() has already been called.
  • EmptyCommitError: If you call createCommit() without creating, updating, or deleting a file.
  • CommitError: If there's an unknown error while committing.

JSON Helper Methods​

Just like on the Repository, the create, read, and update methods also come with JSON helper-method equivalents:

await commitBuilder.createJsonFile("path/to/file.json", anyObject);
const anyObject = await commitBuilder.readJsonFile<ObjectType>("path/to/file.json");
await commitBuilder.updateJsonFile("path/to/file.json", anyObject);