{"id":6716,"library":"mercurial","title":"Mercurial SCM","description":"Mercurial is a fast, scalable, and distributed revision control (version control) system designed for efficient handling of projects of any size. It is primarily implemented in Python, with performance-critical parts in C and Rust. The library is actively maintained with regular releases, with version 7.2.1 being the latest stable release as of April 1, 2026.","status":"active","version":"7.2.1","language":"en","source_language":"en","source_url":"https://www.mercurial-scm.org/","tags":["version-control","scm","mercurial"],"install":[{"cmd":"pip install mercurial","lang":"bash","label":"Install Mercurial"}],"dependencies":[{"reason":"Mercurial requires Python 3.9 or newer. As of version 7.2.0, Python 3.9 support is likely to be deprecated in future releases.","package":"python","optional":false},{"reason":"Optional dependency for improved ZSTD compression/decompression functionality, falling back to system package if vendored module is not available.","package":"zstd","optional":true}],"imports":[{"note":"These are common imports for interacting with Mercurial's core API, typically when writing extensions or programmatic tools that embed Mercurial functionality.","symbol":"ui, hg","correct":"from mercurial import ui, hg"}],"quickstart":{"code":"import os\nimport shutil\nfrom mercurial import ui, hg\n\n# Create a dummy directory for the repository\nrepo_path = 'my_test_repo'\nif os.path.exists(repo_path):\n    shutil.rmtree(repo_path)\nos.makedirs(repo_path)\n\n# Initialize a new Mercurial repository\nrepo = hg.repository(ui.ui(), repo_path, create=True)\nprint(f\"Repository initialized at: {repo_path}\")\n\n# Create a file\nfile_path = os.path.join(repo_path, 'hello.txt')\nwith open(file_path, 'w') as f:\n    f.write('Hello, Mercurial!')\nprint(f\"Created file: {file_path}\")\n\n# Add and commit the file\n# Note: Mercurial's internal API for add/commit can be complex.\n# This example uses `add` and then `commit` via the repo object.\n# For simpler CLI-like interaction, consider `hglib` or `hgapi`.\n# The 'add' command is implicitly handled by `commit` for untracked files in newer versions/contexts, \n# but explicitly adding first is generally safer for robust scripts.\nrepo.add([file_path])\nrepo.commit(text='Initial commit', user='Test User <test@example.com>')\n\nprint(\"File committed.\")\n\n# Verify the commit (optional: run hg log in the directory to confirm)\n# You would typically interact with changesets, manifests, etc. for more complex verification.\nlogs = repo.changelog.read() # Read changelog to get revision info\nif logs:\n    latest_rev = repo.changelog.tip()\n    print(f\"Latest revision: {latest_rev.node()[:12]}\")\n    print(f\"Commit message: {latest_rev.description()}\")\n\n# Clean up the test repository (optional)\nshutil.rmtree(repo_path)\nprint(f\"Cleaned up {repo_path}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"breaking","affected_versions":"7.2.0 and later for Python 3.9; 6.9 and later for Python 3.6/3.7"},{"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`).","message":"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.","severity":"breaking","affected_versions":"7.0 and later"},{"fix":"Extension maintainers should carefully review the raw changes and refactoring mentioned in the 7.2.1 release notes and adapt their extensions accordingly.","message":"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.","severity":"breaking","affected_versions":"7.2.1 and later"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}