git-create-branch

Create a local branch

$ git create-branch [branch_name]

$ git create-branch [[-r|--remote]] [branch_name]

$ git create-branch [[-r|--remote]] upstream [branch_name]

git branch [] [ []]

-d, --delete
    Delete a branch. The branch must be fully merged into its upstream branch, or into HEAD if no upstream was set. Can be repeated to delete multiple branches.

-D
    Delete a branch irrespective of its merged status.

-f, --force
    Force the branch to be created or reset. When creating, it overwrites an existing branch with the same name. When resetting, it discards the current HEAD and forces the branch pointer to the specified .

-m, --move
    Move/rename a branch. Can be repeated to move multiple branches.

-M
    Move/rename a branch even if the new branch name already exists.

-c, --copy
    Copy a branch. Can be repeated to copy multiple branches.

-C
    Copy a branch even if the new branch name already exists.

-l, --list
    List branches. With optional pattern, e.g., "git branch -l 'feature/*'".

-r, --remotes
    List or delete (if used with -d) the remote-tracking branches.

-a, --all
    List both remote-tracking and local branches.


    The name of the new branch to create.


    The commit at which the new branch will start. Can be a commit hash, branch name, tag, or any other ref.

The git-branch command is used to create, list, rename, and delete branches. Creating a branch essentially creates a new pointer to a specific commit, allowing you to develop new features or bug fixes in isolation without affecting the main branch (often named 'main' or 'master'). It does not switch you to the new branch; you'll still be on your current branch. To switch to the new branch, use the git-checkout command. A local branch name cannot collide with an existing remote-tracking branch. If the -d or -D flag is specified, this command will delete a branch. You must be on the branch you intend to delete. It’s important to note that deleting a branch doesn't remove the commits associated with it, if they are reachable from another branch. They are merely orphaned. Before creating a new branch, it’s generally good practice to update your local repository with the latest changes from the remote repository using git-fetch or git-pull to ensure your new branch is based on the most up-to-date code.

Deleting a branch with -D can result in the loss of work if the commits on that branch are not reachable from any other branch.

Creating a branch when in detached HEAD state can be tricky. It's generally better to checkout a branch first, and then create your new branch. In detached HEAD state, you are not on any branch. If you make commits, and then switch away, these commits could be lost if there are no other references to them.

The git-branch command is a core part of Git's branching model, which is a key feature of its design. It has been present since the early versions of Git and has been refined over time to improve usability and add features. Its initial purpose was to provide a simple and efficient way to isolate development efforts. Over time, features like listing remote branches and forceful deletion were added.

git checkout(1), git merge(1), git fetch(1), git pull(1), git remote(1)