feat: add .gtrconfig file for declarative configuration #38
Conversation
- Introduced .gtrconfig file for team-shared settings, allowing configuration to be stored alongside git config. - Updated configuration precedence to include .gtrconfig, detailing the order of settings resolution. - Enhanced functions to retrieve configuration values from both git config and .gtrconfig. - Added example .gtrconfig file template for user reference.
WalkthroughAdds repository-level configuration via an optional Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (1)📚 Learning: 2025-11-24T19:17:34.750ZApplied to files:
🪛 LanguageToolCLAUDE.md[uncategorized] ~577-~577: The official name of this software platform is spelled with a capital “H”. (GITHUB) 🔇 Additional comments (4)
Comment |
- Revised descriptions of binary structure and command flow for improved understanding. - Clarified function names and their roles in the codebase. - Enhanced documentation on configuration management and adapter loading processes. - Added a new section outlining the documentation structure for better navigation.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
CLAUDE.md (1)
479-482: Stale description ofcfg_default/cfg_get_allbehaviorThis paragraph still says
cfg_defaultchecks only git config (local > global > system) then env, and references old line ranges forcfg_get_all. After introducing.gtrconfiginto precedence and changing signatures, this description is now inaccurate.Recommend updating it to:
- Mention
.gtrconfigbetween local and global/system.- Reflect the new
cfg_get_all key [file_key] [scope]andcfg_default key env fallback [file_key]signatures.- Drop hardcoded line numbers or refresh them.
This keeps CLAUDE’s internal model aligned with the current implementation.
bin/gtr (1)
897-904:cmd_config getpasses scope to wrong parameter incfg_get_allcall
cfg_get_allexpects(key, file_key, scope), but line 903 calls:cfg_get_all "$key" "$scope"This passes
scopeasfile_key(second position), leavingscopedefaulted to"auto". The--globaland--localflags are ignored, and the function attempts to read a non-existent.gtrconfigkey matching the scope string.Fix:
- cfg_get_all "$key" "$scope" + cfg_get_all "$key" "" "$scope"The empty string for
file_keyis correct here sinceconfig getqueries git config only, not.gtrconfigfile entries.
🧹 Nitpick comments (1)
README.md (1)
243-280: Configuration precedence docs slightly out of sync with implementationThe README precedence list stops at global → env → defaults, but
lib/config.shand CLAUDE.md document and implement an additionalgit config --systemlayer between global and env. Consider updating this section to mention the system scope so docs fully mirror actual behavior.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (6)
CLAUDE.md(3 hunks)README.md(2 hunks)bin/gtr(6 hunks)lib/config.sh(4 hunks)lib/hooks.sh(1 hunks)templates/.gtrconfig.example(1 hunks)
🧰 Additional context used
📓 Path-based instructions (8)
bin/gtr
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
bin/gtr: Dispatch commands throughcmd_*functions inbin/gtr(case block lines 36‑77)
UpdateGTR_VERSIONon line 8 ofbin/gtrwhen releasing; this affectsgtr version/--versionoutputGlobal
set -einbin/gtr: guard non-critical commands with|| true
list --porcelainoutput must remain stable for scripting purposesUpdate the version constant (line 8: GTR_VERSION="2.0.0") when releasing a new version
Files:
bin/gtr
{bin/gtr,lib/**/*.sh,adapters/**/*.sh}
📄 CodeRabbit inference engine (.github/instructions/testing.instructions.md)
{bin/gtr,lib/**/*.sh,adapters/**/*.sh}: All commands must exit 0 (except intentional failures) and produce expected side-effects
No unquoted path errors; spaces must be handled in file paths
Hooks must run only once per creation/removal event
Files:
bin/gtrlib/hooks.shlib/config.sh
lib/**/*.sh
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
lib/**/*.sh: Core libraries (lib/core.sh,lib/config.sh,lib/ui.sh,lib/copy.sh,lib/hooks.sh,lib/platform.sh) must be sourced at startup and implement specific functionality
Maintain backwards compatibility with Git <2.22 by using fallbackrev-parse --abbrev-ref HEADinstead ofbranch --show-current
lib/**/*.sh: Maintain backwards compatibility with existing configs in shell scripts
Quote all paths to support spaces in directory names
Uselog_error/log_infofromlib/ui.shfor user messages
Implement Git version fallbacks (e.g., Git 2.22+--show-currentvs olderrev-parse); checklib/core.sh:97-100for example
Add new config keys withgtr.<name>prefix to avoid collisions
For performance-sensitive loops (e.g., directory scans), prefer built-ins (find,grep) with minimal subshells
For any new Git command, add fallback for older versions or guard with detection
Files:
lib/hooks.shlib/config.sh
**/*.sh
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
**/*.sh: Always quote paths to handle spaces and special characters; avoid unguarded globbing
Keepset -eactive in shell scripts; ensure non-critical failures are guarded withcommand || true
**/*.sh: Use shebang#!/usr/bin/env bash(not/bin/bashor/bin/sh) for all shell scripts
Usesnake_casenaming for functions and local variables,UPPER_CASEfor constants and environment variables
Use 2-space indentation (no tabs) for all shell scripts
Always quote all variables and paths (e.g.,"$var") in shell scripts
Check return codes and use|| exit 1or|| return 1for error handling in shell scripts
Files:
lib/hooks.shlib/config.sh
**/*.{bash,fish,sh}
📄 CodeRabbit inference engine (.github/instructions/sh.instructions.md)
**/*.{bash,fish,sh}: Bash 3.2+ compatible (macOS default), but 4.0+ features allowed where appropriate
Always quote variables: use"$var"not$var
Use function-scoped variables:local var="value"
Check return codes; functions return 1 on failure
Usesnake_casefor functions and variables,UPPER_CASEfor constants
Prefer[ ]over[[ ]]for POSIX portability; use[[only when needed
Always quote glob inputs; disable unintended globbing withset -ftemporarily if required
Avoid associative arrays in shell scripts; use simple string/loop constructs for Bash 3.2+ compatibility
Avoidreadarrayand process substitution unsupported in older Bash
Debug withbash -x ./bin/gtr <cmd>or wrap suspicious blocks withset -x/set +x
Check function presence withdeclare -f create_worktreeordeclare -f resolve_target
Use stderr for variable inspection:echo "DEBUG var=$var" >&2to keep stdout clean for command substitution
Keep dependencies minimal: only usegit,sed,awk,find,grep; avoid jq/curl unless justified
Check availability of external commands before use when adding new tools
Use"${var}"for variable expansion; for line loops usewhile IFS= read -r line; do ... doneto preserve spaces
Sanitize branch names viasanitize_branch_namefunction; do NOT duplicate logic elsewhere
Everything is sourced at startup withset -eenabled; functions call each other directly; no subshells except for hooks and AI tools
Files:
lib/hooks.shlib/config.sh
lib/*.sh
📄 CodeRabbit inference engine (CLAUDE.md)
lib/*.sh: Maintain backwards compatibility with existing configurations when modifying core functionality files
Follow POSIX-compatible Bash patterns targeting Bash 3.2+ in core library files
Uselocalfor function-scoped variables in library files to prevent variable scope leakage
Provide clear error messages vialog_errorandlog_infofromlib/ui.shin library files
Files:
lib/hooks.shlib/config.sh
lib/config.sh
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
For multi-value git config keys, use
git config --addto merge and deduplicate values rather than overwriting the entire list
Files:
lib/config.sh
README.md
📄 CodeRabbit inference engine (CLAUDE.md)
Always reference
git gtrin user-facing documentation (not./bin/gtr), which is for development/testing only
Files:
README.md
🧬 Code graph analysis (1)
lib/hooks.sh (1)
lib/config.sh (1)
cfg_get_all(85-113)
🔇 Additional comments (8)
lib/hooks.sh (1)
11-14: Hook lookup correctly extended to .gtrconfigUsing
cfg_get_all "gtr.hook.$phase" "hooks.$phase"cleanly merges git config and.gtrconfighook entries while preserving existing behavior and precedence. No issues spotted.bin/gtr (2)
241-275: Copy pattern config now correctly sources from.gtrconfigThe updated
cfg_get_allcalls forgtr.copy.*keys withcopy.*file keys correctly merge git config and.gtrconfigvalues, preserving newline-separated lists and deduplication. This fits the documented precedence and keeps behavior backward compatible.
500-503: Editor/AI defaults correctly wired to.gtrconfig
cfg_default gtr.editor.default ... defaults.editorandcfg_default gtr.ai.default ... defaults.aicorrectly hook up repository-level[defaults]settings in.gtrconfigwhile still honoring local/global git config, env, and fallbacks. The same pattern incmd_doctorkeeps diagnostics in sync.Also applies to: 564-567, 755-758, 775-778
templates/.gtrconfig.example (1)
1-55: Example.gtrconfigaligns with implementation and key mappingThe example cleanly matches the documented mappings (
copy.*,hooks.*,defaults.*) and will be correctly picked up bycfg_get_all_file/cfg_get_file. Duplicate[copy]sections are valid gitconfig and aggregate as expected.README.md (1)
335-343: AI tools table refactor improves clarityThe new table layout (Tool / Install / Use Case / Set as Default) is consistent and makes configuring
gtr.ai.defaultmuch clearer. No issues.CLAUDE.md (1)
224-225: CLAUDE guidance correctly documents new.gtrconfigmodelThe updated sections on configuration storage, precedence, file-based configuration, and the
.gtrconfigkey mapping table align with the newcfg_default/cfg_get_allbehavior and key usage inlib/config.shandbin/gtr. This is very helpful for future changes.Also applies to: 405-447
lib/config.sh (2)
2-59:.gtrconfighelpers and file readers are robust andset -e–safe
_gtrconfig_path,cfg_get_file, andcfg_get_all_fileare implemented defensively: git lookups are guarded (2>/dev/nullwith|| return 0/|| true), paths are quoted, and they gracefully no-op outside a repo. The comment and behavior around--git-common-dirvs--show-toplevelmake the intended “main repo root” semantics clear for worktrees.
80-113: Config precedence implementation matches documented modelThe updated
cfg_get_allandcfg_defaultcorrectly implement:
- Merge & dedupe order for multi-valued keys: local →
.gtrconfig(viafile_key) → global → system.- Scalar precedence for defaults: local →
.gtrconfig(iffile_keyprovided) → global/system → env (env_name) → fallback.Signatures and behavior are consistent with README/CLAUDE docs and with how callers in
bin/gtr/lib/hooks.shusefile_key.Also applies to: 189-220
…E.md - Clarified the order of configuration precedence, explicitly mentioning the .gtrconfig file. - Updated README to include system defaults in the configuration hierarchy. - Adjusted function call in gtr script to align with updated configuration retrieval logic.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CLAUDE.md (1)
405-447: Remove or mark as planned the unimplemented configuration keys from the Git Config Keys section and Key Mapping Table.The documented configuration keys (lines 420-446) claim support for
gtr.editor.default,gtr.ai.default, and thegtr.copy.*keys, but these are not implemented in the codebase. Onlygtr.defaultBranch,gtr.hook.postCreate, andgtr.hook.postRemoveare actually retrieved and used via the configuration functions. The copy functionality does not retrieve these keys throughcfg_get_all, and editor/AI defaults are not retrieved anywhere in the code. Either remove these keys from the documentation or mark them as planned/future features. The Key Mapping Table should be updated to reflect only the currently implemented configuration keys.
🧹 Nitpick comments (2)
CLAUDE.md (2)
432-433: Clarify .worktreeinclude deprecation timeline and migration path.Line 433 marks
.worktreeincludeas deprecated in favor of.gtrconfig, but doesn't specify:
- When deprecation will take effect (v2.1.0, v3.0.0?)
- Whether it will still be supported (and in what precedence order)
- Migration guidance for users currently relying on
.worktreeincludeConsider adding a deprecation timeline and migration instructions to help users transition smoothly.
561-576: Ensure documentation structure section is discoverable and kept in sync.The new Documentation Structure section (lines 561-576) provides valuable navigation guidance for different documentation files and their purposes. Consider:
- Adding a similar navigation section to README.md or CONTRIBUTING.md so new contributors discover it
- Adding inline comments in each instruction file cross-referencing the others
- Setting up a periodic check (e.g., in CI or PR review checklists) to keep file references in sync as documentation evolves
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (3)
CLAUDE.md(8 hunks)README.md(2 hunks)bin/gtr(7 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- bin/gtr
- README.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-11-24T19:17:34.750Z
Learnt from: CR
Repo: coderabbitai/git-worktree-runner PR: 0
File: .github/instructions/lib.instructions.md:0-0
Timestamp: 2025-11-24T19:17:34.750Z
Learning: Applies to lib/**/*.sh : Implement Git version fallbacks (e.g., Git 2.22+ `--show-current` vs older `rev-parse`); check `lib/core.sh:97-100` for example
Applied to files:
CLAUDE.md
🪛 LanguageTool
CLAUDE.md
[uncategorized] ~577-~577: The official name of this software platform is spelled with a capital “H”.
Context: ...on specific areas, consult the relevant .github/instructions/*.md file for detailed gu...
(GITHUB)
- Removed mention of deprecation for .worktreeinclude, clarifying its integration with gtr.copy.include.
Pull Request
Description
Motivation
Fixes # (issue)
Type of Change
Testing
Manual Testing Checklist
Tested on:
Core functionality tested:
git gtr new <branch>- Create worktreegit gtr go <branch>- Navigate to worktreegit gtr editor <branch>- Open in editor (if applicable)git gtr ai <branch>- Start AI tool (if applicable)git gtr rm <branch>- Remove worktreegit gtr list- List worktreesgit gtr config- Configuration commands (if applicable)Test Steps
Expected behavior:
Actual behavior:
Breaking Changes
Checklist
Before submitting this PR, please check:
git gtr(production) and./bin/gtr(development)Additional Context
License Acknowledgment
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache License 2.0.
Summary by CodeRabbit
New Features
Bug Fixes / Behavior
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.