git-branch

List all branches (local and remote; the current branch is highlighted by *)

$ git branch [[-a|--all]]

$ git branch [[-a|--all]] --contains [commit_hash]

$ git branch --show-current

$ git branch [branch_name]

$ git branch [branch_name] [commit_hash]

$ git branch [[-m|--move]] [old_branch_name] [new_branch_name]

$ git branch [[-d|--delete]] [branch_name]

$ git push [remote_name] [[-d|--delete]] [remote_branch_name]

git branch []
git branch [] []
git branch [] (--delete | -d | -D) ...
git branch [] (--move | -m | -M) []
git branch [] (--copy | -c | -C) []
git branch [] (--list | -r | -a)

-d, --delete
    Delete the branch. Fails if the branch has unmerged changes.

-D
    Force delete the branch, even if it has unmerged changes.

-m, --move
    Rename a branch. Fails if the new branch name already exists.

-M
    Force rename a branch, overwriting existing branches with the new name.

-c, --copy
    Copy a branch. Fails if the new branch name already exists.

-C
    Force copy a branch, overwriting existing branches with the new name.

-r, --remotes
    List or delete remote-tracking branches.

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

-v, --verbose
    Show SHA-1 and commit subject for each branch.

-vv
    Show SHA-1, commit subject, and tracking information.

--track
    When creating a new branch, set up tracking information.

--no-track
    When creating a new branch, do not set up tracking information.

--set-upstream-to=<upstream>
    Set/reset the upstream branch for the current branch.

--unset-upstream
    Remove the upstream information for the current branch.

--show-current
    Print the name of the current branch.

--list
    List branches (default behavior when no arguments).

<branchname>
    The name of the branch to create, delete, or rename.

<start-point>
    The commit from which the new branch will start. Defaults to HEAD.

The git branch command is a fundamental tool for managing your project's development lines. It allows you to list existing branches, create new ones, delete obsolete ones, and rename branches. When invoked without arguments, it lists all local branches, highlighting the current branch with an asterisk. Branches in Git are lightweight pointers to commits, enabling parallel development streams without significant overhead. This command is crucial for organizing your work, experimenting with new features, and collaborating effectively within a Git repository. While git branch manages the pointers, switching between branches is handled by git checkout or git switch. It also provides options to view remote-tracking branches and set up upstream relationships for easier pushing and pulling.

git branch itself does not switch your working directory or HEAD. To switch to a different branch, use git checkout or git switch.
Deleting a branch with -d will fail if it contains unmerged changes; use -D to force deletion, but be cautious as this can lead to lost work. Renaming a local branch that is tracked by a remote branch often requires manual intervention to update the remote reference and avoid confusion.

When a local branch tracks a remote-tracking branch, Git knows which remote branch it corresponds to. This enables simpler git pull and git push operations without specifying the remote or branch name. git branch --set-upstream-to allows you to configure this for existing branches, while git branch <new-branch> --track sets it up on creation.

While Git imposes few restrictions, common practice suggests using descriptive, lowercase, hyphen-separated names (e.g., feature/new-login, bugfix/fix-auth). Avoid spaces or special characters. Keeping names concise and clear improves repository readability and collaboration.

Creating a new branch from a specific commit SHA (e.g., git branch my-experiment <sha1>) without immediately checking it out can leave you in a 'detached HEAD' state if you then check out that SHA. git branch itself doesn't cause this, but understanding the relationship between branches, commits, and HEAD is crucial for navigating it.

The concept of cheap, flexible branching was a core design principle of Git from its inception, contrasting sharply with earlier VCS systems. The git branch command, being fundamental to this concept, has been part of Git since its earliest versions. While its core functionality remains consistent, various options have been added over time to enhance usability, such as --track for easier upstream setup and -D for forceful deletion. The introduction of git switch in Git 2.23 provided a dedicated command for switching branches, separating it from git checkout's overloaded functionality, but git branch remains the primary tool for managing branch existence.

git checkout(1), git switch(1), git push(1), git merge(1), git rebase(1), git remote(1)