AgentSkillsCN

Github Repo Navigation

GitHub 代码仓库导航

SKILL.md

GitHub Repository Navigation

Overview

Repository navigation covers techniques and tools for efficiently finding, understanding, and working with code in GitHub repositories. This skill includes code search, file exploration, understanding repository structure, and using GitHub's navigation features effectively.

When to use this skill: When exploring new repositories, finding specific code, or understanding project structure.

Table of Contents

  1. Repository Structure
  2. Code Search Techniques
  3. File Navigation
  4. Understanding History
  5. Navigation Tools
  6. Navigation Checklist
  7. Quick Reference

Repository Structure

Standard Directory Layout

code
repository/
├── .github/              # GitHub-specific files
│   ├── workflows/        # CI/CD workflows
│   ├── actions/          # Custom actions
│   ├── ISSUE_TEMPLATE/   # Issue templates
│   └── PULL_REQUEST_TEMPLATE/
├── src/                  # Source code
│   ├── api/            # API layer
│   ├── components/      # UI components
│   └── utils/           # Utilities
├── tests/                # Test files
├── docs/                 # Documentation
├── scripts/              # Build/utility scripts
├── config/               # Configuration files
├── public/               # Static assets
├── package.json          # Dependencies
├── README.md             # Project documentation
├── CONTRIBUTING.md       # Contribution guide
└── LICENSE               # License file

Common File Patterns

PatternLocationPurpose
*.config.jsRootConfiguration
*.test.jstests/Unit tests
*.spec.jstests/Spec tests
*.mddocs/Documentation
DockerfileRootContainer config
.env.exampleRootEnvironment template

Monorepo Structure

code
monorepo/
├── packages/
│   ├── package-a/
│   ├── package-b/
│   └── package-c/
├── apps/
│   ├── web/
│   └── mobile/
├── services/
│   ├── api/
│   └── worker/
├── shared/
│   ├── utils/
│   └── types/
└── package.json

Code Search Techniques

GitHub Search Syntax

OperatorDescriptionExample
repo:Search in specific reporepo:owner/repo query
org:Search in organizationorg:orgname query
language:Filter by languagelanguage:javascript query
filename:Search by filenamefilename:package.json
path:Search in pathpath:src/api query
extension:Filter by extensionextension:js query
in:Search locationin:file, in:path, in:comment
user:Filter by useruser:username query

Advanced Search Queries

bash
# Find function definition
repo:owner/repo language:javascript "function authenticate"

# Find TODO comments
repo:owner/repo "TODO" in:file

# Find specific file
repo:owner/repo filename:dockerfile

# Find in specific directory
repo:owner/repo path:src/api "endpoint"

# Find by author
repo:owner/repo user:username "feature"

# Find recent changes
repo:owner/repo "bug" updated:>2024-01-01

# Find in issues
repo:owner/repo "error" in:issue

# Find in PRs
repo:owner/repo "refactor" in:pr

Code Search Best Practices

PracticeDescription
Use specific termsSearch for exact function names
Filter by languageNarrow down results
Use file patternsSearch specific file types
Combine operatorsUse multiple filters
Search pathsLimit to directories
Check datesFind recent changes
Review contextLook at surrounding code

File Navigation

GitHub Web Navigation

code
1. Repository root
   ↓
2. Click on folder
   ↓
3. Browse files
   ↓
4. Click file to view
   ↓
5. Use blame to see history
   ↓
6. Use raw for copy

Keyboard Shortcuts

KeyAction
tActivate file finder
sFocus search bar
wSwitch branch/tag
yCopy file path
bFind file
.Go to repository root
lGo to issues
pGo to pull requests
g pGo to pulse
g aGo to actions

File Operations

bash
# View file raw content
gh api repos/:owner/:repo/contents/:path?ref=main

# Download file
gh api repos/:owner/:repo/contents/:path?ref=main \
  --method GET \
  -H "Accept: application/vnd.github.v3.raw"

# Get file history
gh api repos/:owner/:repo/commits?path=:path

# Get blame information
gh api repos/:owner/:repo/commits?path=:path

Understanding History

Commit History

bash
# View commit history
gh repo view

# View file history
gh api repos/:owner/:repo/commits?path=:path

# View commit details
gh api repos/:owner/:repo/commits/:sha

# Compare commits
gh api repos/:owner/:repo/compare/:base...:head

# View diff
gh pr diff 123

Blame View

bash
# View blame for file
gh blame :path

# View blame for specific line
gh blame :path -L 10

# View blame with date
gh blame :path --date

Branch Navigation

bash
# List all branches
gh repo view --json defaultBranchRef

# List remote branches
gh api repos/:owner/:repo/branches

# Switch branch
gh repo checkout main

# View branch comparison
gh repo compare main...feature-branch

Navigation Tools

GitHub CLI

bash
# Repository overview
gh repo view

# List repositories
gh repo list

# Clone repository
gh repo clone owner/repo

# Fork repository
gh repo fork owner/repo

# Create repository
gh repo create my-repo --public

# View issues
gh issue list

# View pull requests
gh pr list

# View releases
gh release list

VS Code Integration

bash
# Open repository in VS Code
gh repo clone owner/repo && code repo

# Open specific file
gh repo clone owner/repo && code repo --file src/index.js

# Open PR in VS Code
gh pr checkout 123 && code .

Git Navigation

bash
# Navigate to repository
cd path/to/repo

# View git status
git status

# View current branch
git branch

# Switch branch
git checkout branch-name

# View commit log
git log

# View file changes
git diff

# Search commits
git log --grep="search term"

# Search file content
git grep "search term"

Navigation Checklist

Exploring New Repository

markdown
## Repository Exploration Checklist

### Initial Assessment
- [ ] README.md reviewed
- [ ] Project structure understood
- [ ] Main branch identified
- [ ] Contribution guidelines read
- [ ] License reviewed
- [ ] Documentation checked

### Code Navigation
- [ ] Entry point identified
- [ ] Key directories located
- [ ] Configuration files found
- [ ] Test structure understood
- [ ] Dependencies reviewed

### Search Strategy
- [ ] Search terms identified
- [ ] File patterns determined
- [ ] Language filters applied
- [ ] Path filters used
- [ ] Results reviewed

Finding Specific Code

markdown
## Code Search Checklist

### Search Preparation
- [ ] Search terms defined
- [ ] File patterns identified
- [ ] Language specified
- [ ] Repository scoped
- [ ] Date filters applied

### Search Execution
- [ ] Query constructed
- [ ] Filters applied
- [ ] Results reviewed
- [ ] Context examined
- [ ] Multiple sources checked

### Results Analysis
- [ ] Relevant files identified
- [ ] Code patterns understood
- [ ] Related code found
- [ ] Dependencies traced
- [ ] Usage documented

Quick Reference

Search Query Examples

GoalQuery
Find functionrepo:owner/repo "function name"
Find TODOrepo:owner/repo "TODO" in:file
Find configrepo:owner/repo filename:config.js
Find API routesrepo:owner/repo path:src/api "router"
Find testsrepo:owner/repo extension:test.js
Find recent bug fixrepo:owner/repo "bug" updated:>2024-01-01

File Path Patterns

PatternMatches
src/**/*All files in src
**/*.test.jsAll test files
config/*.jsonAll JSON configs
docs/**/*.mdAll markdown docs
*.spec.jsAll spec files

Navigation Commands

bash
# GitHub CLI
gh repo view                    # Repository overview
gh repo list                    # List repositories
gh issue list                   # List issues
gh pr list                      # List PRs
gh blame :path                   # View blame
gh repo checkout main              # Switch branch

# Git
git log --oneline             # Compact history
git log --graph               # Branch graph
git show :sha                 # Show commit
git diff HEAD~1 HEAD         # Show changes
git grep "pattern"            # Search content

Navigation Metrics

MetricTargetHow to Track
Search success rate> 80%Found what looking for
Time to locate code< 5 minAverage search time
Files reviewed per session10-20Productivity metric
Documentation usage> 50%Use docs for navigation
Blame usageRegularlyUnderstand changes

Common Pitfalls

  1. Not reading README - Always start with documentation
  2. Poor search terms - Use specific, relevant keywords
  3. Ignoring filters - Use filters to narrow results
  4. Not exploring structure - Understand project layout first
  5. Relying only on search - Browse directories too
  6. Not using blame - Understand code history
  7. Ignoring docs - Documentation guides navigation
  8. Not using CLI - CLI is faster than web UI

Additional Resources