patch2pr

README

patch2pr

Create GitHub pull requests from Git patches without cloning the repository.

Why?

As a command line tool, it's mostly a curiosity and test for the library, but might have some use for exceptionally large repositories or in environments where cloning is not feasible.

As a library, however, it enables tools to make automated code changes without giving every part of system write access or requiring extra logic for managing clones. One part of the system can generate a patch and send it to another part that uses this library to apply it and create a pull request.

Usage: CLI

Pre-built binaries for common platforms are available on the releases page.

You can also install from source using go install:

go install github.com/bluekeyes/patch2pr/cmd/patch2pr@latest

The CLI takes a path to a patch file as the only argument or reads a patch from stdin if no file is given.

The other required arguments are:

• The -repository flag to specify the repository in owner/name format
• A GitHub token, set with the -token flag or in the GITHUB_TOKEN environment variable.
  • Classic tokens must have repo scope
  • Fine-grained tokens must have read and write access to administration (for creating forks), contents (for committing changes), and pull requests

For example:

$ export GITHUB_TOKEN="token"
$ patch2pr -repository bluekeyes/patch2pr /path/to/file.patch

See the CLI help (-h or -help) or below for full details.

Full Usage

Usage: patch2pr [options] [patch...]

  Create a GitHub pull request from a patch file

  This command parses one or more patches, applies them, and creates a pull
  request with the result. It does not clone the repository. If no patch files
  are given, the command reads the patches from standard input. Each file can
  contain a single patch or multiple patches in the mbox format produced by 'git
  format-patch --stdout' or GitHub's patch view.

  By default, patch2pr uses the patch header for author and committer
  information, falling back to the authenticated GitHub user if the headers are
  missing or invalid. Callers can override these values using the standard Git
  environment variables:

    GIT_AUTHOR_NAME
    GIT_AUTHOR_EMAIL
    GIT_AUTHOR_DATE
    GIT_COMMITTER_NAME
    GIT_COMMITER_EMAIL
    GIT_COMMITER_DATE

  Override the commit message by using the -message flag.

  With the -fork and -fork-repository flags, the command can submit the pull
  request from a fork repository. If an existing fork does not exist, the
  command creates a new fork, which may take up to five minutes.

Options:

  -base-branch=branch    The branch to target with the pull request. If unset,
                         use the repository's default branch.

  -draft                 Create a draft pull request.

  -force                 Update the head branch even if it exists and is not a
                         fast-forward.

  -fork                  Submit the pull request from a fork instead of pushing
                         directly to the repository. With no other flags, use a
                         fork in the current account with the same name as the
                         target repository, creating the fork if it does not exist.

  -fork-repository=repo  Submit the pull request from the named fork instead of
                         pushing directly to the repository, creating the fork
                         if it does not exist. Implies the -fork flag.

  -head-branch=branch    The branch to create or update with the new commit. If
                         unset, use 'patch2pr'.

  -json                  Output information about the new commit and pull request
                         in JSON format.

  -message=message       Message for the commit. Overrides the patch header.

  -no-pull-request       Do not create a pull request after creating a commit.

  -patch-base=base       Base commit to apply the patch to. Can be a SHA1, a
                         branch, or a tag. Branches and tags must start with
                         'refs/heads/' or 'refs/tags/' respectively. If unset,
                         use the repository's default branch.

  -pull-body=body        The body for the pull request. If unset, use the body of
                         the commit message.

  -pull-title=title      The title for the pull request. If unset, use the title
                         of the commit message.

  -repository=repo       Repository to apply the patch to in 'owner/name' format.
                         Required.

  -token=token           GitHub API token with 'repo' scope for authentication.
                         If unset, use the value of the GITHUB_TOKEN environment
                         variable.

  -url=url               GitHub API URL. If unset, use https://api.github.com.

  -v/-version            Print the version and exit.

Usage: Library

The CLI is built on the patch2pr library, which can be used to build other tools that apply patches directly to GitHub. See the documentation for full details.

The library uses google/go-github to interact with GitHub and exposes types from that package in the API.

Stability

Beta. The library is used in a production application that applies thousands of patches every day, but the interface for both the CLI and the library may change.

While the underlying patch library (bluekeyes/go-gitdiff) has good test coverage and real-world usage, the space of all possible patches is large, so there are likely undiscovered bugs.

Contributing

Contributions are welcome. If reporting an issue with applying a patch, please include the patch file and the base commit or file content if possible. A link to a public repository is most helpful.

At this time, I don't intend to support services other than GitHub. If you'd like support for another service, please file an issue with a link to the relevant API documentation so I can estimate the work involved in adding the necessary abstractions.

License

MIT

Documentation

Overview

Package patch2pr converts Git patches in to GitHub pull requests.

Index

• Variables
• func IsUnsupported(err error) bool
• type Applier
  • func NewApplier(client *github.Client, repo Repository, c *github.Commit) *Applier
  • func (a *Applier) Apply(ctx context.Context, f *gitdiff.File) (*github.TreeEntry, error)
  • func (a *Applier) Commit(ctx context.Context, tmpl *github.Commit, header *gitdiff.PatchHeader) (*github.Commit, error)
  • func (a *Applier) CreateTree(ctx context.Context) (*github.Tree, error)
  • func (a *Applier) Entries() []*github.TreeEntry
  • func (a *Applier) Reset(c *github.Commit)
• type GraphQLApplier
  • func NewGraphQLApplier(client *githubv4.Client, repo Repository, base string) *GraphQLApplier
  • func (a *GraphQLApplier) Apply(ctx context.Context, f *gitdiff.File) error
  • func (a *GraphQLApplier) Commit(ctx context.Context, ref string, header *gitdiff.PatchHeader) (string, error)
  • func (a *GraphQLApplier) Reset(base string)
  • func (a *GraphQLApplier) SetV3Client(client *github.Client)
• type Reference
  • func NewReference(client *github.Client, repo Repository, ref string) *Reference
  • func (r *Reference) PullRequest(ctx context.Context, spec *github.NewPullRequest) (*github.PullRequest, error)
  • func (r *Reference) Set(ctx context.Context, sha string, force bool) error
• type Repository
  • func ParseRepository(s string) (Repository, error)
  • func (r Repository) String() string

Variables

var DefaultCommitMessage = "Apply patch with patch2pr"

DefaultCommitMessage is the commit message used when no message is provided in a patch header.

Functions

func IsUnsupported

func IsUnsupported(err error) bool

IsUnsupported returns true if err is the result of trying an unsupported operation. It is equivalent to finding the first error in err's chain that implements

type unsupported interface {
    Unsupported() bool
}

and then calling the Unsupported() method.

Types

type Applier

type Applier struct {
	// contains filtered or unexported fields
}

Applier applies patches to create trees and commits in a repository.

func NewApplier

func NewApplier(client *github.Client, repo Repository, c *github.Commit) *Applier

NewApplier creates a new Applier for a repository. The Applier applies changes on top of commit c.

func (*Applier) Apply

func (a *Applier) Apply(ctx context.Context, f *gitdiff.File) (*github.TreeEntry, error)

Apply applies the changes in a file, adds the result to the list of pending tree entries, and returns the entry. If the application succeeds, Apply creates a blob in the repository with the modified content.

func (*Applier) Commit

func (a *Applier) Commit(ctx context.Context, tmpl *github.Commit, header *gitdiff.PatchHeader) (*github.Commit, error)

Commit commits the latest tree, optionally using the details in tmpl and header. If there are pending tree entries, it calls CreateTree before creating the commit. It returns an error if there are no pending trees or tree entries.

If tmpl is not nil, Commit uses it as a template for the new commit, overwriting fields as needed. If header is not nil, Commit uses it to set the message, author, and committer for the new commit. Values in header overwrite those in tmpl.

If both tmpl and header are nil or missing fields, Commit uses a default message, the current time, and the authenticated user as needed for the commit details.

func (*Applier) CreateTree

func (a *Applier) CreateTree(ctx context.Context) (*github.Tree, error)

CreateTree creates a tree from the pending tree entries and clears the entry list. The new tree serves as the base tree for future Apply calls. CreateTree returns an error if there are no pending tree entires.

func (*Applier) Entries

func (a *Applier) Entries() []*github.TreeEntry

Entries returns the list of pending tree entries.

func (*Applier) Reset

func (a *Applier) Reset(c *github.Commit)

Reset resets the applier so that future Apply calls start from commit c. It removes pending tree entries and clears the latest tree. Reset does not modify the remote repository.

type GraphQLApplier

type GraphQLApplier struct {
	// contains filtered or unexported fields
}

GraphQLApplier applies patches to create commits in a repository. Compared to the normal Applier, the GraphqQLApplier:

• Generally makes fewer API requests
• Does not support setting a commit author or committer
• Does not create intermediate blobs and trees
• Uses more memory while applying patches with multiple files
• Updates a branch (which must exist) to reference the new commit
• Creates signed commits

Due to limitations in the GraphQL API, not all patches are supported; see Apply. Use the regular Applier if you need to apply arbitrary patches or if you are targeting a GitHub Enterprise instance that does not support the createCommitOnBranch GraphQL mutation.

func NewGraphQLApplier

func NewGraphQLApplier(client *githubv4.Client, repo Repository, base string) *GraphQLApplier

NewGraphQLApplier creates an applier for a repository. The applier applies changes on top of base, the full OID (SHA) of a commit.

func (*GraphQLApplier) Apply

func (a *GraphQLApplier) Apply(ctx context.Context, f *gitdiff.File) error

Apply applies the changes in a file, adding the result to the list of pending file changes. It does not modify the repository.

Due to GraphQL limitations, some patches are not supported:

• Adding or renaming files that use a non-standard mode
• Changing the mode of an existing file
• Modifying or deleting binary files (without a V3 client)
• Modifying or deleting large files (without a V3 client)

When given an unsupported patch, Apply returns an error such that IsUnsupported(err) is true. Setting a V3 client with SetV3Client allows Apply to process some patches that are otherwise unsupported.

func (*GraphQLApplier) Commit

func (a *GraphQLApplier) Commit(ctx context.Context, ref string, header *gitdiff.PatchHeader) (string, error)

Commit creates a commit with all pending file changes. It updates the branch ref to point at the new commit and returns the OID (SHA) of the commit. The branch must already exist and reference at the current base commit of the GraphQLApplier.

If header is not nil, Apply uses it to set the commit message. It ignores other fields set in header. In particular, the commit timestamp, author, and committer are always set by GitHub.

func (*GraphQLApplier) Reset

func (a *GraphQLApplier) Reset(base string)

Reset resets the applier so that future Apply calls start from commit base. It removes all pending file changes. Reset does not modify the repository.

func (*GraphQLApplier) SetV3Client

func (a *GraphQLApplier) SetV3Client(client *github.Client)

SetV3Client sets a REST API client used to implement functionality missing in the GraphQL API. Without a V3 client, the applier will fail on patches that modify binary and very large files.

type Reference

type Reference struct {
	// contains filtered or unexported fields
}

Reference is a named reference in a repository.

func NewReference

func NewReference(client *github.Client, repo Repository, ref string) *Reference

NewReference creates a new Reference for ref in repo.

func (*Reference) PullRequest

func (r *Reference) PullRequest(ctx context.Context, spec *github.NewPullRequest) (*github.PullRequest, error)

PullRequest create a new pull request for the reference. The reference must be a branch (start with "refs/heads/".) The pull request takes values from spec, except for Head, which is set to the reference.

func (*Reference) Set

func (r *Reference) Set(ctx context.Context, sha string, force bool) error

Set creates or updates the reference to point to sha. If force is true and the reference exists, Set updates it even if the update is not a fast-forward.

type Repository

type Repository struct {
	Owner string
	Name  string
}

Repository identifies a GitHub repository.

func ParseRepository

func ParseRepository(s string) (Repository, error)

ParseRepository parses a Repository from a string in "owner/name" format.

func (Repository) String

func (r Repository) String() string