🐚 shtick

Group Organization

Groups are the core organizational unit in shtick. Each group contains related aliases, environment variables, and functions that can be activated together.

Use groups to separate configurations by context - work projects, personal tools, development environments, or any logical grouping that makes sense for your workflow.

Select a subtopic to learn about creating groups and managing their activation state.

Creating Groups

Activation

Groups can be activated/deactivated. Only active groups' items are loaded into your shell:

Managing Items

Items are the individual configuration pieces within groups: aliases, environment variables, and shell functions. Each item type has specialized handling to ensure correct escaping and syntax across all supported shells.

Select a subtopic to learn how to manage each item type.

Aliases

Environment Variables

Functions

Shell Support

shtick generates shell-specific code for each supported shell:

• POSIX/Bash-like: bash, zsh, ksh, dash, ash, mksh, pdksh, yash
• Modern: fish, xonsh, elvish, nu, ion
• Legacy: tcsh, csh
• PowerShell: pwsh

Each shell receives properly formatted syntax. For example, Fish uses set -gx VAR value instead of export VAR=value.

Auto-Sourcing

The auto-sourcing wrapper makes changes apply immediately without manual source commands. The wrapper:

1. Intercepts shtick commands
2. Runs the actual shtick binary
3. On success, sources the updated loader file
4. Returns the original exit code

Module Structure

shtick/
├── shtick.h              # Data structures & declarations
├── main.c                # Command dispatcher (~650 LOC)
├── config.c              # TOML persistence (~410 LOC)
├── groups.c              # Group lifecycle
├── aliases.c             # Alias management
├── env.c                 # Environment variable management
├── functions.c           # Function management (~310 LOC)
├── generator.c           # Multi-shell code gen (~650 LOC)
├── escape.c              # Shell-specific escaping (~270 LOC)
├── completions.c         # Shell completion gen (~400 LOC)
├── display.c             # Status output
├── utils.c               # Shared utilities (~280 LOC)
├── source_cmd.c          # Auto-sourcing helper
├── settings.c            # User preferences
├── backup.c              # Backup/restore
├── batch.c               # Bulk operations
└── wrapper.c             # Wrapper generation

Config Persistence

The config.c module handles TOML parsing and writing:

• Parses [group.aliases], [group.env], [group.functions] sections
• Multiline string support for function bodies
• Automatic directory creation
• Separate active_groups file for activation state

Code Generator

The generator.c module creates shell-specific loader files:

• Iterates through active groups (always includes persistent)
• Formats aliases, env vars, functions per shell syntax
• Applies shell-specific escaping
• Writes to load_active.<shell>

Value Escaping

The escape.c module handles security and syntax:

• Shell-specific quoting rules
• Injection pattern detection
• Different handling for Bash, Fish, PowerShell, etc.
• Critical variable warnings (PATH, HOME, SHELL)

Data Flow

User Command
    ↓
main.c parses arguments
    ↓
Item added/removed
    ↓
config.save_config() → writes config.toml
    ↓
generator.generate_shell_file()
    ↓
For each shell:
  - escape values
  - format syntax
  - write load_active.<shell>
    ↓
If auto-sourcing:
  - source load_active.<shell>

Two-Phase System

shtick uses a two-phase configuration approach:

1. Phase 1 - Metadata: Update config.toml (shell-agnostic)
2. Phase 2 - Generation: Create shell-specific loader files

This separation allows regenerating files anytime without losing config, and makes it easy to add new shells.