Used By

Create and update Used By badge by leveraging GitHub's dependencies information via a pull request.

Usage

Run as GitHub Action

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/used-by.yml

    steps:
      - uses: actions/checkout@v7
      - uses: shenxianpeng/used-by@main # or tag
        with:
          repo: '${{ github.repository }}' # current repository
          update-badge: 'true'

      # create pull request if changed
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8
        with:
          add-paths: "README.md" # the file path to commit
          commit-message: "chore: update used-by badge by github-actions[bot]"
          title: "chore: automatic update used-by badge"
          base: main
          labels: documentation
          delete-branch: true

Required Inputs

repo:

• Description: GitHub repository name. e.g. shenxianpeng/used-by. Defaults to shenxianpeng/used-by.
• Default: 'shenxianpeng/used-by'

Optional Inputs

file-path:

• Description: The path to file. Defaults to README.md.
• Default: 'README.md'

badge-label:

• Description: The badge display name. Defaults to Used by.
• Default: 'Used by'

badge-color:

• Description: The badge display color. Defaults to informational.
• Default: 'informational'

badge-logo:

• Description: The badge display logo. Defaults to slickpic.
• Default: 'slickpic'

update-badge:

• Description: Update an existing badge whose count changed ('true' or 'false'); a missing badge is always added. Defaults to false.
• Default: 'false'

max-drop:

• Description: Skip the update when the count drops by more than this percentage (0-100), which usually means GitHub returned bad data. A warning is printed instead. Use 100 to accept any drop. Defaults to 50.
• Default: '50'

For supported values of badge-label, badge-color and badge-logo, see https://shields.io/badges/static-badge

Install used-by CLI

pip install git+https://github.com/shenxianpeng/used-by.git@main

Help of used-by CLI

used-by --help
usage: used-by [-h] [--repo REPO] [--file-path FILE_PATH] [--badge-label BADGE_LABEL] [--badge-color BADGE_COLOR] [--badge-logo BADGE_LOGO] [--update-badge UPDATE_BADGE] [--max-drop MAX_DROP]

Generate a Used By badge from GitHub dependents information.

options:
  -h, --help            show this help message and exit
  --repo REPO           GitHub repository name (e.g., shenxianpeng/used-by).
  --file-path FILE_PATH
                        The path to the file where the badge will be added. Defaults to README.md.
  --badge-label BADGE_LABEL
                        The badge display name. Defaults to Used by.
  --badge-color BADGE_COLOR
                        The badge display color. Defaults to informational.
  --badge-logo BADGE_LOGO
                        The badge display logo. Defaults to slickpic.
  --update-badge UPDATE_BADGE
                        Add or update badge if set. Defaults to False.
  --max-drop MAX_DROP   Do not update the badge when the count drops by more than this percentage, which usually means GitHub returned bad data. Use 100 to accept any drop. Defaults to 50.

Run used-by CLI

# generate markdown makeup text by default
$ used-by --repo shenxianpeng/used-by

Add Used By badge in README

Copy following content to show Used By badge in your repository README.

Markdown

[![Used by](https://img.shields.io/static/v1?label=Used%20by&message=10&color=informational&logo=slickpic)](https://github.com/shenxianpeng/used-by/network/dependents)<!-- used by badge -->

reStructuredText

.. image:: https://img.shields.io/static/v1?label=Used%20by&message=0&color=informational&logo=slickpic
    :target: https://github.com/shenxianpeng/used-by/network/dependents
    :alt: used-by

License

MIT © 2024-present Xianpeng Shen