# How Commit-Scoped Comments and Visibility Filtering Work in tuicr

> Discover how commit-scoped comments and visibility filtering in tuicr help code reviewers focus on specific commits and streamline feedback. Learn to use these powerful features today.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: deep-dive
- Published: 2026-08-07

---

**Commit-scoped comments in tuicr are automatically hidden or shown based on the active commit selection, allowing reviewers to focus on specific commits without distraction.**

tuicr is a terminal-based code review tool that supports inline comments on diffs. When you use the inline commit selector to focus on exactly one commit, comments become scoped to that commit's SHA and filter dynamically as you navigate through the history.

## How Commit-Scoped Comments Work in tuicr

tuicr attaches metadata to each comment to track its associated commit. This scoping mechanism ensures that commentary remains relevant to the specific changes under review.

### The Comment Struct and commit_id Field

The foundation of this feature lies in the `Comment` struct defined in [`src/model/comment.rs`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs). Each comment instance stores an optional `commit_id` field that holds the SHA of the commit it belongs to.

```rust
// src/model/comment.rs (lines 86-94)
pub struct Comment {
    pub content: String,
    pub comment_type: CommentType,
    pub side: Option<LineSide>,
    pub commit_id: Option<String>,  // None for unscoped, Some(sha) for scoped
}

```

When `commit_id` is `None`, the comment is considered unscoped and remains visible regardless of commit selection. When populated with a SHA string, the comment binds to that specific commit.

### Saving Scoped Comments with App::save_comment

The scoping logic triggers during comment creation. In [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs), the `App::save_comment` method detects whether the inline commit selector displays exactly one commit. If so, it invokes the `Comment::with_commit_id` builder to attach the commit SHA.

```rust
// Inside App::save_comment (src/app/mod.rs)
if let Some(single_commit) = self.commit_selector.single_commit() {
    // Scope the comment to the single selected commit
    let comment = Comment::new(content, comment_type, side)
        .with_commit_id(single_commit.sha);
    self.add_comment_to_session(comment);
}

```

The `with_commit_id` method (defined in [`src/model/comment.rs`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs) at lines 46-53) returns a new `Comment` instance with the `commit_id` field populated, ensuring the annotation persists its scope across sessions.

## Visibility Filtering Implementation

Once comments carry scope metadata, tuicr filters them dynamically based on the user's current commit selection.

### The comment_visible Helper Method

The visibility logic resides in [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs) within a helper method (conventionally named `comment_visible`). This function determines whether a comment should appear in the current view.

```rust
// src/app/mod.rs - comment_visible logic
fn comment_visible(&self, comment: &Comment) -> bool {
    match &comment.commit_id {
        // Unscoped comments are always visible
        None => true,
        // Scoped comments visible only if SHA is in current selection
        Some(sha) => self.commit_selector.contains_commit(sha),
    }
}

```

When the user changes the commit selector—switching to a different commit or expanding to a range—the `contains_commit` check updates accordingly. Comments whose `commit_id` no longer intersects with the active selection return `false` and disappear from the interface.

### Rendering and UI Integration

The visibility filter applies across all rendering contexts:

- **Diff view**: Out-of-scope inline comments are omitted from the gutter
- **Comment navigator**: Only visible comments appear in the navigation list
- **Export operations**: Hidden comments are excluded from review submissions

In [`src/ui/comment_panel.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_panel.rs), the UI code respects these filters when rendering existing comments, ensuring the display remains synchronized with the commit selector state.

## Practical Code Examples

### Creating a Commit-Scoped Comment via TUI

When a user presses `i` to add an inline comment while the commit selector shows exactly one commit (e.g., SHA `a1b2c3d`), tuicr executes:

```rust
let comment = Comment::new(
    "Fix typo in variable name".to_string(),
    CommentType::Note,
    Some(LineSide::New),
)
.with_commit_id("a1b2c3d");

// The comment is stored with its commit_id and will disappear 
// if the selector switches away from `a1b2c3d`
app.add_comment_to_session(comment);

```

### Manual Construction Using the Library API

For programmatic usage, construct scoped comments directly using the model API:

```rust
use tuicr::model::comment::{Comment, CommentType, LineSide};

// Build a comment scoped to a specific commit SHA
let scoped = Comment::new(
    "Refactor loop logic".into(),
    CommentType::Suggestion,
    Some(LineSide::New),
)
.with_commit_id("deadbeef");

// Insert via the ReviewStore API
review_store.add_comment(session_slug, file_path, scoped)?;

```

### Implementing Custom Filtering Logic

To replicate tuicr's visibility behavior in external tools:

```rust
use std::collections::HashSet;
use tuicr::model::comment::Comment;

fn is_comment_visible(active_commits: &HashSet<String>, comment: &Comment) -> bool {
    match &comment.commit_id {
        None => true, // Always visible
        Some(sha) => active_commits.contains(sha),
    }
}

```

## Summary

- **Automatic Scoping**: When the inline commit selector shows exactly one commit, `App::save_comment` automatically attaches the commit SHA via `Comment::with_commit_id`
- **Dynamic Visibility**: The `comment_visible` helper in [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs) filters comments by checking if their `commit_id` exists in the current selection
- **Backward Compatibility**: Comments with `commit_id: None` (legacy or file-level) remain visible under all commit selections
- **Forge Integration**: When submitting reviews via [`src/forge/submit.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/submit.rs), the `commit_id` is included in the payload to maintain scope on remote platforms

## Frequently Asked Questions

### What happens to comments when I switch to a different commit?

Comments scoped to the previous commit automatically hide. The `comment_visible` method returns `false` when the stored `commit_id` SHA no longer matches the active selection, removing the comment from the diff view and navigator until you return to that commit.

### Can I view all comments regardless of commit selection?

Comments with `commit_id == None` are always visible, but scoped comments require you to select their specific commit. To see all comments simultaneously, you would need to expand the commit selector to include all SHAs or clear the filter, causing `contains_commit` to match every scoped comment.

### How does tuicr handle comments from older sessions without commit_id?

Existing sessions that pre-date the `commit_id` field simply store `None` in that field. According to the logic in [`src/model/comment.rs`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs), these unscoped comments pass the visibility filter unconditionally, ensuring backward compatibility with legacy review data.

### Where is the commit scope stored when submitting to a remote forge?

During submission in [`src/forge/submit.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/submit.rs), tuicr includes the `commit_id` field in the review payload. This allows platforms like GitHub or GitLab to associate inline comments with the correct commit SHA, maintaining the scoping context in the remote repository.