mirror of
https://github.com/tj-actions/branch-names.git
synced 2024-11-27 16:33:51 +08:00
315 lines
12 KiB
Markdown
315 lines
12 KiB
Markdown
## branch-names
|
|
|
|
[](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)
|
|
[](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)
|
|
[](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on)
|
|
[](https://github.com/search?o=desc\&q=tj-actions+branch-names+language%3AYAML\&s=\&type=Code)
|
|
|
|
[](https://app.codacy.com/gh/tj-actions/branch-names/dashboard?utm_source=gh\&utm_medium=referral\&utm_content=\&utm_campaign=Badge_grade)
|
|
[](https://github.com/tj-actions/branch-names/actions?query=workflow%3ACI)
|
|
[](https://github.com/tj-actions/branch-names/actions/workflows/sync-release-version.yml)
|
|
|
|
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
|
|
|
|
[](#contributors-)
|
|
|
|
<!-- ALL-CONTRIBUTORS-BADGE:END -->
|
|
|
|
Get a branch or tag name without the `/ref/*` prefix.
|
|
|
|
## Table of Contents
|
|
|
|
* [Features](#features)
|
|
* [Usage](#usage)
|
|
* [Inputs](#inputs)
|
|
* [Outputs](#outputs)
|
|
* [Events](#events)
|
|
* [`push*`](#push)
|
|
* [`pull_request*`](#pull_request)
|
|
* [`tag*`](#tag)
|
|
* [Other supported events](#other-supported-events)
|
|
* [Possible usage with actions/checkout:](#possible-usage-with-actionscheckout)
|
|
* [Credits](#credits)
|
|
* [Report Bugs](#report-bugs)
|
|
* [Contributors ✨](#contributors-)
|
|
|
|
## Features
|
|
|
|
* Retrieve the current branch name without any prefix. (e.g. `'refs/heads/main'` -> `'main'`)
|
|
* Retrieve the current tag with an option to strip the prefix (e.g. `v0.0.1` -> `v` -> `0.0.1`)
|
|
* Detect actions triggered by non default branches
|
|
* Detect actions triggered by the default branch
|
|
* Supports all valid [git branch names](https://wincent.com/wiki/Legal_Git_branch_names)
|
|
|
|
## Usage
|
|
|
|
```yaml
|
|
...
|
|
|
|
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 }}"
|
|
# Outputs: "Running on default: main"
|
|
|
|
- name: Running on a pull request branch.
|
|
if: steps.branch-names.outputs.is_default == 'false'
|
|
run: |
|
|
echo "Running on pr: ${{ steps.branch-names.outputs.current_branch }}"
|
|
# Outputs: "Running on pr: feature/test"
|
|
|
|
- name: Running on a pull request branch.
|
|
if: steps.branch-names.outputs.is_default == 'false'
|
|
run: |
|
|
echo "Base branch: ${{ steps.branch-names.outputs.base_ref_branch }}"
|
|
# Outputs: "Base branch: main"
|
|
|
|
- name: Running on any event.
|
|
run: |
|
|
echo "Default branch: ${{ steps.branch-names.outputs.default_branch }}"
|
|
# Outputs: "Default branch: main"
|
|
```
|
|
|
|
If you feel generous and want to show some extra appreciation:
|
|
|
|
Support this project with a :star:
|
|
|
|
[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]
|
|
|
|
[buymeacoffee]: https://www.buymeacoffee.com/jackton1
|
|
|
|
[buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
|
|
|
|
## Inputs
|
|
|
|
<!-- AUTO-DOC-INPUT:START - Do not remove or modify this section -->
|
|
|
|
```yaml
|
|
- uses: tj-actions/branch-names@v8
|
|
id: branch-names
|
|
with:
|
|
# The prefix that should be stripped from the tag
|
|
# e.g `v` -> with a tag `v0.0.1` -> returns
|
|
# `0.0.1`
|
|
# Type: string
|
|
strip_tag_prefix: ''
|
|
|
|
```
|
|
|
|
<!-- AUTO-DOC-INPUT:END -->
|
|
|
|
## Outputs
|
|
|
|
<!-- AUTO-DOC-OUTPUT:START - Do not remove or modify this section -->
|
|
|
|
| OUTPUT | TYPE | DESCRIPTION |
|
|
|---------------------------------------------------------------------------------|--------|----------------------------------------------------------------------------------|
|
|
| <a name="output_base_ref_branch"></a>[base\_ref\_branch](#output_base_ref_branch) | string | The target branch of a <br>pull request or tag e.g <br>`main` |
|
|
| <a name="output_current_branch"></a>[current\_branch](#output_current_branch) | string | The current branch name regardless <br>of event\_type e.g `main`, `feature/test` |
|
|
| <a name="output_default_branch"></a>[default\_branch](#output_default_branch) | string | The default branch name e.g <br>`main` OR `master` |
|
|
| <a name="output_head_ref_branch"></a>[head\_ref\_branch](#output_head_ref_branch) | string | The source branch of a <br>pull request e.g `feature/test` |
|
|
| <a name="output_is_default"></a>[is\_default](#output_is_default) | string | Returns `"true"` if the current <br>branch is the default else <br>`"false"`. |
|
|
| <a name="output_is_tag"></a>[is\_tag](#output_is_tag) | string | Returns `"true"` if the current <br>branch is a tag else <br>`"false"`. |
|
|
| <a name="output_ref_branch"></a>[ref\_branch](#output_ref_branch) | string | The branch that triggered the <br>workflow run. e.g `1/merge`, `main` |
|
|
| <a name="output_tag"></a>[tag](#output_tag) | string | The tag that triggered the <br>workflow run. e.g `v0.0.1`, `0.0.1` |
|
|
|
|
<!-- AUTO-DOC-OUTPUT:END -->
|
|
|
|
## Events
|
|
|
|
### `push*`
|
|
|
|
```yaml
|
|
on:
|
|
push:
|
|
branches:
|
|
- main
|
|
|
|
...
|
|
steps:
|
|
- name: Get branch names
|
|
id: branch-names
|
|
uses: tj-actions/branch-names@v8
|
|
|
|
- name: Current branch names
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.current_branch }}"
|
|
# Outputs: "main" the branch that triggered the push event.
|
|
|
|
- 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 }}"
|
|
# Outputs: "Running on default: main".
|
|
|
|
- name: Running on the default branch (i.e non tag based branch).
|
|
if: steps.branch-names.outputs.is_tag == 'false' && steps.branch-names.outputs.is_default == 'true'
|
|
run: |
|
|
echo "Running on branch: ${{ steps.branch-names.outputs.current_branch }}"
|
|
# Outputs: "Running on branch: main".
|
|
|
|
- name: Get Ref brach name
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.ref_branch }}"
|
|
# Outputs: "main"
|
|
|
|
- name: Default branch name
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.default_branch }}"
|
|
# Outputs: "main" the default branch.
|
|
```
|
|
|
|
### `pull_request*`
|
|
|
|
```yaml
|
|
on:
|
|
pull_request:
|
|
branches:
|
|
- main
|
|
|
|
...
|
|
steps:
|
|
- name: Get branch names
|
|
id: branch-names
|
|
uses: tj-actions/branch-names@v8
|
|
|
|
- name: Current branch names
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.current_branch }}"
|
|
# Outputs: "feature/test" current PR branch.
|
|
|
|
- name: Running on a non tag based branch and a PR branch.
|
|
if: steps.branch-names.outputs.is_default == 'false'
|
|
run: |
|
|
echo "Running on branch: ${{ steps.branch-names.outputs.current_branch }}"
|
|
# Outputs: "Running on branch: feature/test".
|
|
|
|
- name: Running on a pull request (i.e non tag based branch).
|
|
if: steps.branch-names.outputs.is_tag == 'false' && steps.branch-names.outputs.is_default == 'false'
|
|
run: |
|
|
echo "Running on branch: ${{ steps.branch-names.outputs.current_branch }}"
|
|
# Outputs: "Running on branch: feature/test".
|
|
|
|
- name: Get Ref branch name
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.ref_branch }}"
|
|
# Outputs: "1/merge"
|
|
|
|
- name: Get Head Ref branch names (i.e The current pull request branch)
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.head_ref_branch }}"
|
|
# Outputs: "feature/test" current PR branch.
|
|
|
|
- name: Get Base Ref branch names (i.e The target of a pull request.)
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.base_ref_branch }}"
|
|
# Outputs: "main".
|
|
|
|
- name: Default branch names
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.default_branch }}"
|
|
# Outputs: "main" the default branch.
|
|
```
|
|
|
|
### `tag*`
|
|
|
|
```yaml
|
|
on:
|
|
push:
|
|
tags:
|
|
- '*'
|
|
|
|
...
|
|
steps:
|
|
- name: Get branch names
|
|
id: branch-names
|
|
uses: tj-actions/branch-names@v8
|
|
with:
|
|
strip_tag_prefix: v # Optionally strip the leading `v` from the tag.
|
|
|
|
- name: Running on a tag branch.
|
|
if: steps.branch-names.outputs.is_tag == 'true'
|
|
run: |
|
|
echo "Running on: ${{ steps.branch-names.outputs.tag }}"
|
|
# Outputs: "Running on: 0.0.1".
|
|
|
|
- name: Get the current tag
|
|
if: steps.branch-names.outputs.is_tag == 'true' # Replaces: startsWith(github.ref, 'refs/tags/')
|
|
run: |
|
|
echo "${{ steps.branch-names.outputs.tag }}"
|
|
# Outputs: "0.0.1"
|
|
```
|
|
|
|
### Other supported events
|
|
|
|
See [.github/workflows/test.yml](https://github.com/tj-actions/branch-names/blob/main/.github/workflows/test.yml) for more examples.
|
|
|
|
### Possible usage with [actions/checkout](https://github.com/actions/checkout):
|
|
|
|
```yaml
|
|
on:
|
|
pull_request:
|
|
branches:
|
|
- develop
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Get branch names.
|
|
id: branch-names
|
|
uses: tj-actions/branch-names@v8
|
|
- uses: actions/checkout@v4
|
|
with:
|
|
ref: ${{ steps.branch-names.outputs.head_ref_branch }}
|
|
```
|
|
|
|
* Free software: [MIT license](LICENSE)
|
|
|
|
## Credits
|
|
|
|
This package was created with [Cookiecutter](https://github.com/cookiecutter/cookiecutter).
|
|
|
|
## Report Bugs
|
|
|
|
Report bugs at https://github.com/tj-actions/branch-names/issues.
|
|
|
|
If you are reporting a bug, please include:
|
|
|
|
* Your operating system name and version.
|
|
* Any details about your workflow that might be helpful in troubleshooting.
|
|
* Detailed steps to reproduce the bug.
|
|
|
|
## Contributors ✨
|
|
|
|
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
|
|
|
|
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
|
|
|
|
<!-- prettier-ignore-start -->
|
|
|
|
<!-- markdownlint-disable -->
|
|
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<td align="center" valign="top" width="14.28%"><a href="https://github.com/loarca"><img src="https://avatars.githubusercontent.com/u/22898638?v=4?s=100" width="100px;" alt="Alejandro Loarca"/><br /><sub><b>Alejandro Loarca</b></sub></a><br /><a href="https://github.com/tj-actions/branch-names/commits?author=loarca" title="Code">💻</a></td>
|
|
<td align="center" valign="top" width="14.28%"><a href="https://ianwoodard.me"><img src="https://avatars.githubusercontent.com/u/17186604?v=4?s=100" width="100px;" alt="Ian Woodard"/><br /><sub><b>Ian Woodard</b></sub></a><br /><a href="https://github.com/tj-actions/branch-names/commits?author=IanWoodard" title="Documentation">📖</a></td>
|
|
<td align="center" valign="top" width="14.28%"><a href="https://home.boidol.dev/"><img src="https://avatars.githubusercontent.com/u/652404?v=4?s=100" width="100px;" alt="Raphael Boidol"/><br /><sub><b>Raphael Boidol</b></sub></a><br /><a href="https://github.com/tj-actions/branch-names/commits?author=boidolr" title="Documentation">📖</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<!-- markdownlint-restore -->
|
|
|
|
<!-- prettier-ignore-end -->
|
|
|
|
<!-- ALL-CONTRIBUTORS-LIST:END -->
|
|
|
|
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
|