Skip to content

[codex] Document ignored blame revisions for code experts #857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vim-zz merged 1 commit into from
May 27, 2026
+17 −1
Merged

[codex] Document ignored blame revisions for code experts #857

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/automation-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,8 @@ is:

This action, shall add a comment with codeExperts suggestion. If the comment already exists, the comment shall be edited.

The underlying blame-based expertise calculation respects a repository-level `.git-blame-ignore-revs` file. Use this Git file to keep formatting-only commits or mechanical migrations from dominating code expert attribution.

<div class="filter-details" markdown=1>

| Args | Usage | Type | Description |
Expand Down Expand Up @@ -582,10 +584,12 @@ automations:

For more information about the `codeExperts` filter function, see the [filter functions documentation](https://docs.gitstream.cm/filter-functions/#codeexperts).

!!! tip "Limit git history for code experts"
!!! tip "Control code expert attribution"

Use the [`config.git_history_since`](./cm-file.md#configgit_history_since) configuration to limit the git history analysis to commits after a specific date. This is useful for team transitions or when you want to focus on recent contributors only.

Use `.git-blame-ignore-revs` when you need to exclude specific commits from blame attribution. This is different from [`config.ignore_files`](./cm-file.md#configignore_files), which excludes whole files from automation processing.

#### `merge` :fontawesome-brands-github: :fontawesome-brands-gitlab: :fontawesome-brands-bitbucket:

Once triggered, merge the PR if possible. It can be set to wait for all checks to pass or only required ones.
Expand Down
2 changes: 2 additions & 0 deletions docs/automations/standard/explain-code-experts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ quickstart: true

Post a comment that uses git blame and history to list the most relevant experts for all PRs. The comment will automatically update as additional commits are added to the PR.

If your repository has formatting-only commits or mechanical migrations that should not count toward expertise, list those commit SHAs in `.git-blame-ignore-revs`. The blame-based calculation used by this automation excludes those revisions from code expert attribution.

<div class="automationImage" markdown="1">
![Explain Code Experts](explain-code-experts.png)
</div>
Expand Down
10 changes: 10 additions & 0 deletions docs/filter-functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,12 @@ The output lists the Git provider users, e.g., GitHub users, which are mapped fr

The `codeExperts` filter function calls gitStream app API with the `repo` context to calculate the experts.

!!! note "Ignored blame revisions"

`codeExperts` respects a repository-level `.git-blame-ignore-revs` file when calculating blame-based expertise. Use this Git file to exclude specific commits, such as formatting-only commits or mechanical migrations, from blame attribution.

This is different from [`config.git_history_since`](./cm-file.md#configgit_history_since), which limits history analysis by date, and [`config.ignore_files`](./cm-file.md#configignore_files), which excludes whole files from automation processing.

<div class="filter-details" markdown=1>

| Argument | Usage | Type | Description |
Expand Down Expand Up @@ -806,6 +812,8 @@ This filter helps to explain the results of [`rankByGitBlame`](#rankbygitblame),

The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the `git-blame` output. Git users that could not be automatically mapped are marked with `*`. To map these users, you can add `user_mapping` see instructions [here](/cm-file#config).

`explainRankByGitBlame` respects a repository-level `.git-blame-ignore-revs` file. Commits listed there are excluded from blame attribution before contributor percentages are calculated.

<div class="filter-details" markdown=1>

| Argument | Usage | Type | Description |
Expand Down Expand Up @@ -978,6 +986,8 @@ contributors' percentage of lines in the file, based on `git-blame`.

This function sums all these percentages per user and yield an average percentage of contribution. Then you can use the thresholds to get the right reviewer.

`rankByGitBlame` respects a repository-level `.git-blame-ignore-revs` file. Commits listed there are excluded from blame attribution before contributor percentages are calculated.

The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the `git-blame` output. When gitStream cannot map the Git user to a Git provider user it will be dropped from the output list, hence the list may contain less than 100% of the lines.

<div class="filter-details" markdown=1>
Expand Down