gh-repo-create
Create a new GitHub repository
TLDR
Create a new repository interactively
Create a new repository with a specified name and description
Create a private repository from the current directory
Clone the new repository locally after creation
Push the current directory to a new GitHub repository
SYNOPSIS
gh repo create [repository-name | local-path] [flags]
PARAMETERS
--add-readme
Adds an initial README file to the repository.
--add-gitignore
Adds a .gitignore file with a specified template (e.g., "Python", "Node").
--add-license
Adds a license file with a specified template (e.g., "MIT", "Apache-2.0").
--allow-forking
Allows the repository to be forked (default for public repos).
--confirm
Confirms repository creation without prompting for user confirmation.
-d, --description
Provides a description for the new repository.
--default-branch
Sets the name for the default branch (e.g., "main", "master").
--disable-issues
Disables the issues feature for the repository.
--disable-projects
Disables the projects feature for the repository.
--disable-wiki
Disables the wiki feature for the repository.
--enable-lfs
Enables Git Large File Storage (LFS) for the repository.
--enable-merge-commit
Enables the merge commit strategy for pull requests.
--enable-rebase-merge
Enables the rebase and merge strategy for pull requests.
--enable-squash-merge
Enables the squash and merge strategy for pull requests.
-h, --homepage
Sets the homepage URL for the repository.
-i, --internal
Makes the repository internal (visible to organization members only).
--org
Specifies the organization under which to create the repository.
-p, --public
Makes the new repository public.
-r, --private
Makes the new repository private (this is the default visibility if no other is specified).
--remote
Sets the name for the remote (default: "origin") when creating from a local path.
--source
Specifies a local directory path to initialize the repository from and push its contents.
--team
Assigns a team to the repository (for organization repos only).
--template
Creates the new repository from an existing template repository on GitHub.
DESCRIPTION
The gh-repo-create command is an integral part of the GitHub CLI (Command Line Interface), designed to streamline the process of creating new repositories directly from your terminal.
It eliminates the need to navigate the web UI, making repository setup faster and more efficient, especially for developers who prefer command-line workflows or scripting automated tasks.
This command allows users to specify various repository attributes at creation time, including its visibility (public, private, internal), a description, a homepage URL, and the inclusion of initial files like a README, .gitignore, or license.
Furthermore, gh-repo-create supports creating repositories within specific organizations, setting a default branch name, disabling features like issues or wikis, and configuring merge strategies.
It can also initialize a new local Git repository and link it to the newly created remote GitHub repository, providing a seamless setup from local to remote.
CAVEATS
Authentication Required: You must be authenticated with GitHub CLI (`gh auth login`) to create repositories. Your authentication token needs sufficient permissions (e.g., repo scope).
Naming Restrictions: Repository names must be unique within your user account or organization and adhere to GitHub's naming conventions (e.g., no spaces, certain special characters).
Network Connectivity: An active internet connection is necessary to communicate with GitHub's servers.
Organization Permissions: When creating repositories in an organization, you must have the necessary administrative or creation privileges within that organization.
INTERACTIVE MODE
If you run gh repo create without any arguments (e.g., just `gh repo create`), it enters an interactive mode. It will prompt you step-by-step for the repository name, visibility, and other initial settings. This is particularly helpful for new users or when you're unsure of all available options.
CREATING FROM LOCAL DIRECTORY
When run inside an existing local Git repository (or a directory where you want to initialize one), gh repo create can automatically create a new GitHub repository with the same name and push the local repository's contents to it, automatically setting up the remote connection. This streamlines the process of taking a local project to GitHub.
HISTORY
The gh-repo-create command is a core component of the GitHub CLI, which was initially released in beta in May 2020 and reached general availability in September 2020. It was designed to bring the functionality of GitHub's web interface directly to the command line, enabling developers to manage common GitHub tasks without context switching. Since its inception, gh repo create has been a fundamental feature, continuously updated with new flags and options to match GitHub's evolving repository features and user demands for more granular control over repository creation.
