How Commit-Scoped Comments and Visibility Filtering Work in tuicr

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. Each comment instance stores an optional commit_id field that holds the SHA of the commit it belongs to.

// 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, 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.

// 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 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 within a helper method (conventionally named comment_visible). This function determines whether a comment should appear in the current view.

// 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, 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:

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:

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:

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 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, 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}