gh describe

Emulate git describe --tags for shallow clone repositories.

The git describe command is a useful tool for versioning a development build. However, it requires access to the full history of all tags and branches, which can be a problem in workflows where you often work with shallow clones of repositories. This tool, gh-describe, retrieves the necessary historical information from the GitHub API instead of locally, allowing you to use git describe as you normally would even in shallow clone repositories.

Usage in GitHub Actions

- name: Git describe
  id: ghd
  uses: proudust/gh-describe@v2

Action inputs

All inputs are optional, and sensible defaults will be used if they are not set.

Name	Description	Default
token	Personal Access Token (PAT)	GITHUB_TOKEN
repo	Target repository	The owner and repository that triggered the workflow run.
commit-ish	Commit-ish object names to describe.	The commit sha that triggered the workflow run.
match	Only consider tags matching the given glob pattern.
exclude	Do not consider tags matching the given glob pattern.
default	If the name is not found, use this value.	If the name is not found, the action fails.

- name: Git describe
  id: ghd
  uses: proudust/gh-describe@v2
  with:
    token: ${{ secrets.ALT_GITHUB_TOKEN }} # Use a custom PAT instead of the default GITHUB_TOKEN
    repo: proudust/gh-describe-sample # Describe the other repository
    commit-ish: master # Needed for the other repository
    match: "v*.*.*" # Only tags with patch versions
    exclude: "*-beta,*-nightly" # Ignore tags that match any of these glob patterns (comma-separated)
    default: "v0.0.0" # Use this value if no tag is found, instead of failing

Action outputs

The following outputs can be used by subsequent workflow steps.

Name	Description	Example
describe	git describe --tags-like description.	v1.5.4-2-g4fdf9d0
tag	The most recent tag.	v1.5.4
distance	The number of additional commits from the most recent tag.	2
sha	The object name for the commit itself.	4fdf9d0b88fe5f55e465ae947bca6b6b55c39415
short-sha	The object name for the commit itself.	4fdf9d0

Step outputs can be accessed using the following example.
Note that in order to read the step outputs, the action step must have an ID.

- name: Git describe
  id: ghd
  uses: proudust/gh-describe@v2
- name: Check outputs
  run: |
    echo "describe  : ${{ steps.ghd.outputs.describe }}"
    echo "tag       : ${{ steps.ghd.outputs.tag }}"
    echo "distance  : ${{ steps.ghd.outputs.distance }}"
    echo "sha       : ${{ steps.ghd.outputs.sha }}"
    echo "short-sha : ${{ steps.ghd.outputs.short-sha }}"

Usage on your terminal

GitHub CLI Extensions

Require GitHub CLI and JavaScript Runtime (Deno or Node.js).

gh extensions install proudust/gh-describe
gh describe

Deno

Require GitHub CLI and Deno.

deno run --allow-run=gh,git https://deno.land/x/gh_describe@v2.2.0/main.ts

or

deno install --global --name gh-describe --allow-run=gh,git https://deno.land/x/gh_describe@v2.2.0/main.ts
gh-describe

Required permissions:

Permission	Reason
--allow-run=gh	Required to access the GitHub API via the gh CLI.
--allow-run=git	Required to get the remote URL and current commit SHA from the local repository.

Self-contained executable

Require GitHub CLI. Download from Release page.

Windows:

gh-describe-x86_64-pc-windows-msvc.exe

Mac or Linux:

./gh-describe-aarch64-apple-darwin
./gh-describe-x86_64-apple-darwin
./gh-describe-x86_64-unknown-linux-gnu

Help

$ gh describe --help
  Usage:   gh-describe [commit-ish]
  Version: v2.2.0

  Description:

    Emulate `git describe --tags` for shallow clone repositories.

  Options:

    -h, --help     - Show this help.
    -V, --version  - Show the version number for this program.

  Options like `git describe`:

    --match       <pattern...>  - Only consider tags matching the given glob pattern.
    --no-match                  - Clear and reset the list of match patterns.
    --exclude     <pattern...>  - Do not consider tags matching the given glob pattern.
    --no-exclude                - Clear and reset the list of exclude patterns.

  Options for `gh`:

    -R, --repo  <repo>  - Target repository. Format: OWNER/REPO

  Other options:

    --default  <tag>      - If the name is not found, use this value.
    --runtime  <runtime>  - If installed by `gh extension install`, can specify the execution runtime.  (Values: "deno", "node")

License

MIT License