| Option | Description |
plugin_languages
|
Enable languages plugin
![]() |
✨ On master/main
type: boolean
default: no
|
plugin_languages_ignored
|
Ignored languages
![]() |
✨ On master/main
type: array
(comma-separated)
|
plugin_languages_skipped
|
Skipped repositories
![]() |
⏩ Inherits repositories_skipped
✨ On master/main
type: array
(newline-separated)
|
plugin_languages_limit
|
Display limit
![]() |
✨ On master/main
type: number
(0 ≤
𝑥
≤ 8)
zero behaviour: disable
default: 8
|
plugin_languages_threshold
|
Display threshold (percentage)
![]() |
✨ On master/main
type: string
default: 0%
|
plugin_languages_other
|
Group unknown, ignored and over-limit languages into "Other" category
If this option is enabled, "Other" category will not be subject to plugin_languages_threshold.
It will be automatically hidden if empty.
![]() |
✨ On master/main
type: boolean
default: no
|
plugin_languages_colors
|
Custom languages colors
![]() |
✨ On master/main
type: array
(comma-separated)
default: github
|
plugin_languages_aliases
|
Custom languages names
![]() |
✨ On master/main
type: string
|
plugin_languages_sections
|
Displayed sections
Note that recently-used is only available when plugin_languages_indepth is enabled
![]() |
✨ On master/main
type: array
(comma-separated)
default: most-used
allowed values: |
plugin_languages_details
|
Additional details
Note that lines is only available when plugin_languages_indepth is enabled
![]() |
✨ On master/main
type: array
(comma-separated)
allowed values:- bytes-size
- percentage
- lines
|
plugin_languages_indepth
|
Indepth mode
⚠️ read documentation first
![]() |
✨ On master/main
🌐 Web instances must configure settings.json:
- metrics.cpu.overuse
- metrics.run.tempdir
- metrics.run.git
type: boolean
default: false
|
plugin_languages_indepth_custom
|
Indepth mode - Custom repositories
Specify a list of additional repositories to analyze.
Below are the supported syntax formats:
owner/repo (e.g. lowlighter/metrics)owner/repo@branch (e.g. lowlighter/metrics@main)owner/repo@branch:commits (e.g. lowlighter/metrics@main:v1.0..v1.1)
- See
git rev-list documentation for more information about commits syntax
It is possible to specify repositories that are not hosted on github.com by passing a full url instead.
In this case the repository must be accessible directly.
ℹ️ This option bypass plugin_languages_skipped
![]() |
✨ On master/main
type: array
(comma-separated)
|
plugin_languages_analysis_timeout
|
Indepth mode - Analysis timeout
![]() |
✨ On master/main
type: number
(1 ≤
𝑥
≤ 60)
default: 15
|
plugin_languages_analysis_timeout_repositories
|
Indepth mode - Analysis timeout (repositories)
![]() |
✨ On master/main
type: number
(0 ≤
𝑥
≤ 15)
zero behaviour: disable
default: 7.5
|
plugin_languages_categories
|
Indepth mode - Displayed categories (most-used section)
![]() |
✨ On master/main
type: array
(comma-separated)
default: markup, programming
allowed values:- data
- markup
- programming
- prose
|
plugin_languages_recent_categories
|
Indepth mode - Displayed categories (recently-used section)
![]() |
✨ On master/main
type: array
(comma-separated)
default: markup, programming
allowed values:- data
- markup
- programming
- prose
|
plugin_languages_recent_load
|
Indepth mode - Events to load (recently-used section)
![]() |
✨ On master/main
type: number
(100 ≤
𝑥
≤ 1000)
default: 300
|
plugin_languages_recent_days
|
Indepth mode - Events maximum age (day, recently-used section)
![]() |
✨ On master/main
type: number
(0 ≤
𝑥
≤ 365)
zero behaviour: disable
default: 14
|
## 🔎 `indepth` mode
The default algorithm uses the top languages from each repository you contributed to using GitHub GraphQL API (which is similar to the displayed languages bar on github.com). When working in collaborative projects with a lot of people, these numbers may be less representative of your actual work.
The `plugin_languages_indepth` option lets you use a more advanced algorithm for more accurate statistics.
Under the hood, it will clone your repositories, run [linguist-js](https://github.com/Nixinova/Linguist) (a JavaScript port of [GitHub linguist](https://github.com/github/linguist)) and iterate over patches matching your `commits_authoring` setting.
Since git lets you use any email and username for commits, *metrics* may not be able to detect a commit ownership if it isn't the same as your GitHub personal data. By default, it will use your GitHub username, but you can configure additional matching usernames and email addresses using `commits_authoring` option.
*Example: configuring `indepth` mode*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_indepth: yes
commits_authoring: firstname lastname, username, username@users.noreply.github.com
```
> 💡 This feature unlocks the `lines` option in `plugin_languages_details`
> ⚠️ This feature significantly increase workflow time
> ⚠️ Since this mode iterates over **each matching commit of each repository**, it is not suited for large code base, especially those with a large amount of commits and the ones containing binaries. While `plugin_languages_analysis_timeout` and `plugin_languages_analysis_timeout_repositories` can be used to increase the default timeout for analysis, please be responsible and keep this feature disabled if it cannot work on your account to save GitHub resources and our planet 🌏
> ⚠️ Although *metrics* does not send any code to external sources, repositories are temporarily cloned on the GitHub Action runner. It is advised to keep this option disabled when working with sensitive data or company code. Use at your own risk, *metrics* and its authors **cannot** be held responsible for any resulting code leaks. Source code is available for auditing at [analyzers.mjs](/source/plugins/languages/analyzers.mjs).
> 🌐 Web instances must enable this feature in `settings.json`
Below is a summary of the process used to compute indepth statistics:
## Most used mode
1. Fetch GPG keys linked to your GitHub account
- automatically add attached emails to `commits_authoring`
- *web-flow* (GitHub's public key for changes made through web-ui) is also fetched
2. Import GPG keys so they can be used to verify commits later
3. Iterate through repositories
- early break if `plugin_languages_analysis_timeout` is reached
- skip repository if it matches `plugin_languages_skipped`
- include repositories from `plugin_languages_indepth_custom`
- a specific branch and commit range can be used
- a source other than github.com can be used
4. Clone repository
- target branch is checkout
5. List of authored commits is computed
- using `git log --author` and `commits_authoring` to search in commit headers
- using `git log --grep` and `commits_authoring` to search in commit body
- ensure these are within the range specified by `plugin_languages_indepth_custom` (if applicable)
6. Process authored commits
- early break if `plugin_languages_analysis_timeout_repositories` is reached
- using `git verify-commit` to check authenticity against imported GPG keys
- using `git log --patch` to extract added/deleted lines/bytes from each file
- using [GitHub linguist](https://github.com/github/linguist) ([linguist-js](https://github.com/Nixinova/LinguistJS)) to detect language for each file
- respect `plugin_languages_categories` option
- if a file has since been deleted or moved, checkout on the last commit file was present and run linguist again
7. Aggregate results
## Recently used mode
1. Fetch push events linked to your account (or target repository)
- matching `plugin_languages_recent_load` and `plugin_languages_recent_days` options
- matching committer emails from `commits_authoring`
2. Process authored commits
- using [GitHub linguist](https://github.com/github/linguist) ([linguist-js](https://github.com/Nixinova/LinguistJS)) to detect language for each file
- respect `plugin_languages_recent_categories` option
- directly pass file content rather than performing I/O and simulating a git repository
3. Aggregate results
## 📅 Recently used languages
This feature uses a similar algorithm as `indepth` mode, but uses patches from your events feed instead.
It will fetch a specified amount of recent push events and perform linguistic analysis on it.
> ⚠️ Note that *metrics* won't be able to use more events than GitHub API is able to provide
*Example: display recently used languages from 400 GitHub events from last 2 weeks*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_sections: recently-used
plugin_languages_recent_load: 400
plugin_languages_recent_days: 14
```
> 🌐 Web instances must enable this feature in `settings.json`
## 🥽 Controling which languages are displayed
Several options lets you customize which languages should be displayed.
It is possible to ignore completely languages or those lower than a given threshold, skip repositories, and filter by language categories.
*Example: hide HTML and CSS languages, skip lowlighter/metrics repository*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_ignored: html, css
plugin_languages_skipped: lowlighter/metrics
```
*Example: hide languages with less than 2% usage*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_threshold: 2%
```
> 💡 The threshold feature will automatically scale remaining languages so the total percentage is always 100%. However, other stats like bytes count and lines are not affected.
When using `indepth` mode, it is possible to hide languages per category.
Supported categories are `data`, `markup`, `programming` and `prose`.
*Example: hide data and prose languages from stats*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_categories: data, prose
plugin_languages_recent_categories: data, prose
```
## 🎨 Using custom colors
The plugin uses GitHub language colors, but it may be hard to distinguish them depending on which languages you use.
It is possible to use custom colors using `plugin_languages_colors` option.
The following syntaxes are supported:
- A predefined set from [colorsets.json](colorsets.json) *(support limited to 8 languages max)*
- `${language}:${color}` to change the color of a language *(case insensitive)*
- `${n}:${color}` to change the color of the n-th language
Both hexadecimal and [named color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) are supported.
*Example: using a predefined color set*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_colors: rainbow
plugin_languages_limit: 8
```
*Example: setting JavaScript to red, the first language to blue and the second one to `#ff00aa`*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_colors: javascript:red, 0:blue, 1:#ff00aa
```
## ✍️ Using custom languages name
This plugin is limited by [GitHub linguist](https://github.com/github/linguist) capabilities, meaning that some languages may be mislabeled in some cases.
To mitigate this, it is possible to use `plugin_languages_aliases` option and provide a list of overrides using the following syntax: `${language}:${alias}` *(case insensitive)*.
*Example: display JavaScript as JS and TypeScript as TS*
```yml
- uses: lowlighter/metrics@latest
with:
plugin_languages: yes
plugin_languages_aliases: javascript:JS typescript:TS
```
## ℹ️ Examples workflows
```yaml
name: Most used
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ""
plugin_languages: yes
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_limit: 4
```
```yaml
name: Most used (with details)
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.details.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ""
plugin_languages: yes
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_details: bytes-size, percentage
plugin_languages_limit: 4
```
```yaml
name: Recently used
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.recent.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ""
plugin_languages: yes
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_sections: recently-used
plugin_languages_details: bytes-size, percentage
plugin_languages_limit: 4
```
```yaml
name: Indepth analysis
uses: lowlighter/metrics@latest
with:
filename: metrics.plugin.languages.indepth.svg
token: ${{ secrets.METRICS_TOKEN }}
base: ""
plugin_languages: yes
plugin_languages_ignored: >-
html, css, tex, less, dockerfile, makefile, qmake, lex, cmake, shell,
gnuplot
plugin_languages_indepth: yes
plugin_languages_details: lines, bytes-size
plugin_languages_limit: 4
plugin_languages_analysis_timeout: 15
```
