CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-thefuck

Magnificent app which corrects your previous console command

Overview
Eval results
Files

shell-integration.mddocs/

Shell Integration

Multi-shell support for command history, aliases, and shell-specific functionality across bash, zsh, fish, tcsh, and PowerShell environments. This system provides seamless integration with various shells through platform-specific implementations.

Capabilities

Base Shell Interface

Generic shell class providing the foundation for all shell-specific implementations.

class Generic:
    """
    Base shell class with common functionality.
    
    All shell-specific classes inherit from this base class
    and override methods as needed for shell-specific behavior.
    """
    
    def get_aliases(self):
        """
        Returns dictionary of shell aliases.
        
        Returns:
        dict: Mapping of alias names to their expansions
        
        Default implementation returns empty dict.
        Shell-specific implementations parse alias files/commands.
        """
    
    def from_shell(self, command_script):
        """
        Prepares command before running in app.
        
        Parameters:
        - command_script (str): Original command string
        
        Returns:
        str: Command with aliases expanded
        
        Expands shell aliases to full commands for proper analysis.
        """
    
    def to_shell(self, command_script):
        """
        Prepares command for running in shell.
        
        Parameters:
        - command_script (str): Command to prepare for shell execution
        
        Returns:
        str: Shell-ready command string
        
        Default implementation returns command unchanged.
        Shell-specific implementations may add escaping or formatting.
        """
    
    def app_alias(self, fuck):
        """
        Returns shell alias configuration for thefuck integration.
        
        Parameters:
        - fuck (str): Alias name to use (typically 'fuck')
        
        Returns:
        str: Shell-specific alias command
        
        Generates the alias command that users add to their shell config.
        """
    
    def put_to_history(self, command_script):
        """
        Adds command script to shell history.
        
        Parameters:
        - command_script (str): Command to add to history
        
        Returns:
        None
        
        Appends the corrected command to the shell's history file
        so it appears in command history for future use.
        """

Module-Level Shell Functions

High-level functions that automatically detect and use the appropriate shell.

def from_shell(command):
    """
    Prepares command using current shell's from_shell method.
    
    Parameters:
    - command (str): Command string to prepare
    
    Returns:
    str: Command prepared by current shell implementation
    
    Automatically detects current shell and delegates to appropriate handler.
    """

def to_shell(command):
    """
    Prepares command using current shell's to_shell method.
    
    Parameters:
    - command (str): Command string to prepare for shell
    
    Returns:
    str: Shell-ready command string
    
    Automatically detects current shell and delegates to appropriate handler.
    """

def thefuck_alias():
    """
    Returns default alias name for thefuck.
    
    Returns:
    str: Default alias name (typically 'fuck')
    
    Can be overridden by TF_ALIAS environment variable.
    """

def app_alias(alias):
    """
    Returns alias command for current shell.
    
    Parameters:
    - alias (str): Desired alias name
    
    Returns:
    str: Shell-specific alias configuration command
    
    Generates alias command for user's shell configuration file.
    """

def put_to_history(command):
    """
    Adds command to current shell's history.
    
    Parameters:
    - command (str): Command to add to history
    
    Returns:
    None
    
    Uses current shell's history mechanism to store the command.
    """

Shell-Specific Implementations

The system includes specialized implementations for major shells:

Bash Shell Support

class Bash(Generic):
    """
    Bash shell implementation with bash-specific features.
    
    Supports:
    - Bash history file (~/.bash_history)
    - Bash alias parsing
    - Bash-specific alias format
    """
    
    def app_alias(self, fuck):
        """
        Returns bash-specific alias command.
        
        Example output:
        alias fuck='TF_ALIAS=fuck eval $(thefuck $(fc -ln -1))'
        """

Zsh Shell Support

class Zsh(Generic):
    """
    Zsh shell implementation with zsh-specific features.
    
    Supports:
    - Zsh history file (~/.zsh_history)
    - Zsh alias parsing
    - Zsh-specific history format
    """

Fish Shell Support

class Fish(Generic):
    """
    Fish shell implementation with fish-specific features.
    
    Supports:
    - Fish history file (~/.local/share/fish/fish_history)
    - Fish alias (abbreviation) parsing
    - Fish-specific syntax
    """
    
    def app_alias(self, fuck):
        """
        Returns fish-specific alias command.
        
        Example output:
        function fuck; eval (thefuck (history | head -1)); end
        """

PowerShell Support

class Powershell(Generic):
    """
    PowerShell implementation for Windows environments.
    
    Supports:
    - PowerShell history
    - PowerShell alias format
    - Windows-specific paths and commands
    """

Usage Examples

Basic Shell Integration

from thefuck.shells import from_shell, to_shell, put_to_history

# Process command through current shell
original_command = "ll -la"
expanded_command = from_shell(original_command)  # Expands 'll' alias to 'ls -la'
print(f"Expanded: {expanded_command}")

# Prepare corrected command for shell execution
corrected = "ls -la"
shell_ready = to_shell(corrected)
print(f"Shell ready: {shell_ready}")

# Add to shell history
put_to_history("ls -la")

Alias Configuration Generation

from thefuck.shells import app_alias, thefuck_alias

# Get default alias name
default_alias = thefuck_alias()  # Usually 'fuck'
print(f"Default alias: {default_alias}")

# Generate alias command for current shell
alias_command = app_alias('f')  # Use 'f' instead of 'fuck'
print(f"Add to shell config: {alias_command}")

# Examples of output for different shells:
# Bash: alias f='TF_ALIAS=f eval $(thefuck $(fc -ln -1))'
# Fish: function f; eval (thefuck (history | head -1)); end
# Zsh: alias f='TF_ALIAS=f eval $(thefuck $(fc -ln -1))'

Direct Shell Object Usage

from thefuck.shells import Generic, Bash, Fish

# Create shell-specific instances
bash_shell = Bash()
fish_shell = Fish()

# Use bash-specific functionality
bash_aliases = bash_shell.get_aliases()
bash_alias_cmd = bash_shell.app_alias('fuck')
print(f"Bash alias: {bash_alias_cmd}")

# Use fish-specific functionality
fish_alias_cmd = fish_shell.app_alias('fuck')
print(f"Fish alias: {fish_alias_cmd}")

# Process command through specific shell
command = "ll"
bash_expanded = bash_shell.from_shell(command)
fish_expanded = fish_shell.from_shell(command)

History Management

from thefuck.shells import put_to_history

# Add corrected commands to history
corrections = [
    "git push origin main",
    "sudo apt update",
    "ls -la /home/user"
]

for correction in corrections:
    put_to_history(correction)
    print(f"Added to history: {correction}")

Custom Shell Detection

import os
from thefuck.shells import Generic, Bash, Zsh, Fish

def get_current_shell():
    """Detect current shell from environment."""
    shell_path = os.environ.get('SHELL', '')
    
    if 'bash' in shell_path:
        return Bash()
    elif 'zsh' in shell_path:
        return Zsh()
    elif 'fish' in shell_path:
        return Fish()
    else:
        return Generic()

# Use detected shell
current_shell = get_current_shell()
alias_cmd = current_shell.app_alias('f')
print(f"Shell-specific alias: {alias_cmd}")

Shell Integration Patterns

Alias Expansion

The system handles various alias expansion patterns:

# Example alias expansions:
# 'll' -> 'ls -la'
# 'gs' -> 'git status'
# 'la' -> 'ls -A'
# 'gp' -> 'git push'

expanded = from_shell('ll /home')  # Becomes 'ls -la /home'

History File Formats

Different shells use different history formats:

  • Bash: Plain text, one command per line
  • Zsh: Extended format with timestamps (if enabled)
  • Fish: YAML-based format with metadata
  • PowerShell: Binary format (platform-specific)

Environment Integration

The shell system integrates with environment variables:

  • SHELL: Detect current shell
  • TF_ALIAS: Override default alias name
  • HISTFILE: Use custom history file location
  • Shell-specific variables (e.g., BASH_HISTORY, ZDOTDIR)

Cross-Platform Considerations

Path Handling

  • Unix/Linux: Uses forward slashes, tilde expansion
  • Windows: Handles backslashes and drive letters
  • PowerShell: Uses .NET path handling

Command Escaping

  • Bash/Zsh: Uses shell quoting rules
  • Fish: Uses fish-specific escaping
  • PowerShell: Uses PowerShell string handling

History Location

  • Unix: Typically in home directory
  • Windows: Often in user profile directory
  • macOS: Follows Unix conventions with some variations

Error Handling

The shell integration system handles various error conditions:

  • Unknown shells: Falls back to Generic implementation
  • Missing history files: Creates files as needed
  • Permission errors: Logs warnings and continues
  • Invalid aliases: Ignores malformed alias definitions
  • Shell detection failures: Uses safe defaults

This robust error handling ensures thefuck works across different environments even when shell-specific features are unavailable.

Install with Tessl CLI

npx tessl i tessl/pypi-thefuck

docs

configuration.md

core-application.md

data-types.md

index.md

rule-development.md

rule-system.md

shell-integration.md

user-interface.md

utilities.md

tile.json