hub-branch

Show the name of the currently active branch

$ hub branch

$ hub branch [branch_name]

hub branch [options] [<branch-name>] [<start-point>]
hub branch [options] --delete [-r] <branch-name>
hub branch [options] --move [<old-name>] <new-name>
hub branch [options] --set-upstream [<branch-name>]

<branch-name>
    The name of the branch to create, delete, or operate on.

<start-point>
    A commit or reference (e.g., `HEAD`, `origin/main`) from which to start a new branch.

-a, --all
    Show both local and remote-tracking branches. When creating a branch, it can also push the branch to the remote, effectively setting it up.

-r, --remotes
    Show remote-tracking branches. When used with --delete, it deletes the remote branch.

-d, --delete
    Delete the specified branch. This operation will fail if the branch has unmerged changes.

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

-u, --set-upstream, --track
    Set the upstream branch for the new branch. When creating a branch, it configures it to track the remote branch with the same name.

-v, --verbose
    Show more verbose output, including associated pull request numbers when listing branches.

-m, --move
    Move/rename a branch. If <old-name> is omitted, it defaults to the current branch.

The hub branch command extends standard `git branch` functionality by integrating GitHub-specific features, primarily related to pull requests. It allows users to list, create, delete, and manage Git branches with an awareness of their corresponding pull requests on GitHub.

When listing branches, hub branch can display associated pull request numbers. For creating new branches, it simplifies the workflow by allowing immediate pushing to the remote and even opening a pull request directly from the command line. Deleting branches can also encompass deleting the remote counterpart and closing related pull requests, making it a powerful tool for developers working extensively with GitHub repositories.

The hub branch command relies on the hub tool being installed and properly configured. It functions as an extension to git branch, so basic Git knowledge is beneficial. Its GitHub-specific features (like pull request integration) only work effectively when operating within a repository hosted on GitHub.

One of the key advantages of hub branch is its deep integration with GitHub pull requests. When listing branches with -v, it can display the associated pull request number. When creating a new branch, hub branch can optionally push it to the remote and even open a new pull request for it directly on GitHub, significantly speeding up the development workflow.

Unlike plain git branch, hub branch can have different defaults. For instance, when creating a branch and pushing it, hub branch often implicitly sets up upstream tracking or attempts to create the remote branch if it doesn't exist, reducing the need for explicit --set-upstream flags.

The hub project, which includes the branch subcommand, was created to provide a more integrated command-line experience for developers using GitHub. Its development stemmed from the need to bridge the gap between Git's native capabilities and GitHub's rich platform features, particularly for common workflows like creating and managing pull requests. hub branch specifically evolved to streamline operations that traditionally required multiple Git commands and manual interaction with the GitHub web interface.

git-branch(1), hub(1), git(1)