How to use the command 'gh pr create' (with examples)

The gh pr create command is a part of the GitHub CLI toolset, a powerful suite designed to streamline GitHub interactions directly from your terminal. This specific command allows developers to efficiently manage pull requests by offering various options to customize and create pull requests for their repositories. Its versatility in handling different scenarios makes it an ideal tool for projects demanding collaborative code management.

Use case 1: Interactively create a pull request

Code:

gh pr create

Motivation:

Using the gh pr create command without any additional arguments is perfect for users who prefer an interactive approach to creating pull requests. This method allows you to input information step-by-step, making it exceedingly user-friendly and accessible for newcomers to the GitHub CLI or GitHub in general. It ensures that you consciously fill in necessary details like title, description, and other settings for the pull request, reducing chances of overlooking any important information.

Explanation:

The command gh pr create operates in interactive mode when executed without flags or options. This prompts the user through a guided interface, soliciting essential details about the pull request such as the title, description, and base branch. This is advantageous when you need to ensure that all pull request details are well thought out and conform to the project’s requirements.

Example Output:

Opening pull request in your browser...
Pull request successfully created.
View it here: <URL>

Use case 2: Create a pull request using the branch’s commit messages for title and description

Code:

gh pr create --fill

Motivation:

The --fill option is ideal when the current branch’s commit messages sufficiently describe the changes. This option automates the filling of the pull request title and description, thus saving time, especially in scenarios where the commit messages are comprehensive and well-documented. It ensures consistency between commit messages and pull request details, making project maintenance more straightforward.

Explanation:

The --fill flag instructs the GitHub CLI to automatically populate the title and description fields of the pull request based on the commit messages from the current branch. This is useful for automation and reducing manual input, maintaining a concise and coherent narrative from code changes up to the pull request level.

Example Output:

Received pull request title: "Feature addition to improve API performance"
Received pull request description: "Implement caching and request batching as per commits 12345 and 67890"
Pull request created: <URL>

Use case 3: Create a draft pull request

Code:

gh pr create --draft

Motivation:

The draft pull request option is designed for cases where the code is not yet ready for a full review but you still want to share it with your team for early feedback or previews. This approach helps in getting initial input on coding direction, opening discussions on implementation strategies, or confirming API architectures. It marks the pull request clearly as a work-in-progress, avoiding unnecessary thorough reviews before the code is ready.

Explanation:

The --draft flag creates the pull request in draft mode. Draft pull requests are not meant for complete code reviews but rather as a preliminary showcase. This status signals to collaborators that the changes are still under development and not ready to be merged, which is visually indicated on the GitHub interface with a ‘Draft’ label.

Example Output:

Draft pull request created.
View it: <URL>

Use case 4: Create a pull request specifying the base branch, title, and description

Code:

gh pr create --base base_branch --title "title" --body "body"

Motivation:

This use case is particularly beneficial for developers who know exactly what they want to convey in the pull request and where it needs to be directed. By specifying the base branch, title, and pull request body all at once, you can create the pull request efficiently in a single command. This is ideal for repetitive tasks or when integrating within scripts for automated workflows.

Explanation:

• --base base_branch: Specifies the target branch into which the changes should be merged. It’s crucial for directing changes accurately, especially in projects with multiple active branches.
• --title "title": Defines the title of the pull request. Having a descriptive title helps in recognizing the purpose of the changes at a glance.
• --body "body": This argument allows you to provide a detailed description directly within the command line. It is essential for outlining the changes and giving context or instructions to reviewers.

Example Output:

Pull request to base_branch successfully created.
Title: Feature Enhancement
Description: This pull request aims to improve the feature by adding user authentication.
URL: <URL>

Use case 5: Start opening a pull request in the default web browser

Code:

gh pr create --web

Motivation:

When you need the flexibility of manually entering or editing pull request details through a web interface, the --web option is your go-to choice. This command opens up the standard pull request creation page for the repository in your default web browser. It combines the convenience of command-line initiation with the user-friendliness of the GitHub web interface’s comprehensive pull request tools.

Explanation:

The --web flag directs the GitHub CLI to launch the full pull request form in the user’s default browser. This is invaluable for users who require additional browser-based functionalities, such as inserting rich text, images, or accessing templates that are better handled through a GUI than via command line.

Example Output:

Opening pull request form in browser...
Browser opened at: <GitHub Pull Request URL>

Conclusion:

The gh pr create command is a versatile tool enabling developers to manage pull requests in a manner best suited to their workflow needs, whether through interactive prompts, automated suggestions, draft preparations, definitive command specifications, or browser-based fine-tuning. Utilizing these diverse options, teams can ensure that their collaborative efforts are both efficient and adaptable to varying project requirements.