hg-push
Push Mercurial commits to a remote repository
TLDR
Push changes to the "default" remote path
Push changes to a specified remote repository
Push a new branch if it does not exist (disabled by default)
Specify a specific revision changeset to push
Specify a specific branch to push
Specify a specific bookmark to push
SYNOPSIS
hg push [OPTION]... [DEST]
PARAMETERS
--force, -f
Pushes even if it creates new remote heads or results in a non-fast-forward update. Use with caution as it can rewrite remote history or complicate others' pulls.
--rev REV, -r REV
Pushes only the specified revision REV and its ancestors that are not yet at the destination.
--branch BRANCH, -b BRANCH
Pushes only changesets belonging to the named BRANCH. This will push the branch and its ancestors.
--bookmark BOOKMARK, -B BOOKMARK
Pushes the specified BOOKMARK and any associated changesets.
--new-branch
Allows pushing new branches even if the remote repository is configured to reject them by default.
--mq
When used in an MQ-enabled repository, pushes the applied patches (patches that are committed into the main repository).
--stream
Attempts to push changes using a streaming protocol if supported by the server, potentially improving performance for large pushes.
--ssh CMD, -S CMD
Specifies the CMD to use when connecting to a remote repository via SSH.
--remotecmd CMD, -e CMD
Specifies the CMD to run on the remote side.
--bundle FILE, -t FILE
Pushes changes into a local bundle FILE instead of a remote repository. This creates a file that can be transferred manually.
--insecure, -U
Do not verify the server's SSL certificate when pushing over HTTPS. Not recommended for production environments.
DEST
The path or URL of the destination repository. If omitted, Mercurial uses the default path configured in the local repository's .hg/hgrc file.
DESCRIPTION
hg push is a fundamental command in Mercurial, a distributed version control system, used to transfer new changesets from your local repository to a remote repository. This operation makes your local commits visible and available to others who pull from the remote.
By default, hg push sends all new changesets, including new heads (branches), that are present in your local repository but not in the destination. If the remote repository has divergent changes (e.g., you pushed to a different branch than expected, or someone else pushed concurrent changes), Mercurial will typically prevent the push unless explicitly told to force it, ensuring repository integrity and preventing accidental history rewriting. It's crucial for collaboration in a distributed environment, allowing developers to share their work.
CAVEATS
Non-Fast-Forward Pushes: Mercurial typically prevents pushes that would create new heads on the remote without merging, or that would remove history. The --force option bypasses this but should be used with extreme caution, as it can complicate other developers' work or lead to lost changes if not handled correctly.
Permissions: Successful pushes require write permissions on the remote repository.
Network Connectivity: An active and stable network connection is necessary to communicate with the remote repository.
DEFAULT DESTINATION
If no destination is specified, hg push attempts to push to the default path configured in your repository's .hg/hgrc file, typically under the [paths] section (e.g., default = ssh://user@host/repo). This provides a convenient way to manage common remote targets.
PUSHING SPECIFIC CHANGES
Beyond pushing all new changes, hg push offers granular control through options like --branch, --rev, or --bookmark. These allow developers to push only specific branches, revisions, or bookmarks, which is useful for targeted updates or when collaborating on multiple features simultaneously.
SERVER-SIDE HOOKS
Remote Mercurial repositories often utilize server-side hooks (e.g., pretxnpush, changegroup) that trigger actions or enforce policies upon receiving a push. These hooks can perform validations, send notifications, or integrate with other systems, ensuring code quality and workflow compliance.
HISTORY
Mercurial (hg) was initiated by Matt Mackall in 2005, evolving rapidly as a robust distributed version control system. The hg push command has been a cornerstone of its distributed workflow from its early days, essential for sharing changesets between repositories. Its core functionality for transferring committed changes has remained consistent, while additional options like --new-branch, --bookmark, and various protocol enhancements have been introduced over time to accommodate new features and improve efficiency. This continuous refinement reflects Mercurial's commitment to providing flexible and reliable version control for developers.