Skip to content

Latest commit

 

History

History
327 lines (237 loc) · 8.57 KB

shell-integration.md

File metadata and controls

327 lines (237 loc) · 8.57 KB

Shell Integration

Camp provides shell integration through the cgo function, which allows instant navigation to camp directories without needing to type cd or wait for a subprocess to complete.

Quick Setup

Add one of the following to your shell configuration:

Zsh (~/.zshrc):

eval "$(camp shell-init zsh)"

Bash (~/.bashrc):

eval "$(camp shell-init bash)"

Fish (~/.config/fish/config.fish):

camp shell-init fish | source

PowerShell ($PROFILE, Windows PowerShell 5.1 or PowerShell 7):

Invoke-Expression (& camp shell-init powershell | Out-String)

POSIX sh (~/.profile) for dash, busybox ash, and the /bin/sh on minimal and embedded systems:

eval "$(camp shell-init sh)"

Use the script for the shell you actually run. In PowerShell, reload with . $PROFILE or open a new session. cgo, csw, and browser g navigate to local destinations; remote hops require a POSIX shell wrapper. The shorthand functions below are available in the POSIX and fish integrations. Tab completion is available in bash, zsh, and fish. The bash script uses bash arrays and programmable completion, so a shell like busybox ash rejects the whole thing with syntax error: unexpected "(" (expecting "fi") and you get no integration at all. The sh script gives you the camp wrapper, cgo, and every shorthand function; it installs no tab completion, because POSIX sh has no completion mechanism to install into. Not sure which you have? camp list names the right command for your shell when integration is missing.

Verified working: dash, busybox ash, and mksh. ksh93 is not supported: it parses the script but has no local builtin, and rather than erroring it silently skips the assignment, so a wrapper function would read whatever the caller happened to have in that variable. The script detects this and refuses with an explanation instead of installing itself.

The cgo Function

The cgo (camp-go) function is the primary interface for navigation. It's a shell function (not an alias or script) because it needs to change the current working directory.

Basic Usage

# Jump to camp root
cgo

# Jump to a category
cgo p         # projects/
cgo f         # festivals/
cgo i         # .campaign/intents/
cgo d         # docs/
cgo w         # workflow/
cgo wt        # projects/worktrees/
cgo r         # workflow/reviews/
cgo de        # workflow/design/
cgo ex        # workflow/explore/

# Fuzzy search within category
cgo p api     # projects/api-* (fuzzy match)
cgo f fest    # festivals/*fest* (fuzzy match)

Category Shortcuts

Shortcut Directory Description
p projects/ Project directories
f festivals/ Festival planning
i .campaign/intents/ Intents via camp intent
settings .campaign/ Camp settings directory
d docs/ Documentation
w workflow/ Workflow resources
wt projects/worktrees/ Git worktrees
r workflow/reviews/ Review materials
de workflow/design/ Design documents
ex workflow/explore/ Exploratory notes

cgo i is intentionally still available for operators who need the underlying files, but day-to-day intent capture and editing should go through camp intent.

Running Commands on Windows

camp run and camp project run launch the named executable with distinct arguments on Windows. PowerShell operators are not interpreted by those commands; invoke powershell.exe -Command explicitly when you need a shell expression. On macOS and Linux, raw command forms keep their shell expression behavior.

In development builds, registered camp flow run commands use PowerShell on Windows and sh on macOS/Linux. A stored POSIX expression can opt into Git Bash with shell: sh in .campaign/flows/registry.yaml. Use shell: powershell to select PowerShell explicitly.

Running Commands (POSIX and Fish)

Use -c to run a command from a category directory without changing to it:

# List projects
cgo -c p ls

# Run fest status from festivals
cgo -c f fest status

# Run tests from a project
cgo -c p api make test

The command inherits your current environment and its output goes to your terminal.

Tab Completion

Shell integration includes intelligent tab completion:

cgo <TAB>       # Shows category shortcuts
cgo p <TAB>     # Shows projects in projects/
cgo p ap<TAB>   # Completes to matching project names

The completion system queries camp for real-time suggestions based on your camp structure.

Helper Functions

Shell integration also provides shorthand functions for common operations:

cint - Quick Intent Capture

cint "my idea for a new feature"

Equivalent to camp intent add "...". Quickly capture thoughts and ideas.

cnote - Quick Note Capture

cnote "quick research note"
cnote "follow up" --body "details to remember"

Equivalent to camp intent note "...". Quickly capture notes without routing them through the intent lifecycle.

cie - Explore Intents

cie

Equivalent to camp intent explore. Opens the interactive TUI for browsing, filtering, and managing intents.

cr - Run from Camp Root

cr make test

Equivalent to camp run make test. Runs a command from the camp root directory.

Technical Details

Why a Shell Function?

The cgo command must be a shell function because:

  • Only shell functions can change the current directory
  • Scripts and binaries run in subprocesses and cannot affect the parent shell
  • Aliases don't support the complex logic needed for argument handling

How It Works

  1. cgo calls camp go --print to get the target path
  2. If successful, it runs cd to change to that directory
  3. If there's an error, it shows the error message
# What happens internally:
cgo p api
# → dest=$(camp go p api --print)
# → cd "$dest"

Error Handling

# Not in a camp
$ cgo
Error: not in a camp
Hint: Initialize with 'camp init' or navigate to a camp

# Target not found
$ cgo p nonexistent
camp: not found: p nonexistent

# Multiple matches show selection
$ cgo p api
Multiple matches found:
  api-service
  api-gateway
Using best match: api-service

Shell-Specific Notes

Zsh

  • Uses [[ ]] for conditionals
  • Uses _describe for completion
  • compdef registers completion functions

Bash

  • Compatible with bash 3.2+ (macOS default)
  • Uses [ ] for POSIX compatibility
  • Avoids bash 4+ features (associative arrays, ${var,,})
  • Uses complete -F for completion

Fish

  • Uses test instead of [ ] or [[ ]]
  • Uses set -l for local variables
  • Uses $status instead of $?
  • Array syntax: $argv[1], $argv[2..-1]
  • Excellent built-in completion support

Finding the installed binary

camp shell-init defines a shell function named camp that wraps the real binary so navigation commands can change your working directory. Because of that, plain which camp usually prints the function body, not a path.

# zsh — external binary only (skips shell functions)
whence -p camp
# or: which -p camp

# bash
type -P camp

# function + every binary on PATH
type -a camp

# resolve symlinks to the real install location
realpath "$(whence -p camp)"   # zsh
realpath "$(type -P camp)"     # bash

Run the binary without the wrapper with command camp ... (for example command camp version).

Troubleshooting

cgo not found

Make sure you added the shell-init line to your config and restarted your shell:

# Check if the camp binary is on PATH (not the shell function)
whence -p camp   # zsh
type -P camp     # bash

# Re-source your config
source ~/.zshrc  # or ~/.bashrc, config.fish

Completion not working

# Zsh: Make sure compinit is loaded
autoload -Uz compinit && compinit

# Bash: Check if bash-completion is installed
type _init_completion

Permission denied on cd

The target directory might not have read/execute permissions:

# Check permissions
ls -la $(camp go p --print)

# Fix if needed
chmod +x path/to/directory

Advanced Usage

Use with other tools

# Open project in editor
code $(camp go p api --print)

# Fuzzy search with fzf
camp go p --print | fzf | xargs cd

# Copy path to clipboard
camp go p api --print | pbcopy

Custom shortcuts

The shell integration supports custom shortcut mappings (future feature). For now, you can add aliases:

alias cdp='cgo p'
alias cdf='cgo f'