Rename APIs and export types (#117)

* Rename APIs and export types

* Remove Octokit export

Author: bluwy

.changeset/sunny-nights-heal.md

@@ -0,0 +1,8 @@
+---
+"@changesets/ghcommit": major
+---
+
+Rename public APIs and export types. Note that the existing changelog may still reference the old names, but the new names should be used instead.
+
+- `commitFilesFromBase64` -> `commitChanges`
+- `commitChangesFromRepo` -> `commitChangesSinceBase`

README.md

@@ -3,24 +3,24 @@
 > [!IMPORTANT]
 > This is the development branch for `@changesets/ghcommit` v3. For the v2 code, check out the [maintenance/v2](https://github.com/changesets/ghcommit/tree/maintenance/v2) branch.
 
-[![View on NPM](https://badgen.net/npm/v/@changesets/ghcommit)](https://www.npmjs.com/package/@changesets/ghcommit)
+[![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/@changesets/ghcommit?name=true)](https://npmx.dev/package/@changesets/ghcommit)
+[![View changelog](https://npmx.dev/api/registry/badge/version/@changesets/ghcommit?color=229fe4&value=View+changelog&label=+)](./CHANGELOG.md)
 
-NPM / TypeScript package to commit changes GitHub repositories using the GraphQL API.
+Commit file changes to GitHub repositories with the GitHub API.
 
 ## Why?
 
 - **Simplified GPG Signing:**
 
-  If you or your organisation has strict requirements
-  around requiring signed commits (i.e. via Branch Protection or Repo Rulesets), then this can make integrating CI workflows or applications that are designed to make changes to your repos quite difficult. This is because you will need to manage your own GPG keys, assign them to machine accounts (which also means it doesn't work with GitHub Apps), and securely manage and rotate them.
+  If you or your organization has strict requirements around requiring signed commits (i.e. via Branch Protection or Repo Rulesets), then this can make integrating CI workflows or applications that are designed to make changes to your repos quite difficult. This is because you will need to manage your own GPG keys, assign them to machine accounts (which also means it doesn't work with GitHub Apps), and securely manage and rotate them.
 
   Instead of doing this, if you use the GitHub API to make changes to files (such as what happens when making changes to files directly in the web UI), then GitHub's internal GPG key is used, and commits are all signed and associated with the user of the access token that was used.
 
-  (And this also works with GitHub Apps too, including the GitHub Actions app).
+  (And this also works with GitHub Apps too).
 
-  ![](docs/verified.png)
+  <img src="docs/verified.png" alt="Verified commit" height="182px" />
 
-  This library has primarily been designed for use in custom Node GitHub Actions, but can be used in any Node.js or JavaScript project that needs to directly modify files in GitHub repositories.
+  This library has primarily been designed for use in GitHub Actions, but can be used in any Node.js or JavaScript project that needs to directly modify files in GitHub repositories.
 
 - **Simplified Git Config:**
 
@@ -32,15 +32,17 @@ NPM / TypeScript package to commit changes GitHub repositories using the GraphQL
 
 ### Installation
 
-Install using your favourite package manager:
+Install using your favorite package manager:
 
-```
+```bash
 pnpm install @changesets/ghcommit
 ```
 
-### Usage in github actions
+### Octokit
+
+The library requires an [Octokit](https://github.com/octokit/octokit.js) client to call the GitHub APIs. It requires the `@octokit/core`, `@octokit/plugin-rest-endpoint-methods`, and `@octokit/plugin-paginate-rest` packages to be set up in order to work.
 
-All functions in this library that interact with the GitHub API require an octokit client that can execute GraphQL. If you are writing code that is designed to be run from within a GitHub Action, this can be done using the `@actions/github` library:
+If you're running this in GitHub Actions, this can be done using the `@actions/github` library:
 
 ```ts
 import { getOctokit } from "@actions/github";
@@ -50,71 +52,30 @@ const octokit = getOctokit(process.env.GITHUB_TOKEN);
 
 ## API
 
-All the functions below accept a single object as its argument, and share the following base arguments:
-
-<!-- TODO: point to some generated docs instead of including a code snippet -->
+Check the respective JSDoc for the complete documentation.
 
-```ts
-{
-  octokit: GitHubClient;
-  owner: string;
-  repo: string;
-  branch: string;
-  /**
-   * Push the commit even if the branch exists and does not match what was
-   * specified as the base.
-   */
-  force?: boolean;
-  /**
-   * The commit message
-   */
-  message: string | CommitMessage;
-}
-```
-
-### `commitFilesFromBase64`
+### `commitChanges`
 
 > Works in Node.js and browsers
 
-This function will add or delete specific files from a repository's branch based on the given `fileChanges` argument.
-
-In addition to `CommitFilesBasedArgs`, this function has the following arguments:
-
-```ts
-{
-  /**
-   * The current branch, tag or commit that the new branch should be based on.
-   */
-  base: GitBase;
-  /**
-   * The file paths, relative to git root, to add or delete from the branch on GitHub.
-   */
-  fileChanges: {
-    /**
-     * File paths, relative to git root, to add to the repo. Content is a base64-encoded string.
-     */
-    additions?: { path: string; content: string }[];
-    /**
-     * File paths, relative to git root, to remove from the repo.
-     */
-    deletions?: { path: string }[];
-  };
-}
-```
+Commit file changes to a branch using the GitHub API.
 
 Example:
 
 ```ts
 import fs from "node:fs/promises";
 import { context, getOctokit } from "@actions/github";
-import { commitFilesFromBase64 } from "@changesets/ghcommit";
+import { commitChanges } from "@changesets/ghcommit";
 
 const octokit = getOctokit(process.env.GITHUB_TOKEN);
+const owner = context.repo.owner;
+const repo = context.repo.repo;
 
-// Commit the changes to README.md based on the main branch
-await commitFilesFromBase64({
+// Commit the changes to README.md and delete the lockfile based on the main branch
+await commitChanges({
   octokit,
-  ...context.repo,
+  owner,
+  repo,
   branch: "new-branch-to-create",
   message: "[chore] do something",
   base: {
@@ -124,110 +85,66 @@ await commitFilesFromBase64({
     additions: [
       { path: "README.md", content: await fs.readFile("README.md", "base64") },
     ],
+    deletions: [{ path: "package-lock.json" }],
   },
 });
 ```
 
-### `commitChangesFromRepo`
+### `commitChangesSinceBase`
 
 > Works in Node.js only
 
-This function will take an existing repository on your filesystem (defaulting to the current working directory). This function is good to use if you're usually working within the context of a git repository, such as after running `@actions/checkout` in github actions.
-
-In addition to `CommitFilesBasedArgs`, this function has the following arguments:
+Commit file changes since a local git base (defaults to HEAD). This executes the `git` command to determine the changes and then uses `commitChanges` to commit them to the given branch.
 
-```ts
-{
-  /**
-   * The directory used to find the repository root,
-   * and search for changed files to commit.
-   *
-   * Any files that have been changed outside of this directory will be ignored.
-   */
-  cwd: string;
-  /**
-   * The base commit to build your changes on-top of
-   *
-   * @default HEAD
-   */
-  base?: {
-    commit: string;
-  };
-  /**
-   * Don't require {@link cwd} to be the root of the repository,
-   * and use it as a starting point to recursively search for the `.git`
-   * directory in parent directories.
-   *
-   * @default true
-   */
-  recursivelyFindRoot?: boolean;
-  /**
-   * An optional function that can be used to filter which files are included
-   * in the commit. True should be returned for files that should be included.
-   *
-   * By default, all files are included.
-   */
-  filterFiles?: (file: string) => boolean;
-}
-```
+The default HEAD base includes all uncommitted changes since the last commit. If previous commits have been made locally and not pushed, you need to set `base` to the last commit that is known to be in the remote repository.
 
 Example:
 
 ```ts
 import { context, getOctokit } from "@actions/github";
-import { commitChangesFromRepo } from "@changesets/ghcommit";
+import { commitChangesSinceBase } from "@changesets/ghcommit";
 
 const octokit = getOctokit(process.env.GITHUB_TOKEN);
+const owner = context.repo.owner;
+const repo = context.repo.repo;
 
-// Commit & push the files from the current directory
-// e.g. if you're just using @ations/checkout
-await commitChangesFromRepo({
+// Commit the file changes from the current directory
+await commitChangesSinceBase({
   octokit,
-  ...context.repo,
+  owner,
+  repo,
   branch: "new-branch-to-create",
   message: "[chore] do something",
   cwd: process.cwd(),
 });
 
-// Commit & push the files from a specific directory
-// where we've cloned a repo, and made changes to files
-await commitChangesFromRepo({
+// Commit the file changes from a different directory (and git repo)
+await commitChangesSinceBase({
   octokit,
   owner: "my-org",
-  repository: "my-repo",
-  branch: "another-new-branch-to-create",
-  message: "[chore] do something else\n\nsome more details",
+  repo: "my-repo",
+  branch: "new-branch-to-create",
+  message: "[chore] do something else",
   cwd: "/tmp/some-repo",
 });
 
-// Commit & push the files from the current directory,
-// but ensure changes from any locally-made commits are also included
-await commitChangesFromRepo({
+// Commit the file changes including commits added since the workflow run
+await commitChangesSinceBase({
   octokit,
-  ...context.repo,
-  branch: "another-new-branch-to-create",
-  message: {
-    headline: "[chore] do something else",
-    body: "some more details",
-  },
+  owner,
+  repo,
+  branch: "new-branch-to-create",
+  message: "[chore] do something else",
   cwd: process.cwd(),
   base: {
-    // This will be the original sha from the workflow run,
-    // even if we've made commits locally
-    commit: context.sha,
+    commit: context.sha, // The initial SHA of the workflow run
   },
 });
 ```
 
 ## Known Limitations
 
-Due to using the GitHub API to make changes to repository contents,
-there are some things it's not possible to commit,
-and where using the Git CLI is still required.
-
-- Executable files
-- Symbolic Links
-- Submodule changes
+The GitHub API does not allow committing executable files, symbolic links, or submodule changes. If you need to commit any of these types of files, you will need to use the Git CLI instead.
 
 ## Other Tools / Alternatives
 

src/core.ts

@@ -3,18 +3,20 @@ import {
   createCommitOnBranchQuery,
   getRepositoryMetadata,
 } from "./github/graphql/queries.ts";
-import type {
-  CommitFilesFromBase64Args,
-  CommitFilesResult,
-} from "./interface.ts";
+import type { CommitChangesOptions, CommitChangesResult } from "./types.ts";
 import { normalizeCommitMessage, resolveGitRef } from "./utils.ts";
 
 type CreateCommit = (
   refId: string,
   branch: string,
 ) => Promise<{ commitSha: string }>;
 
-export async function commitFilesFromBase64({
+/**
+ * Commit file changes to a branch using the GitHub API.
+ *
+ * Works in Node.js and browsers.
+ */
+export async function commitChanges({
   octokit,
   owner,
   repo,
@@ -23,7 +25,7 @@ export async function commitFilesFromBase64({
   force = false,
   message,
   fileChanges,
-}: CommitFilesFromBase64Args): Promise<CommitFilesResult> {
+}: CommitChangesOptions): Promise<CommitChangesResult> {
   const baseRef = resolveGitRef(base);
 
   const info = await getRepositoryMetadata(octokit, {
@@ -166,7 +168,7 @@ async function createOrForceUpdateTemporaryBranch({
   repo,
   tempBranch,
   baseSha,
-}: Pick<CommitFilesFromBase64Args, "octokit" | "owner" | "repo"> & {
+}: Pick<CommitChangesOptions, "octokit" | "owner" | "repo"> & {
   tempBranch: string;
   baseSha: string;
 }) {

src/git.ts

@@ -1,20 +1,31 @@
 import fs from "node:fs/promises";
 import path from "path";
 import { exec } from "tinyexec";
-import { commitFilesFromBase64 } from "./core.ts";
+import { commitChanges } from "./core.ts";
 import type {
-  CommitChangesFromRepoArgs,
-  CommitFilesFromBase64Args,
-  CommitFilesResult,
-} from "./interface.ts";
+  CommitChangesOptions,
+  CommitChangesSinceBaseOptions,
+  CommitChangesResult,
+} from "./types.ts";
 import { resolveGitRef } from "./utils.ts";
 
-export async function commitChangesFromRepo({
+/**
+ * Commit file changes since a local git base (defaults to HEAD). This executes
+ * the `git` command to determine the changes and then uses {@link commitChanges}
+ * to commit them to the given branch.
+ *
+ * The default HEAD base includes all uncommitted changes since the last commit.
+ * If previous commits have been made locally and not pushed, you need to set `base
+ * to the last commit that is known to be in the remote repository.
+ *
+ * Works in Node.js only.
+ */
+export async function commitChangesSinceBase({
   cwd: workingDirectory,
   recursivelyFindRoot = true,
   filterFiles,
   ...otherArgs
-}: CommitChangesFromRepoArgs): Promise<CommitFilesResult> {
+}: CommitChangesSinceBaseOptions): Promise<CommitChangesResult> {
   const ref = resolveGitRef(otherArgs.base ?? { commit: "HEAD" });
   const cwd = path.resolve(workingDirectory);
   const repoRoot = recursivelyFindRoot ? await findGitRoot(cwd) : cwd;
@@ -24,7 +35,7 @@ export async function commitChangesFromRepo({
     throw new Error(`Could not determine sha for ref ${ref}`);
   }
 
-  return await commitFilesFromBase64({
+  return await commitChanges({
     ...otherArgs,
     fileChanges: await getFileChanges(
       workingDirectory,
@@ -43,17 +54,17 @@ export async function getFileChanges(
   cwd: string,
   repoRoot: string,
   ref: string,
-  filterFiles?: CommitChangesFromRepoArgs["filterFiles"],
-): Promise<CommitFilesFromBase64Args["fileChanges"]> {
+  filterFiles?: CommitChangesSinceBaseOptions["filterFiles"],
+): Promise<CommitChangesOptions["fileChanges"]> {
   /**
    * The directory to add files from. This is relative to the repository
    * root, and is used to filter files.
    */
   const relativeStartDirectory =
     cwd === repoRoot ? null : path.relative(repoRoot, cwd) + "/";
 
-  const additions: CommitFilesFromBase64Args["fileChanges"]["additions"] = [];
-  const deletions: CommitFilesFromBase64Args["fileChanges"]["deletions"] = [];
+  const additions: CommitChangesOptions["fileChanges"]["additions"] = [];
+  const deletions: CommitChangesOptions["fileChanges"]["deletions"] = [];
 
   const addPath = async (filePath: string) => {
     if (