0
# Contrib Commands
1

2
Enhanced command wrappers that provide optimized defaults and specialized functionality for common tools. The contrib system offers pre-configured versions of popular commands with better defaults and additional features.
3

4
## Capabilities
5

6
### Git Integration
7

8
Enhanced git command with optimized settings for programmatic usage.
9

10
```python { .api }
11
@contrib("git")
12
def git(orig):
13
    """
14
    Git command optimized for programmatic usage.
15
    
16
    Returns:
17
    Command: Git command with TTY output disabled for cleaner programmatic usage
18
    """
19
```
20

21
Usage examples:
22

23
```python
24
import sh
25

26
# Use contrib git for cleaner output
27
git = sh.contrib.git
28
result = git("status", "--porcelain")
29
print("Modified files:", result.strip())
30

31
# Compare with regular git (may have TTY formatting)
32
regular_git = sh.git
33
git_output = regular_git("log", "--oneline", "-n", "5")
34

35
# Contrib git works better for parsing
36
commits = git("log", "--format=%H %s", "-n", "10").strip().split('\n')
37
for commit in commits:
38
    hash_part, message = commit.split(' ', 1)
39
    print(f"Commit: {hash_part[:8]} - {message}")
40
```
41

42
### Bash Command Execution
43

44
Pre-configured bash command for executing shell scripts and commands.
45

46
```python { .api }
47
@contrib("bash")
48
def bash(orig):
49
    """
50
    Bash command pre-configured with -c flag for script execution.
51
    
52
    Returns:
53
    Command: Bash command ready for script execution
54
    """
55
```
56

57
Usage examples:
58

59
```python
60
import sh
61

62
# Execute bash commands and scripts
63
bash = sh.contrib.bash
64
result = bash("echo 'Hello from bash'; ls -la | wc -l")
65
print("Bash output:", result)
66

67
# Execute complex shell pipelines
68
pipeline_result = bash("ps aux | grep python | wc -l")
69
python_processes = int(pipeline_result.strip())
70
print(f"Python processes running: {python_processes}")
71

72
# Execute multi-line bash scripts
73
script = '''
74
for i in {1..5}; do
75
    echo "Count: $i"
76
done
77
'''
78
bash(script)
79
```
80

81
### Sudo with Password Handling
82

83
Enhanced sudo command with automatic password prompting and password parameter support.
84

85
```python { .api }
86
@contrib("sudo")
87
def sudo(orig):
88
    """
89
    Sudo command with enhanced password handling.
90
    
91
    Features:
92
    - Automatic password prompting using getpass
93
    - Password parameter support
94
    - Uses -S flag for stdin password input
95
    
96
    Returns:
97
    Command: Enhanced sudo command with password handling
98
    """
99
```
100

101
Usage examples:
102

103
```python
104
import sh
105
import getpass
106

107
# Interactive password prompting (secure)
108
sudo = sh.contrib.sudo
109
sudo("apt", "update")  # Will prompt for password securely
110

111
# Programmatic password (use carefully)
112
password = getpass.getpass("Enter sudo password: ")
113
sudo("systemctl", "restart", "nginx", password=password)
114

115
# File operations requiring sudo
116
sudo("chown", "www-data:www-data", "/var/www/html/uploads/")
117
sudo("chmod", "755", "/var/www/html/")
118

119
# System administration tasks
120
result = sudo("systemctl", "status", "apache2")
121
if "active (running)" in result:
122
    print("Apache is running")
123
else:
124
    print("Apache is not running")
125
```
126

127
### SSH with Interactive Support
128

129
Advanced SSH command with automatic password handling and interactive session support.
130

131
```python { .api }
132
@contrib("ssh")
133
def ssh(orig):
134
    """
135
    SSH command with enhanced interactive capabilities.
136
    
137
    Features:
138
    - Automatic password authentication
139
    - Interactive session management
140
    - Login success detection
141
    - Session content tracking
142
    
143
    Returns:
144
    Command: Enhanced SSH command with interactive features
145
    """
146
```
147

148
Usage examples:
149

150
```python
151
import sh
152

153
# Note: SSH contrib is primarily for interactive use
154
# For basic SSH commands, regular sh.ssh may be sufficient
155
ssh = sh.contrib.ssh
156

157
# Interactive SSH session (advanced usage)
158
# This is primarily used for complex interactive scenarios
159
# Most users should use regular sh.ssh for simple commands
160

161
# Example of remote command execution
162
try:
163
    result = sh.ssh("user@remote-server", "uptime")
164
    print("Remote uptime:", result.strip())
165
except sh.ErrorReturnCode as e:
166
    print("SSH failed:", e)
167

168
# For file transfers, consider using sh.scp or sh.rsync
169
sh.scp("local_file.txt", "user@remote:/tmp/")
170
sh.rsync("-av", "local_dir/", "user@remote:backup/")
171
```
172

173
### Creating Custom Contrib Commands
174

175
Extend the contrib system with your own enhanced command wrappers.
176

177
```python
178
import sh
179

180
# Example: Enhanced docker command with common defaults
181
@sh.contrib("docker")
182
def docker(orig):
183
    """Docker command with common defaults."""
184
    # Add common flags and settings
185
    cmd = orig.bake("--rm")  # Always remove containers after exit
186
    return cmd
187

188
# Example: Enhanced curl with better defaults
189
@sh.contrib("curl") 
190
def curl(orig):
191
    """Curl with better defaults for API usage."""
192
    cmd = orig.bake(
193
        "-s",           # Silent mode
194
        "-L",           # Follow redirects
195
        "-f",           # Fail on HTTP errors
196
        "--max-time", "30"  # 30 second timeout
197
    )
198
    return cmd
199

200
# Usage
201
docker = sh.contrib.docker
202
curl = sh.contrib.curl
203

204
# These now have the enhanced defaults
205
container_output = docker("run", "ubuntu", "echo", "hello")
206
api_response = curl("https://api.example.com/status")
207
```
208

209
### Accessing Contrib Commands
210

211
Multiple ways to access and use contrib commands in your applications.
212

213
```python
214
import sh
215

216
# Method 1: Direct access
217
git_contrib = sh.contrib.git
218
result = git_contrib("status")
219

220
# Method 2: Import pattern
221
from sh.contrib import git, sudo, bash
222
git_status = git("status", "--porcelain")
223
sudo("systemctl", "restart", "nginx")
224
bash_result = bash("echo $HOME; pwd")
225

226
# Method 3: Dynamic access
227
command_name = "git"
228
contrib_cmd = getattr(sh.contrib, command_name)
229
output = contrib_cmd("log", "--oneline", "-n", "5")
230

231
# Check available contrib commands
232
available_contribs = [cmd for cmd in dir(sh.contrib) if not cmd.startswith('_')]
233
print("Available contrib commands:", available_contribs)
234
```
235

236
## Types
237

238
```python { .api }
239
class Contrib(ModuleType):
240
    """
241
    Module type for contrib command system.
242
    
243
    Provides decorator interface for creating enhanced command wrappers.
244
    """
245
    
246
    @classmethod
247
    def __call__(cls, name: str):
248
        """
249
        Decorator for creating contrib command wrappers.
250
        
251
        Parameters:
252
        - name: str = name of the command to enhance
253
        
254
        Returns:
255
        callable: Decorator function for command enhancement
256
        """
257
```