Initial commit

2025-11-30 09:01:17 +08:00
commit 7f0944bcfe
18 changed files with 8440 additions and 0 deletions
--- a/skills/skill/references/syntax.md
+++ b/skills/skill/references/syntax.md
@@ -0,0 +1,432 @@
+# Special Syntax & Command Quirks
+
+GitHub CLI has several syntax inconsistencies and special cases to be aware of.
+
+## Field Name Inconsistencies
+
+**CRITICAL:** Different commands use different field names for the same data.
+
+### Stars field
+
+| Command | Field Name |
+|---------|-----------|
+| `gh repo view` | `stargazerCount` |
+| `gh search repos` | `stargazersCount` |
+
+**Examples:**
+
+```bash
+# ✅ Correct for gh repo view
+gh repo view anthropics/anthropic-sdk-python --json stargazerCount
+
+# ✅ Correct for gh search repos
+gh search repos "anthropics" --json stargazersCount
+
+# ❌ Wrong - will error
+gh repo view anthropics/anthropic-sdk-python --json stargazersCount
+gh search repos "anthropics" --json stargazerCount
+```
+
+### Forks field
+
+| Command | Field Name |
+|---------|-----------|
+| `gh repo view` | `forkCount` |
+| `gh search repos` | `forksCount` |
+
+**Examples:**
+
+```bash
+# ✅ Correct
+gh repo view owner/repo --json forkCount
+gh search repos "query" --json forksCount
+
+# ❌ Wrong
+gh repo view owner/repo --json forksCount
+gh search repos "query" --json forkCount
+```
+
+### Quick reference table
+
+| Data | `gh repo view` | `gh search repos` |
+|------|----------------|-------------------|
+| Stars | `stargazerCount` | `stargazersCount` |
+| Forks | `forkCount` | `forksCount` |
+| Topics | `repositoryTopics` | `repositoryTopics` |
+| Description | `description` | `description` |
+| URL | `url` | `url` |
+
+## Negative Qualifiers
+
+When using negative search qualifiers (prefixed with `-`), you need special syntax to prevent the shell from interpreting the hyphen as a flag.
+
+### Unix/Linux/Mac
+
+Use `--` to mark the end of flags:
+
+```bash
+# ✅ Correct
+gh search issues -- "bug report -label:wontfix"
+gh search repos -- "typescript -topic:deprecated"
+gh search code -- "TODO -filename:test"
+
+# ❌ Wrong - shell interprets -label as a flag
+gh search issues "bug report -label:wontfix"
+```
+
+### PowerShell
+
+Use `--%` (stop parsing) operator:
+
+```bash
+# ✅ Correct
+gh --% search issues -- "bug report -label:wontfix"
+gh --% search repos -- "rust -archived:true"
+
+# ❌ Wrong
+gh search issues "bug report -label:wontfix"
+```
+
+### Common negative qualifiers
+
+```bash
+# Exclude labels
+gh search issues -- "bug -label:wontfix -label:duplicate"
+
+# Exclude topics
+gh search repos -- "web framework -topic:deprecated"
+
+# Exclude archived repos
+gh search repos -- "stars:>100 -archived:true"
+
+# Exclude specific languages
+gh search code -- "config -language:json"
+
+# Exclude filenames
+gh search code -- "authentication -filename:test -filename:spec"
+```
+
+## Date Format Quirks
+
+### ISO 8601 format required
+
+```bash
+# ✅ Correct
+gh search repos "created:>2024-10-01"
+gh search repos "pushed:<2024-12-31"
+
+# ❌ Wrong
+gh search repos "created:>10/01/2024"  # US format doesn't work
+gh search repos "created:>2024/10/01"  # Slashes don't work
+```
+
+### Date ranges
+
+```bash
+# Between dates
+gh search repos "created:2024-01-01..2024-06-30"
+
+# Relative dates work in some contexts
+gh search repos "pushed:>2024-10-01"  # After October 1st
+
+# Time is optional (defaults to start of day)
+gh search repos "created:>2024-10-01T12:00:00Z"  # With time
+gh search repos "created:>2024-10-01"  # Without time (00:00:00)
+```
+
+## Search Syntax Gotchas
+
+### Spaces in queries
+
+Wrap multi-word queries in quotes:
+
+```bash
+# ✅ Correct
+gh search code "error handling" --language=python
+gh search repos "machine learning" --sort stars
+
+# ❌ Wrong - treats each word as separate argument
+gh search code error handling --language=python
+```
+
+### Boolean operators
+
+GitHub search doesn't support traditional AND/OR/NOT:
+
+```bash
+# ✅ Use qualifiers instead
+gh search repos "topic:react topic:typescript"  # Implicit AND
+gh search issues -- "bug -label:wontfix"  # Implicit NOT
+
+# ❌ Wrong - literal text search
+gh search repos "react AND typescript"
+gh search repos "bug NOT wontfix"
+```
+
+### Wildcards
+
+Limited wildcard support:
+
+```bash
+# ✅ Wildcards work in some contexts
+gh search code "function*" --language=typescript
+gh search repos "react-*" in:name
+
+# ❌ Wildcards don't work everywhere
+gh search repos "created:>2024-*"  # Doesn't work with dates
+```
+
+## JSON Output Quirks
+
+### jq is required for field extraction
+
+```bash
+# ✅ Correct - use jq to extract fields
+gh api repos/owner/repo/contents/file.ts | jq -r '.content'
+
+# ❌ Wrong - raw output is base64 + JSON
+gh api repos/owner/repo/contents/file.ts
+```
+
+### Array handling
+
+```bash
+# ✅ Correct - iterate array
+gh search repos "topic:rust" --json name --jq '.[].name'
+
+# ❌ Wrong - returns raw JSON array
+gh search repos "topic:rust" --json name
+```
+
+### Null handling
+
+```bash
+# ✅ Correct - handle nulls
+gh api repos/owner/repo/contents/path | jq -r '.content // empty'
+
+# ❌ Wrong - errors on null
+gh api repos/owner/repo/contents/path | jq -r '.content'
+```
+
+## API Endpoint Quirks
+
+### Base64 encoding
+
+File contents from the API are base64-encoded:
+
+```bash
+# ✅ Correct - decode with base64 -d
+gh api repos/owner/repo/contents/file.ts | jq -r '.content' | base64 -d
+
+# ❌ Wrong - outputs base64 gibberish
+gh api repos/owner/repo/contents/file.ts | jq -r '.content'
+```
+
+### Recursive tree flag
+
+For recursive directory listings, use query parameter:
+
+```bash
+# ✅ Correct
+gh api repos/owner/repo/git/trees/main?recursive=1
+
+# ❌ Wrong - returns only top level
+gh api repos/owner/repo/git/trees/main
+```
+
+### Ref parameter
+
+Specify branch/tag/commit with `ref`:
+
+```bash
+# ✅ Correct
+gh api repos/owner/repo/contents/file.ts?ref=dev
+gh api repos/owner/repo/contents/file.ts?ref=v1.0.0
+gh api repos/owner/repo/contents/file.ts?ref=abc123
+
+# ❌ Wrong - uses default branch
+gh api repos/owner/repo/contents/file.ts
+```
+
+## Pagination
+
+### Default limits
+
+Different commands have different default limits:
+
+```bash
+# gh search commands default to 30 results
+gh search repos "topic:rust"  # Returns max 30
+
+# Specify limit explicitly
+gh search repos "topic:rust" --limit 100  # Max 100
+
+# API commands may paginate automatically
+gh api repos/owner/repo/issues  # May return all or paginate
+```
+
+### Manual pagination
+
+```bash
+# Use --paginate for API calls
+gh api --paginate repos/owner/repo/issues
+
+# Search commands have hard limit of 1000 total results
+gh search repos "topic:python" --limit 1000
+```
+
+## Permission Errors
+
+### Authentication required
+
+Some operations require authentication:
+
+```bash
+# Works without auth
+gh search repos "topic:rust"
+gh api repos/owner/repo/contents/README.md
+
+# Requires auth
+gh repo view owner/private-repo
+gh search repos "is:private"
+
+# Set token
+export GH_TOKEN="your_token"
+# or
+gh auth login
+```
+
+### Rate limiting
+
+```bash
+# Check rate limit status
+gh api rate_limit
+
+# Authenticated requests have higher limits
+# Unauthenticated: 60 requests/hour
+# Authenticated: 5000 requests/hour
+```
+
+## Quoting Rules
+
+### Shell quoting
+
+```bash
+# ✅ Double quotes for variables
+gh api repos/$OWNER/$REPO/contents/file.ts
+
+# ✅ Single quotes for literal strings
+gh search code 'function*'
+
+# ✅ Escape special chars in double quotes
+gh search repos "name with \"quotes\""
+```
+
+### JSON quoting in --json
+
+```bash
+# ✅ Comma-separated field list
+gh repo view owner/repo --json name,description,stargazerCount
+
+# ❌ Wrong - no quotes around field names
+gh repo view owner/repo --json "name","description"
+
+# ❌ Wrong - spaces
+gh repo view owner/repo --json name, description
+```
+
+## Command-Specific Quirks
+
+### gh search vs gh api
+
+Different approaches for different use cases:
+
+```bash
+# Use gh search for discovery
+gh search repos "topic:rust" --sort stars
+
+# Use gh api for precise data
+gh api repos/owner/repo --jq '.stargazers_count'
+```
+
+### gh repo view vs gh api
+
+Field names differ:
+
+```bash
+# gh repo view uses camelCase
+gh repo view owner/repo --json stargazerCount
+
+# gh api uses snake_case
+gh api repos/owner/repo --jq '.stargazers_count'
+```
+
+## Common Errors
+
+### "No field named X"
+
+You used the wrong field name for the command:
+
+```bash
+# Error: "No field named stargazersCount"
+gh repo view owner/repo --json stargazersCount
+
+# Fix: use stargazerCount for gh repo view
+gh repo view owner/repo --json stargazerCount
+```
+
+### "Not Found (404)"
+
+File doesn't exist or wrong ref:
+
+```bash
+# Check file exists in branch
+gh api repos/owner/repo/contents/path/file.ts?ref=main
+
+# Try different ref
+gh api repos/owner/repo/contents/path/file.ts?ref=dev
+```
+
+### "Bad credentials"
+
+Authentication issue:
+
+```bash
+# Check auth status
+gh auth status
+
+# Re-authenticate
+gh auth login
+```
+
+## Tips
+
+### Always test field names
+
+Before using in scripts, test the field name:
+
+```bash
+# Check available fields
+gh repo view owner/repo --json | jq keys
+
+# Check search result fields
+gh search repos "query" --json | jq '.[0] | keys'
+```
+
+### Use --help
+
+Every command has detailed help:
+
+```bash
+gh search repos --help
+gh api --help
+gh repo view --help
+```
+
+### Check the manual
+
+For edge cases, check official docs:
+
+- CLI manual: https://cli.github.com/manual/
+- Search syntax: https://docs.github.com/en/search-github
+- API reference: https://docs.github.com/en/rest