Mercurial SCM

Warnings

• gotcha Direct use of Mercurial's internal Python API (e.g., `from mercurial import ...`) is primarily intended for writing extensions and is considered unstable. Its license is GPL-2.0-or-later. For stable, permissive-licensed programmatic interaction, consider `hgapi` which wraps the command-line interface, or `hglib` for the command server.
  Fix: For general repository operations from Python, evaluate using `hgapi` or `hglib`. If writing an extension, consult the official Mercurial extension development guides and be prepared for internal API changes.
• breaking Mercurial has adjusted its Python version support over time. Version 6.9 dropped support for Python 3.6 and 3.7. Version 7.2.0 was likely the last to support Python 3.9, with future releases focusing on newer Python versions (e.g., 3.14, 3.15).
  Fix: Ensure your project uses Python >=3.9. For future compatibility, plan to upgrade Python versions as Mercurial support shifts. Check release notes for specific version requirements.
• breaking Mercurial 7.0 introduced compliance with PEP 517 for packaging. This means `setup.py` can no longer be called directly for building; instead, PyPA's `build` package should be used. This primarily affects maintainers who build Mercurial from source or create custom distributions.
  Fix: If building Mercurial from source, use standard PEP 517 build tools (e.g., `python -m build`). Refer to the release notes for build-time dependencies (`wheel`, `setuptools`, `setuptools_scm`, `docutils`).
• breaking The 7.2.1 release included a 'large import-cycle-breaking series' due to Python typing efforts. This refactoring, involving new files, may make merges more difficult for existing extension maintainers and could break older extensions that relied on specific internal import paths or structures.
  Fix: Extension maintainers should carefully review the raw changes and refactoring mentioned in the 7.2.1 release notes and adapt their extensions accordingly.

Install

• pip install mercurial Install Mercurial

Imports

• ui, hg

  from mercurial import ui, hg

  These are common imports for interacting with Mercurial's core API, typically when writing extensions or programmatic tools that embed Mercurial functionality.

Quickstart

This quickstart demonstrates how to programmatically initialize a Mercurial repository, create a file, and commit it using the internal `mercurial` Python API. This approach is typically used for developing Mercurial extensions or deeply embedded functionality. For simpler command-line interactions from Python, external libraries like `hglib` (for command server) or `hgapi` (wrapping CLI) might be considered as they offer a more stable API than the internal `mercurial` modules.

import os
import shutil
from mercurial import ui, hg

# Create a dummy directory for the repository
repo_path = 'my_test_repo'
if os.path.exists(repo_path):
    shutil.rmtree(repo_path)
os.makedirs(repo_path)

# Initialize a new Mercurial repository
repo = hg.repository(ui.ui(), repo_path, create=True)
print(f"Repository initialized at: {repo_path}")

# Create a file
file_path = os.path.join(repo_path, 'hello.txt')
with open(file_path, 'w') as f:
    f.write('Hello, Mercurial!')
print(f"Created file: {file_path}")

# Add and commit the file
# Note: Mercurial's internal API for add/commit can be complex.
# This example uses `add` and then `commit` via the repo object.
# For simpler CLI-like interaction, consider `hglib` or `hgapi`.
# The 'add' command is implicitly handled by `commit` for untracked files in newer versions/contexts, 
# but explicitly adding first is generally safer for robust scripts.
repo.add([file_path])
repo.commit(text='Initial commit', user='Test User <test@example.com>')

print("File committed.")

# Verify the commit (optional: run hg log in the directory to confirm)
# You would typically interact with changesets, manifests, etc. for more complex verification.
logs = repo.changelog.read() # Read changelog to get revision info
if logs:
    latest_rev = repo.changelog.tip()
    print(f"Latest revision: {latest_rev.node()[:12]}")
    print(f"Commit message: {latest_rev.description()}")

# Clean up the test repository (optional)
shutil.rmtree(repo_path)
print(f"Cleaned up {repo_path}")