From efd43ce4417e5e72d2aa4045005f52339527f9e4 Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sat, 24 Jan 2026 20:24:44 -0800 Subject: [PATCH 1/7] chore: bump checkout version --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eb22fa3..d9feca4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,7 +6,7 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 with: fetch-depth: 2 - uses: ruby/setup-ruby@v1 From 8e7584edf1b40ef303c1b24327c8b9163ee8f741 Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sun, 25 Jan 2026 03:22:38 -0800 Subject: [PATCH 2/7] chore: avoid a deprecated argument --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d9feca4..b50dbb0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,4 +22,4 @@ jobs: CODECOV_TOKEN: ${{ secrets.CODECOV_ORG_TOKEN }} with: fail_ci_if_error: true - file: coverage/coverage.xml + files: coverage/coverage.xml From 8df264490c91f63b777e4d565df561521385a91b Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sun, 25 Jan 2026 03:27:49 -0800 Subject: [PATCH 3/7] style: edit whitespace --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cc6c129..4644540 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # [Codecov](https://codecov.io) Bash Example + [![codecov](https://codecov.io/gh/codecov/example-bash/branch/master/graph/badge.svg)](https://codecov.io/gh/codecov/example-bash) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash?ref=badge_shield) @@ -7,14 +8,17 @@ ### Produce Coverage Reports ## Caveats + ### Private Repo + Repository tokens are required for (a) all private repos, (b) public repos not using GitHub Actions, Travis-CI, CircleCI or AppVeyor. Find your repository token at Codecov and provide via appending `-t ` to you where you upload reports. ## Links + - [Community Boards](https://community.codecov.io) - [Support](https://codecov.io/support) - [Documentation](https://docs.codecov.io) ## License -[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash?ref=badge_large) +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash?ref=badge_large) From a73ed75cff46ef40b7d007a01f66acc512aaedbd Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sun, 25 Jan 2026 03:27:50 -0800 Subject: [PATCH 4/7] docs(blame): create .git-blame-ignore-revs --- .git-blame-ignore-revs | 1 + 1 file changed, 1 insertion(+) create mode 100644 .git-blame-ignore-revs diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 0000000..5639545 --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1 @@ +8df264490c91f63b777e4d565df561521385a91b # style: edit whitespace From d9ef20817ff805f2a5646ecdf0df2c97ad995294 Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sun, 25 Jan 2026 04:20:45 -0800 Subject: [PATCH 5/7] docs: add comments to the workflow --- .github/workflows/ci.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b50dbb0..0990159 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,21 +1,43 @@ name: Test and coverage +# This workflow runs on every push to collect code coverage from Bash scripts +# and uploads the results to Codecov for tracking and visualization. on: push jobs: build: runs-on: ubuntu-latest steps: + # Checkout the repository code + # fetch-depth: 2 is required for Codecov to properly detect the commit SHA. + # Codecov needs access to the parent commit to calculate diffs, especially + # for merge commits. Without this, you may see errors like: + # "Issue detecting commit SHA. Please run actions/checkout with fetch-depth > 1 or set to 0" - uses: actions/checkout@v6 with: fetch-depth: 2 + + # Set up Ruby environment + # bashcov is a Ruby-based tool, so we need Ruby installed to run it - uses: ruby/setup-ruby@v1 with: ruby-version: head + + # Install Ruby dependencies from Gemfile + # - bashcov: Runs Bash scripts with coverage instrumentation + # - simplecov-cobertura: Converts coverage reports to Cobertura XML format + # (Codecov requires XML, not the default HTML output) - name: Install Ruby dependencies run: bundle update --bundler && bundle install + + # Run the Bash script with coverage collection + # bashcov instruments the script and tracks which lines are executed, + # generating coverage data that SimpleCov processes - name: Run script run: bashcov script.sh + + # Upload coverage report to Codecov + # The coverage.xml file is generated by simplecov-cobertura (configured in .simplecov) - name: Upload reports to Codecov uses: codecov/codecov-action@v5 env: From 31e17df6f746a22edb6b5dc03925c5c85e3f1a31 Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sun, 25 Jan 2026 04:34:07 -0800 Subject: [PATCH 6/7] docs: comment on .simplecov --- .simplecov | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.simplecov b/.simplecov index 8806695..5bbdfb8 100644 --- a/.simplecov +++ b/.simplecov @@ -1,5 +1,9 @@ require 'simplecov' require 'simplecov-cobertura' -# Creates a `coverage/coverage.xml` file +# Configure SimpleCov to output coverage in Cobertura XML format. +# While SimpleCov's default output is HTML (useful for local viewing), .html coverage +# reports are not supported by Codecov. + +# This formatter creates a `coverage/coverage.xml` file that Codecov can read. SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter From c6085d2a7cda29552159f837c89d1f42f5094ec2 Mon Sep 17 00:00:00 2001 From: Michael I Chen Date: Sun, 25 Jan 2026 04:39:20 -0800 Subject: [PATCH 7/7] docs: enhance README.md --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4644540..f15c374 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,101 @@ [![codecov](https://codecov.io/gh/codecov/example-bash/branch/master/graph/badge.svg)](https://codecov.io/gh/codecov/example-bash) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fcodecov%2Fexample-bash?ref=badge_shield) -## Guide +This repository demonstrates how to collect and report code coverage for Bash scripts using [Codecov](https://codecov.io). It provides a complete, working example that you can use as a template for your own projects. -### Produce Coverage Reports +## Quick Start -## Caveats +1. **Copy the key files** to your repository: + - [`.github/workflows/ci.yml`](.github/workflows/ci.yml) - GitHub Actions workflow for running coverage + - [`.simplecov`](.simplecov) - SimpleCov configuration for XML output + - `Gemfile` - Ruby dependencies -### Private Repo +2. **Install dependencies**: -Repository tokens are required for (a) all private repos, (b) public repos not using GitHub Actions, Travis-CI, CircleCI or AppVeyor. Find your repository token at Codecov and provide via appending `-t ` to you where you upload reports. + ```bash + bundle install + ``` -## Links +3. **Run coverage locally**: + + ```bash + bashcov script.sh + ``` + +4. **View the coverage report**: + - HTML report: `coverage/index.html` + - XML report (for Codecov): `coverage/coverage.xml` + +5. **Set up GitHub Actions**: + - The workflow will automatically run on push + - For private repos, add `CODECOV_TOKEN` as a repository secret + +## How It Works + +This setup uses a combination of Ruby tools to instrument and collect coverage from Bash scripts: + +1. **`bashcov`** runs your Bash script with coverage instrumentation, tracking which lines are executed +2. **`simplecov-cobertura`** converts the coverage data into Cobertura XML format +3. **Codecov Action** uploads the XML report to Codecov for visualization and tracking + +The default SimpleCov output is HTML, which Codecov cannot process. That's why we use `simplecov-cobertura` to generate XML format that Codecov understands. + +## Key Files + +### [`.github/workflows/ci.yml`](.github/workflows/ci.yml) + +This GitHub Actions workflow: + +- Checks out your code (with `fetch-depth: 2` for proper commit detection) +- Sets up Ruby and installs dependencies +- Runs your script with `bashcov` to collect coverage +- Uploads the coverage report to Codecov + +See the workflow file for detailed inline comments explaining each step. + +### [`.simplecov`](.simplecov) + +This configuration file tells SimpleCov to output coverage in Cobertura XML format instead of the default HTML. Codecov requires XML format to process coverage reports. + +## Dependencies + +This project uses two Ruby gems: + +- **`bashcov`**: A coverage tool for Bash scripts. It instruments your script and tracks which lines are executed during runtime. Learn more at [bashcov on GitHub](https://github.com/infertux/bashcov). + +- **`simplecov-cobertura`**: A formatter for SimpleCov that outputs coverage reports in Cobertura XML format. While SimpleCov's default output is HTML (great for local viewing), Codecov requires XML format to ingest coverage data. This gem bridges that gap. + +## Example Script + +The included [`script.sh`](script.sh) demonstrates a simple Bash script with: + +- Function definitions +- Conditional logic +- Multiple execution paths + +When run with `bashcov`, it shows which code paths are executed and which are not, helping you identify untested code. + +## Private Repositories + +Repository tokens are required for: + +- All private repositories +- Public repositories not using GitHub Actions, Travis-CI, CircleCI, or AppVeyor + +To use a token: + +1. Find your repository token at [Codecov](https://codecov.io) +2. Add it as a GitHub secret named `CODECOV_TOKEN` (or `CODECOV_ORG_TOKEN` for organization-level tokens) +3. The workflow will automatically use it + +## Documentation + +- **[Codecov Bash Documentation](https://about.codecov.io/language/bash/)** - Official guide for Bash coverage +- **[codecov-action Repository](https://github.com/codecov/codecov-action)** - GitHub Action for uploading coverage +- **[Codecov Documentation](https://docs.codecov.io)** - Complete Codecov documentation +- **[How to get Coverage Metrics for Bash Scripts](https://about.codecov.io/blog/how-to-get-coverage-metrics-for-bash-scripts/)** - Blog post with detailed instructions + +## Support - [Community Boards](https://community.codecov.io) - [Support](https://codecov.io/support)