branch-names

Project Introduction: branch-names

Overview

The branch-names project is a focused tool designed to simplify the process of retrieving the current branch or tag name in a GitHub Action workflow without including the unwanted /ref/* prefix. Its simplicity and effectiveness make it a valuable tool for developers who require refined control over their Git workflows on platforms like Ubuntu, macOS, and Windows.

Key Features

• Branch Name Retrieval: Easily get the current branch name without the '/ref/*' prefix. For instance, it converts 'refs/heads/main' to 'main'.
• Tag Name Adjustments: It offers the option to strip prefixes from tag names, such as reshaping v0.0.1 into 0.0.1 by removing the v.
• Event Detection: The tool can detect workflows triggered by default and non-default branches, providing flexibility in automation scripts.
• Wide Git Support: It supports all valid Git branch names, ensuring compatibility across various development environments.

Usage

The branch-names action is integrated into GitHub workflows using a simple YAML configuration. It provides multiple outputs, including current branch names (regular and default), whether the branch is a tag, and related reference branches. Here’s a basic usage example:

steps:
  - name: Get branch names.
    id: branch-names
    uses: tj-actions/branch-names@v8
      
  - name: Running on the default branch.
    if: steps.branch-names.outputs.is_default == 'true'
    run: |
      echo "Running on default: ${{ steps.branch-names.outputs.current_branch }}"

Inputs and Outputs

Inputs

One primary input is configurable:

• strip_tag_prefix: A string value that specifies a prefix to remove from tag names, allowing cleaner version number presentations.

Outputs

The action provides detailed outputs for various scenarios, such as:

• current_branch: The name of the current branch.
• default_branch: Name of the default branch, typically main or master.
• is_default: A boolean flag signifying if the current branch is the default.
• tag: The tag name that triggered the workflow, if applicable.

Supported Events

branch-names is versatile, supporting a variety of git events, including push, pull_request, and tag. This flexibility allows for robust automation across different types of workflow triggers.

Integration and Support

For those looking to integrate this action with checking out code, branch-names is easily compatible with actions like actions/checkout, where it can guide the code to be checked out based on the head ref of a pull request.

Community and Contributions

branch-names thrives on community involvement, offering opportunities for contributions. The project embraces contributions in code, documentation, and more, as highlighted by their all-contributors specification.

Contact and Support

Bugs or issues can be reported on their GitHub issues page, where users are encouraged to provide detailed information about their operating system and how to reproduce any problems.

Overall, branch-names stands out as an essential tool for GitHub Actions users, streamlining the management of branch and tag names within automated workflows. It's a testament to the power of focused, community-driven open-source projects crafted with practicality in mind.