Skip to content

Search and edit code repositories with git-rg

Use the git-rg Skill and command-line tool to find or change remote code. It reads immutable revisions and previews complete diffs without cloning repository history, then creates a new branch and Draft PR/MR through platform APIs after explicit authorization.

Enable the git-rg Skill and include the repository URL, branch, and search target in your task. For example:

Use git-rg to find request-timeout settings on the main branch of https://gitlab.example.com/team/service.git. List file paths, line numbers, and relevant code.

In obscli, enter $ to select the git-rg Skill, then send the task. Public repositories can usually be read anonymously; private repositories require repository credentials available to the Agent.

To provide a Token only to the current session, use private session credentials with the name GITRG_TOKEN. Container environment changes or persistent CLI logins are unnecessary. The credential expires when the session closes or the Agent restarts.

Ask the Agent to edit remote code

From v0.5.0, git-rg supports Agent-prepared changes and Draft PR/MR creation. Writes are disabled by default and publication uses GITRG_WRITE_TOKEN; GITRG_TOKEN cannot replace the publication credential. Setting a write Token does not trigger a write: each publication still requires --enable-write. From v0.6.0, a write Token alone also supports reads and previews; when both Tokens are supplied, reads prefer GITRG_TOKEN.

Specify the repository, target branch, requested changes, validation requirements, and whether Draft PR/MR publication is authorized. For example:

Use git-rg to read the main branch of gitlab:team/service and fix request-timeout handling. Prepare a change plan and run dry-run first. Show the diff and any checks that cannot run locally. Once there are no conflicts, use the current session's GITRG_WRITE_TOKEN to create a new branch and Draft MR. Do not merge it.

Add GITRG_WRITE_TOKEN to the session in the same way as a read Token. Bind it to one repository and a dedicated identity. See Add git-rg Tokens for creation steps and minimum permissions. Never place Tokens in chat, change plans, command arguments, or repository files.

The Agent should follow these steps:

  1. Read the complete file with env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN git-rg read --auth env --ref TARGET REPOSITORY PATH, recording the returned commit SHA and blob SHA. Pin subsequent reads to that commit.
  2. Create a JSON change plan. Updates and deletions require the original expected_blob; content contains the complete replacement file, not a patch fragment.
  3. Clear provider Tokens in the same way and run git-rg propose --dry-run --auth env --changes changes.json REPOSITORY. Check the immutable baseline, file conflicts, and complete diff. dry-run never writes remotely, but from v0.6.0 it can read using GITRG_WRITE_TOKEN if GITRG_TOKEN is missing.
  4. Run git-rg propose --enable-write --changes changes.json REPOSITORY only when publication is authorized. Check proposal.result.complete=true, the new branch, commit, and Draft PR/MR URL together.
  5. Report compilation, tests, and CI separately. complete=true confirms the remote commit and Draft PR/MR are complete; it does not mean the code is validated or ready to merge.

These examples show command syntax. Actual SHAs and complete file contents must come from the same immutable read:

env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg read --auth env --ref main gitlab:team/service path/to/file.go
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg propose --dry-run --auth env --changes changes.json gitlab:team/service
git-rg propose --enable-write --changes changes.json gitlab:team/service

Changed target branches return base_changed; changed files return blob_conflict. Read a new snapshot and regenerate the plan. An existing source branch with unrelated content returns branch_conflict and is not overwritten. After a publication timeout, retry with exactly the same plan, repository, and Agent identity so the tool can check and recover remote state. Do not change the branch or create a duplicate MR.

The first implementation supports only new branches in the same repository and ordinary UTF-8 text files. It does not update existing branches, create fork PRs, modify binaries, symlinks, or submodules, merge automatically, or run repository tests. Use CI or a separate code-execution environment for testing.

Use private session credentials

Agent hosts and containers do not install or depend on gh or glab, and no platform login is required on the node. Reads and previews explicitly use --auth env. All authenticated git-rg operations read Tokens only from the current session's private credential environment. Closing the session, restarting the Agent, or disconnecting revokes the credentials; other sessions do not inherit them.

Read commands must also clear GITHUB_TOKEN, GH_TOKEN, and GITLAB_TOKEN in their subprocess to avoid provider Tokens inherited by the Agent process. For genuinely anonymous public-repository access, also clear GITRG_TOKEN and GITRG_WRITE_TOKEN there. Omitting only the read Token does not guarantee anonymity.

Search, refs, read, and dry-run prefer GITRG_TOKEN. After clearing provider Tokens, v0.6.0 or later falls back to GITRG_WRITE_TOKEN only when the read Token is absent; v0.5.0 has no fallback. A Token rejected by the platform does not trigger an identity-switch retry. For read-only tasks, prefer a separate low-permission Token: a project-scoped GitLab project access token with the Reporter role and read_api scope, or a repository-scoped GitHub fine-grained Token with Contents: read. Public repositories support anonymous reads, but commands still use --auth env to avoid node-login fallback.

Creating a Draft PR/MR uses only GITRG_WRITE_TOKEN for validation reads and writes, without falling back to a read Token. For GitHub, limit the fine-grained Token to the target repository with Contents: read and write and Pull requests: read and write; add Workflows: read and write only if changes actually affect .github/workflows/. For GitLab, use a project access token with Developer and api to create an unprotected source branch and Draft MR; write_repository cannot replace the REST API api scope. From v0.6.0, a write Token with both read and publication permissions can handle the whole editing workflow. Prefer low-permission read Tokens for ordinary read-only tasks. Never put Tokens in chat, repository URLs, change plans, or repository files.

Enter /credentials in the current obscli chat and add GITRG_TOKEN, GITRG_WRITE_TOKEN, or both as needed. The Agent sees names and types only; the runtime injects actual values into executing commands. See Add git-rg Tokens.

Minimal command examples

Run these commands in the Agent environment and replace the repository and branch. Put all options before the search text and repository URL.

# List branches and tags of a self-managed GitLab repository.
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg refs --auth env --provider gitlab https://gitlab.example.com/team/service.git

# Search a literal on a branch, showing files, lines, and two context lines.
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg --auth env --provider gitlab --ref main --format text -F -C 2 \
  'request_timeout' https://gitlab.example.com/team/service.git

# Search Go files in a GitHub repository.
env -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN \
  git-rg --auth env --ref main --glob '*.go' --format text -F \
  'request_timeout' github:OWNER/REPO

Keep --auth env in every read command. To confirm complete search results, use the default NDJSON output and check the final summary.complete. When a result limit is reached or only an index is searched, no matches do not prove the repository has no matching content.

For private-repository access failures, check the current session's GITRG_TOKEN, host, and read permissions. Do not log in on the Agent node or switch to persistent environment variables. Self-managed GitLab needs --provider gitlab; SSH-style repository URLs do not imply SSH-key authentication support.

See the git-rg documentation for complete options.