0
# Shell Integration
1

2
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.
3

4
## Capabilities
5

6
### Base Shell Interface
7

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

10
```python { .api }
11
class Generic:
12
    """
13
    Base shell class with common functionality.
14
    
15
    All shell-specific classes inherit from this base class
16
    and override methods as needed for shell-specific behavior.
17
    """
18
    
19
    def get_aliases(self):
20
        """
21
        Returns dictionary of shell aliases.
22
        
23
        Returns:
24
        dict: Mapping of alias names to their expansions
25
        
26
        Default implementation returns empty dict.
27
        Shell-specific implementations parse alias files/commands.
28
        """
29
    
30
    def from_shell(self, command_script):
31
        """
32
        Prepares command before running in app.
33
        
34
        Parameters:
35
        - command_script (str): Original command string
36
        
37
        Returns:
38
        str: Command with aliases expanded
39
        
40
        Expands shell aliases to full commands for proper analysis.
41
        """
42
    
43
    def to_shell(self, command_script):
44
        """
45
        Prepares command for running in shell.
46
        
47
        Parameters:
48
        - command_script (str): Command to prepare for shell execution
49
        
50
        Returns:
51
        str: Shell-ready command string
52
        
53
        Default implementation returns command unchanged.
54
        Shell-specific implementations may add escaping or formatting.
55
        """
56
    
57
    def app_alias(self, fuck):
58
        """
59
        Returns shell alias configuration for thefuck integration.
60
        
61
        Parameters:
62
        - fuck (str): Alias name to use (typically 'fuck')
63
        
64
        Returns:
65
        str: Shell-specific alias command
66
        
67
        Generates the alias command that users add to their shell config.
68
        """
69
    
70
    def put_to_history(self, command_script):
71
        """
72
        Adds command script to shell history.
73
        
74
        Parameters:
75
        - command_script (str): Command to add to history
76
        
77
        Returns:
78
        None
79
        
80
        Appends the corrected command to the shell's history file
81
        so it appears in command history for future use.
82
        """
83
```
84

85
### Module-Level Shell Functions
86

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

89
```python { .api }
90
def from_shell(command):
91
    """
92
    Prepares command using current shell's from_shell method.
93
    
94
    Parameters:
95
    - command (str): Command string to prepare
96
    
97
    Returns:
98
    str: Command prepared by current shell implementation
99
    
100
    Automatically detects current shell and delegates to appropriate handler.
101
    """
102

103
def to_shell(command):
104
    """
105
    Prepares command using current shell's to_shell method.
106
    
107
    Parameters:
108
    - command (str): Command string to prepare for shell
109
    
110
    Returns:
111
    str: Shell-ready command string
112
    
113
    Automatically detects current shell and delegates to appropriate handler.
114
    """
115

116
def thefuck_alias():
117
    """
118
    Returns default alias name for thefuck.
119
    
120
    Returns:
121
    str: Default alias name (typically 'fuck')
122
    
123
    Can be overridden by TF_ALIAS environment variable.
124
    """
125

126
def app_alias(alias):
127
    """
128
    Returns alias command for current shell.
129
    
130
    Parameters:
131
    - alias (str): Desired alias name
132
    
133
    Returns:
134
    str: Shell-specific alias configuration command
135
    
136
    Generates alias command for user's shell configuration file.
137
    """
138

139
def put_to_history(command):
140
    """
141
    Adds command to current shell's history.
142
    
143
    Parameters:
144
    - command (str): Command to add to history
145
    
146
    Returns:
147
    None
148
    
149
    Uses current shell's history mechanism to store the command.
150
    """
151
```
152

153
## Shell-Specific Implementations
154

155
The system includes specialized implementations for major shells:
156

157
### Bash Shell Support
158

159
```python { .api }
160
class Bash(Generic):
161
    """
162
    Bash shell implementation with bash-specific features.
163
    
164
    Supports:
165
    - Bash history file (~/.bash_history)
166
    - Bash alias parsing
167
    - Bash-specific alias format
168
    """
169
    
170
    def app_alias(self, fuck):
171
        """
172
        Returns bash-specific alias command.
173
        
174
        Example output:
175
        alias fuck='TF_ALIAS=fuck eval $(thefuck $(fc -ln -1))'
176
        """
177
```
178

179
### Zsh Shell Support
180

181
```python { .api }
182
class Zsh(Generic):
183
    """
184
    Zsh shell implementation with zsh-specific features.
185
    
186
    Supports:
187
    - Zsh history file (~/.zsh_history)
188
    - Zsh alias parsing
189
    - Zsh-specific history format
190
    """
191
```
192

193
### Fish Shell Support
194

195
```python { .api }
196
class Fish(Generic):
197
    """
198
    Fish shell implementation with fish-specific features.
199
    
200
    Supports:
201
    - Fish history file (~/.local/share/fish/fish_history)
202
    - Fish alias (abbreviation) parsing
203
    - Fish-specific syntax
204
    """
205
    
206
    def app_alias(self, fuck):
207
        """
208
        Returns fish-specific alias command.
209
        
210
        Example output:
211
        function fuck; eval (thefuck (history | head -1)); end
212
        """
213
```
214

215
### PowerShell Support
216

217
```python { .api }
218
class Powershell(Generic):
219
    """
220
    PowerShell implementation for Windows environments.
221
    
222
    Supports:
223
    - PowerShell history
224
    - PowerShell alias format
225
    - Windows-specific paths and commands
226
    """
227
```
228

229
## Usage Examples
230

231
### Basic Shell Integration
232

233
```python
234
from thefuck.shells import from_shell, to_shell, put_to_history
235

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

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

246
# Add to shell history
247
put_to_history("ls -la")
248
```
249

250
### Alias Configuration Generation
251

252
```python
253
from thefuck.shells import app_alias, thefuck_alias
254

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

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

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

269
### Direct Shell Object Usage
270

271
```python
272
from thefuck.shells import Generic, Bash, Fish
273

274
# Create shell-specific instances
275
bash_shell = Bash()
276
fish_shell = Fish()
277

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

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

287
# Process command through specific shell
288
command = "ll"
289
bash_expanded = bash_shell.from_shell(command)
290
fish_expanded = fish_shell.from_shell(command)
291
```
292

293
### History Management
294

295
```python
296
from thefuck.shells import put_to_history
297

298
# Add corrected commands to history
299
corrections = [
300
    "git push origin main",
301
    "sudo apt update",
302
    "ls -la /home/user"
303
]
304

305
for correction in corrections:
306
    put_to_history(correction)
307
    print(f"Added to history: {correction}")
308
```
309

310
### Custom Shell Detection
311

312
```python
313
import os
314
from thefuck.shells import Generic, Bash, Zsh, Fish
315

316
def get_current_shell():
317
    """Detect current shell from environment."""
318
    shell_path = os.environ.get('SHELL', '')
319
    
320
    if 'bash' in shell_path:
321
        return Bash()
322
    elif 'zsh' in shell_path:
323
        return Zsh()
324
    elif 'fish' in shell_path:
325
        return Fish()
326
    else:
327
        return Generic()
328

329
# Use detected shell
330
current_shell = get_current_shell()
331
alias_cmd = current_shell.app_alias('f')
332
print(f"Shell-specific alias: {alias_cmd}")
333
```
334

335
## Shell Integration Patterns
336

337
### Alias Expansion
338

339
The system handles various alias expansion patterns:
340

341
```python
342
# Example alias expansions:
343
# 'll' -> 'ls -la'
344
# 'gs' -> 'git status'
345
# 'la' -> 'ls -A'
346
# 'gp' -> 'git push'
347

348
expanded = from_shell('ll /home')  # Becomes 'ls -la /home'
349
```
350

351
### History File Formats
352

353
Different shells use different history formats:
354

355
- **Bash**: Plain text, one command per line
356
- **Zsh**: Extended format with timestamps (if enabled)
357
- **Fish**: YAML-based format with metadata
358
- **PowerShell**: Binary format (platform-specific)
359

360
### Environment Integration
361

362
The shell system integrates with environment variables:
363

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

369
## Cross-Platform Considerations
370

371
### Path Handling
372
- Unix/Linux: Uses forward slashes, tilde expansion
373
- Windows: Handles backslashes and drive letters
374
- PowerShell: Uses .NET path handling
375

376
### Command Escaping
377
- Bash/Zsh: Uses shell quoting rules
378
- Fish: Uses fish-specific escaping
379
- PowerShell: Uses PowerShell string handling
380

381
### History Location
382
- Unix: Typically in home directory
383
- Windows: Often in user profile directory
384
- macOS: Follows Unix conventions with some variations
385

386
## Error Handling
387

388
The shell integration system handles various error conditions:
389

390
- **Unknown shells**: Falls back to Generic implementation
391
- **Missing history files**: Creates files as needed
392
- **Permission errors**: Logs warnings and continues
393
- **Invalid aliases**: Ignores malformed alias definitions
394
- **Shell detection failures**: Uses safe defaults
395

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