PullCraft

PullCraft is a simple but powerful CLI tool for automating the creation and updating of GitHub pull requests. It creates diffs based on your code changes and a base or specified branch, then uses generative AI to create meaningful PR titles and descriptions. It then creates the PR for you and opens the PR in the browser for final review. You can provide hints, templates, and other options to customize the PR creation process to your needs.

Table of Contents

• Features
• Prerequisites
• Quick Start
• Installation
• Usage
  • CLI Examples
  • Library Usage
• Configuration Options and CLI Flags
• Template Placeholders
• Examples
• Troubleshooting
• Contributing
• License
• Acknowledgments

Features

• Automatic PR creation and updating
• AI-powered generation of PR titles and descriptions
• Customizable templates for PR content
• Support for different GitHub authentication strategies
• Configurable file exclusions and diff thresholds
• Option to dump diffs to a file for manual review

Prerequisites

• Git
• A GitHub account
• An OpenAI API key

Installation

Option 1: Using npm (for Node.js users)

If you have Node.js installed, you can install PullCraft using npm:

npm install -g pullcraft

Option 2: Direct download (for non-Node.js users)

Linux and macOS

1. Download and run the installation script:

   curl -O https://raw.githubusercontent.com/jamesvillarrubia/pullcraft/main/build/install.sh
   sudo bash install.sh

This script will automatically:

• Fetch the latest version of PullCraft
• Download the executable
• Make it executable
• Move it to /usr/local/bin
• Verify the installation

If you encounter any issues, please check the error messages and ensure you have the necessary permissions.

Windows

1. Download the installation script:

   curl -O https://raw.githubusercontent.com/jamesvillarrubia/pullcraft/main/build/install.bat
   

2. Right-click on the downloaded install.bat file and select "Run as administrator".

   NOTE: The windows binary currently untested and has been removed. Best option for Windows is to install with npm -g pullcraft

This script will automatically:

• Fetch the latest version of PullCraft
• Download the executable
• Create an installation directory
• Move the executable to the installation directory
• Add the installation directory to your PATH
• Verify the installation

After installation, restart your command prompt for the PATH changes to take effect.

If you encounter any issues, please check the error messages and ensure you're running the script with administrator privileges.

Quick Start

1. Set up your OpenAI API key:

   • Option 1: Create a .env file in your project root:

     OPENAI_API_KEY=your_api_key_here

   • Option 2: Set it as an environment variable in your shell:

     export OPENAI_API_KEY=your_api_key_here

   • Option 3: Use the --api-key option when running PullCraft:

     pullcraft main feature-branch --api-key your_api_key_here

2. Create a PR:

   pullcraft main feature-branch

Usage

CLI Examples

PullCraft is primarily used as a command-line tool. Here are some common usage scenarios:

1. Basic usage (create a PR from current branch to the default base branch):

   pullcraft

2. Specify base branch:

   pullcraft main

3. Specify both base and compare branches:

   pullcraft main feature-branch

4. Use custom file exclusions:

   pullcraft main --exclusions "*.md,package-lock.json"

5. Open the PR in the browser after creation:

   pullcraft main --open-pr

6. Use a specific GitHub strategy:

   pullcraft main --github-strategy octokit

7. Provide a hint for the AI:

   pullcraft main --hint "This PR updates the user authentication system"

8. Use custom templates:

   pullcraft main --title-template "feat: {{title}}" --description-template "## Changes\n\n{{description}}"

9. Set a custom diff threshold:

   pullcraft main --diff-threshold 600

10. Use a different OpenAI model:

    pullcraft main --model gpt-4

11. Dump the diff to a file for review:

    pullcraft main --dumpTo diff.txt

12. Combine multiple options:

    pullcraft main feature-branch --open-pr --exclusions "*.md" --hint "Bug fix for login system" --diff-threshold 500

Remember, you can always use the --help option to see all available commands and options:

pullcraft --help

These examples showcase the flexibility of PullCraft's CLI. You can mix and match options to suit your specific needs and workflow.

Library Usage

import PullCraft from 'pullcraft';

const options = {
  // ... your configuration options
};

const pullCraft = new PullCraft(options);
pullCraft.createPr('main', 'feature-branch');

Configuration Options and CLI Flags

PullCraft can be configured using a .pullcraftrc file, environment variables, or command-line options. The config file is ingested via cosmiconfig, so it's location and format is quite flexible. The configuration is resolved in the following order:

1. Command-line options
2. Configuration file
3. Default values

Example .pullcraftrc file:

{
  "baseDefault": "main",
  "openPr": true,
  "exclusions": [".md", "package-lock.json"],
  "githubStrategy": "gh"
}

PullCraft will look for the OpenAI API key in the following order:

1. Command-line option (--api-key)
2. Environment variable (OPENAI_API_KEY)
3. .env file in the project root
4. Configuration file (.pullcraftrc)

Always ensure your API key is kept secure and not exposed in public repositories.

Option	Type	Default	CLI Flag	Alias	Description
baseDefault	string	'main'	--base-branch <branch>	-b	Default base branch for PR creation
compareBranch	string	-	--compare-branch <branch>	-c	Specify the compare branch
openPr	boolean	false	--open-pr	-o	Automatically open PR in browser after creation
exclusions	string[]	[]	--exclusions <patterns>	-e	File exclusion patterns (comma-separated)
githubStrategy	string	'gh'	--github-strategy <strategy>	-g	GitHub authentication strategy ('gh' or 'octokit')
githubToken	string	-	--github-token <token>		GitHub token (required for 'octokit' strategy)
placeholderPattern	string	'__KEY__'	--placeholder-pattern <pattern>	-p	Pattern for placeholders in templates
diffThreshold	number	400	--diff-threshold <number>	-d	Maximum number of lines for diff display
titleTemplate	string	'__title__'	--title-template <template>	-t	Template for PR title
descriptionTemplate	string	'__description__'	--description-template <template>	-d	Template for PR description
hint	string	-	--hint <text>	-h	Hint for the AI about the type of changes
dumpTo	string	-	--dump-to <filename>		Filename to dump the diff for manual review
openaiConfig.apiKey	string	-	--api-key <key>		OpenAI API Key
openaiConfig.url	string	OpenAI's default	--url <url>		Custom URL for OpenAI API
openaiConfig.model	string	'gpt-3.5-turbo'	--model <model>	-m	OpenAI model to use
openaiConfig.maxTokens	number	500	--max-tokens <number>		Maximum number of tokens in the OpenAI response
openaiConfig.n	number	1	--n <number>		Number of completions to generate for OpenAI
openaiConfig.stop	string	-	--stop <sequence>		Stop sequence for OpenAI API
openaiConfig.temperature	number	0.7	--temp <number>		Sampling temperature for OpenAI API

Additional CLI-only flags:

• --help: Display help information
• --version (-v): Display version information Example usage:

pullcraft main feature-branch --open-pr -e ".md,package-lock.json" -d 600 -m gpt-4 --temp 0.8 --hint "Refactoring authentication system"

This table provides a comprehensive list of all CLI options and flags, including their aliases (where applicable) and descriptions. It gives users a quick reference for all available command-line arguments they can use with PullCraft.

Template Placeholders

PullCraft uses a placeholder system in its title and body templates to dynamically insert information from the git repository and the diff. The default placeholder pattern is __KEY__, where KEY is replaced with the actual placeholder name.

Available Default Placeholders

• __owner__: The owner of the repository
• __repo__: The name of the repository
• __baseBranch__: The base branch of the pull request
• __compareBranch__: The compare branch of the pull request

Using Placeholders in Templates

You can use these placeholders in your title and body templates. For example, the title template: is

export const titleTemplate = '<:build,chore,ci,docs,feat,fix,perf,refactor,style,test>: <TITLE GOES HERE>\n Example: "fix: Adds a missing semicolon"';

But this can be overridden by the command line option. For example, you can use:

pullcraft main --title-template '__baseBranch__ -> __compareBranch__ : <TITLE GOES HERE>\n Example: "main -> ci/add-colon : Adds a missing semicolon"';

In this example:

• __compareBranch__ and __baseBranch__ will be replaced with the actual branch names
• <TITLE GOES HERE> is simply instructions for the AI on where to put the title and is not a strict placeholder.

Custom Placeholders

You can also define custom placeholders in your configuration or command line options. These will be available for use in your templates and will be filled by the AI-generated content.

Changing the Placeholder Pattern

If you prefer a different placeholder pattern, you can change it using the --placeholder-pattern option:

bash
pullcraft main --placeholder-pattern "{{KEY}}" --title-template "feat({{repo}}): {{KEY_FEATURE}}"

This will use {{KEY}} as the placeholder pattern instead of __KEY__. This flexibility allows you to customize the templates to fit your project's conventions and needs.

Troubleshooting

If you encounter issues while using PullCraft, try the following:

1. Ensure your OpenAI API key is correctly set and has sufficient credits.
2. Check that you have the necessary permissions for the GitHub repository you're working with.
3. Verify that your local Git repository is up to date with the remote.
4. If using the 'gh' strategy, ensure you're logged in with the GitHub CLI (gh auth login).

For more detailed troubleshooting, please check our FAQ or open an issue on GitHub.

Contributing

Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• OpenAI for providing the AI capabilities
• The GitHub CLI and Octokit teams for their excellent APIs