How do I include the git branch name with setuptools-scm?

ONLINECAST

2 min read

·

05-10-2024

10

0

Share

Tagging Your Python Packages with Git Branch Names: A Guide to setuptools-scm

When building and distributing Python packages, it's crucial to track versions effectively. setuptools-scm is a powerful tool that automatically generates version numbers from your Git repository, keeping your code organized and your releases transparent. However, sometimes you need more than just the commit hash or tag – you might want to include the current Git branch name in the version string. This article will guide you through achieving this with setuptools-scm.

The Problem: Branch Names and Package Versioning

You're working on a project where it's essential to know the specific branch a package was built from, particularly during development or for specific feature branches. While setuptools-scm excels at incorporating commit hashes and tags, it doesn't directly include the branch name in the version string.

Original Code and Approach

Let's start with a basic example demonstrating how to use setuptools-scm for versioning:

from setuptools import setup

setup(
    name='my_package',
    use_scm_version={
        "write_to": "my_package/_version.py",
        "write_to_template": '__version__ = "{version}"\n',
    },
    setup_requires=['setuptools_scm'],
)

This code utilizes setuptools_scm to extract version information from your Git repository and writes it to a file called _version.py. However, this doesn't include the branch name.

Adding Branch Names to Your Version String

Here's how you can modify your setup.py to incorporate the branch name into your version string:

from setuptools import setup
import subprocess

def get_git_branch():
    try:
        output = subprocess.check_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD']).strip().decode('utf-8')
        return output
    except subprocess.CalledProcessError:
        return 'unknown'

setup(
    name='my_package',
    use_scm_version={
        "write_to": "my_package/_version.py",
        "write_to_template": '__version__ = "{version}+{branch}"\n',
        "local_scheme": "no-local-version",
    },
    setup_requires=['setuptools_scm'],
)

Explanation

1. Branch Name Retrieval: The get_git_branch() function uses subprocess to execute the git rev-parse --abbrev-ref HEAD command, which returns the current branch name.
2. Version String Formatting: The write_to_template parameter now incorporates the branch name using {branch}.
3. Local Scheme Modification: The local_scheme parameter is set to "no-local-version" to avoid generating a local version string based on uncommitted changes.

Benefits of Including Branch Names

• Enhanced Traceability: Having the branch name in the version string provides greater clarity about the specific development environment or feature branch from which the package was built. This is particularly valuable for troubleshooting issues or identifying the origin of a particular package release.
• Improved Development Workflow: This approach can streamline development processes. For example, it allows for easy identification of packages built from specific feature branches, aiding in testing and integration.
• Debugging and Error Analysis: When encountering problems, knowing the branch name associated with a particular package version can significantly assist in debugging and error analysis.

Considerations and Best Practices

• Branch Name Conventions: Consider establishing clear naming conventions for your branches to maintain consistency and readability in version strings.
• Deployment Practices: Be mindful of how branch names impact your release processes. For production releases, you might want to use a specific tag or a convention that indicates a stable branch (e.g., "main" or "master").
• Automated Testing: Implement automated tests to verify that your versioning strategy is functioning correctly and that the branch names are accurately incorporated into your package versions.

Conclusion

By incorporating branch names into your package versions using setuptools-scm, you gain valuable insights into your development process and improve the traceability of your code. This approach helps you effectively manage your projects and releases, ensuring a smoother and more informed development workflow.

Remember, always test your changes thoroughly and follow best practices for version control and package management.