docs: apply intent-driven progressive disclosure principles#25
Merged
Conversation
When 'git hop clone' or 'git hop add' creates a new branch, configure it to track the remote default branch (e.g., origin/main). This fixes first push failures due to missing upstream configuration. Changes: - Add trackBranch parameter to git.CreateWorktree - Pass origin/<defaultBranch> when creating branches in add, fork, clone, and doctor repair flows - Add regression tests for --track flag behavior
Restructure README and configuration guide to lead with reader intent
and reveal information in layers:
README changes:
- Lead with pain point ("work on multiple branches in parallel...")
instead of feature list
- Move Architecture section to "Advanced: How It Works" at end
- Add verification steps to all workflows
- Reorder: Intent → Quickstart → Commands → Workflows → Config →
Troubleshooting → Advanced
Configuration.md changes:
- Add Quick Start TL;DR upfront ("you only edit global.json")
- Reorder settings table BEFORE full JSON schema (reference, not primary)
- Add "Don't edit" warnings at top of auto-managed file sections
- Reframe Configuration Hierarchy as task: "Override Settings for
Specific Situations" with concrete examples
- Move directory structure to reference section (still available,
non-blocking)
Follow principles from intent-driven progressive disclosure:
- Start with reader's goal (Do, Learn, Fix, Decide, Reference)
- Essential context before steps
- Verification after actions
- Advanced details below main path
- One primary intent per section
There was a problem hiding this comment.
Pull request overview
This PR primarily refactors documentation to follow intent-driven progressive disclosure, and additionally updates git worktree creation to optionally set upstream tracking when creating new branches.
Changes:
- Restructure
README.mdanddocs/configuration.mdflow (intent → quickstart → workflows → advanced), adding “Verify” steps and new warnings. - Extend
GitInterface.CreateWorktree(and callers) with atrackBranchparameter and thread it through worktree creation paths. - Add git wrapper tests covering inclusion/omission of
--track.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| test/mocks/mock_git.go | Updates mock signature for CreateWorktree to include tracking param. |
| internal/hop/worktree_transactional_test.go | Updates tests for new CreateWorktreeTransactional signature. |
| internal/hop/worktree.go | Threads defaultBranch into worktree creation and derives trackBranch. |
| internal/hop/fork.go | Passes default branch through to worktree creation in fork attach. |
| internal/hop/conversion.go | Adds tracking argument to conversion-time worktree creation. |
| internal/hop/clone_worktree.go | Adds tracking argument when creating the main worktree. |
| internal/git/wrapper_test.go | Updates call sites and adds tests for --track behavior. |
| internal/git/wrapper.go | Extends CreateWorktree API and appends --track when creating branches. |
| docs/configuration.md | Reorders and reframes configuration docs with quick-start and warnings. |
| cmd/doctor.go | Uses trackBranch when recreating worktrees. |
| cmd/add.go | Passes default branch into transactional worktree creation. |
| README.md | Reorders sections, adds verify steps, and adds new config guidance. |
| LICENSE | Updates copyright year/holder lines. |
Comments suppressed due to low confidence (1)
internal/git/wrapper.go:158
- When
forceCreateis true,trackBranchis ignored entirely. IftrackBranchis a supported part of the API, it should be applied consistently to both the forced-create path and the fallback create path (or the parameter should be removed/renamed to reflect that it only applies to one codepath).
if forceCreate {
// Force create a new branch
args = append(args, "-b", branch, path)
if base != "" {
args = append(args, base)
}
} else {
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
227
to
+236
|
|
||
| ## Configuration | ||
|
|
||
| For detailed configuration, see [Configuration Guide](docs/configuration.md). | ||
|
|
||
| Quick setup: | ||
|
|
||
| ```bash | ||
| git hop config --help # View all settings | ||
| git hop config port_base 20000 # Change port base |
Comment on lines
145
to
152
| // baseWorktreePath is already absolute after resolution by ResolveWorktreePath | ||
| // CreateWorktree will automatically try to link existing branch first, then create if needed | ||
| if err := m.git.CreateWorktree(baseWorktreePath, branch, worktreePath, "HEAD", false); err != nil { | ||
| trackBranch := "" | ||
| if defaultBranch != "" { | ||
| trackBranch = "origin/" + defaultBranch | ||
| } | ||
| if err := m.git.CreateWorktree(baseWorktreePath, branch, worktreePath, "HEAD", false, trackBranch); err != nil { | ||
| return "", fmt.Errorf("failed to create worktree: %w", err) |
Comment on lines
+175
to
+176
| // Verify the create command includes --track flag | ||
| assert.Contains(t, runner.lastCommand, "worktree add -b main /path/to/worktree --track origin/main HEAD") |
Comment on lines
145
to
151
| // CreateWorktree creates a new worktree. | ||
| // If the branch exists and forceCreate is false, it links the existing branch. | ||
| // If the branch doesn't exist or forceCreate is true, it creates a new branch from base (or HEAD if base is empty). | ||
| func (g *Git) CreateWorktree(hopspacePath, branch, path, base string, forceCreate bool) error { | ||
| // If trackBranch is specified, the new branch will track it (e.g., "origin/main"). | ||
| func (g *Git) CreateWorktree(hopspacePath, branch, path, base string, forceCreate bool, trackBranch string) error { | ||
| args := []string{"worktree", "add"} | ||
|
|
Comment on lines
171
to
+174
| args = []string{"worktree", "add", "-b", branch, path} | ||
| if trackBranch != "" { | ||
| args = append(args, "--track", trackBranch) | ||
| } |
| // CreateWorktree will automatically try to link existing branch first, then create if needed | ||
| if err := m.git.CreateWorktree(baseWorktreePath, branch, worktreePath, "HEAD", false); err != nil { | ||
| trackBranch := "" | ||
| if defaultBranch != "" { |
Comment on lines
+7
to
+19
| **TL;DR:** You only edit `global.json`. Everything else is managed automatically. | ||
|
|
||
| ```bash | ||
| # View your settings | ||
| git hop config | ||
|
|
||
| # Change a setting | ||
| git hop config port_base 20000 | ||
|
|
||
| # See where settings come from | ||
| git hop config --verbose | ||
| ``` | ||
|
|
Comment on lines
+457
to
+472
| ## Override Settings for Specific Situations | ||
|
|
||
| Settings follow a hierarchy — git-hop uses the first one it finds: | ||
|
|
||
| When git-hop needs a setting, it searches in this order (first found wins): | ||
| 1. **Environment variables** — for one command | ||
| 2. **Hub config** (`<hub>/hop.json`) — for one workspace | ||
| 3. **Hopspace config** (`$GIT_HOP_DATA_HOME/<org>/<repo>/hop.json`) — for one repository | ||
| 4. **Global config** (`~/.config/git-hop/global.json`) — for all repositories | ||
| 5. **Built-in defaults** — fallback | ||
|
|
||
| 1. Environment variables | ||
| 2. Hub-level config (`<hub>/hop.json`) | ||
| 3. Hopspace-level config (`$GIT_HOP_DATA_HOME/<org>/<repo>/hop.json`) | ||
| 4. Global config (`$XDG_CONFIG_HOME/git-hop/global.json`) | ||
| 5. Built-in defaults | ||
| **Example:** Change port base for one repo only (don't affect others): | ||
|
|
||
| This allows you to: | ||
| - Set global defaults for all repositories | ||
| - Override for specific repositories (hopspace) | ||
| - Override for specific hubs (workspace-specific) | ||
| - Override for individual commands (environment variables) | ||
| ```bash | ||
| # Edit ~/.local/share/git-hop/github.com/org/repo/hop.json | ||
| # Add this to the JSON: "portBase": 20000 | ||
| ``` |
|
|
||
| To auto-start services on worktree creation: | ||
| ```bash | ||
| git hop config auto_env_start detect |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructured README and configuration documentation to lead with reader intent and reveal information in layers, following intent-driven progressive disclosure principles.
README changes:
Configuration.md changes:
Test Plan
git hopbehaviorDocumentation
Review documents:
docs/REVIEW_INTENT_DRIVEN_DISCLOSURE.md— detailed analysis against 30 principlesdocs/REFACTOR_SUMMARY.md— before/after comparison