the-nexus/docs/safe-commit-practices.md

# Safe Commit Practices

**Issue:** #1430 - [IMPROVEMENT] memory_mine.py ran during git commit — shell injection from commit message

## Problem

During commit for #1124, the commit message contained Python code examples that triggered shell execution of memory_mine.py. The backtick-wrapped code in the commit message was interpreted by the shell during git commit processing.

This is a potential vector for unintended code execution.

## Safe Commit Methods

### 1. Use `git commit -F <file>` (Recommended)

The safest way to commit messages containing code or special characters:

```bash
# Create a file with your commit message
echo "Fix: implement memory_mine.py with backtick example

Example: \`python3 bin/memory_mine.py --days 7\`

This commit adds memory mining functionality." > /tmp/commit-msg.txt

# Commit using the file
git commit -F /tmp/commit-msg.txt
```

### 2. Use the Safe Commit Tool

```bash
# Safe commit with automatic escaping
python3 bin/safe_commit.py -m "Fix: implement memory_mine.py with backtick example"

# Safe commit using file
python3 bin/safe_commit.py -F /tmp/commit-msg.txt

# Check if a message is safe
python3 bin/safe_commit.py --check -m "Example: \`python3 bin/memory_mine.py\`"
```

### 3. Escape Shell Characters Manually

If you must use `git commit -m`, escape special characters:

```bash
# Escape backticks and other shell characters
git commit -m "Fix: implement memory_mine.py with backtick example

Example: \\`python3 bin/memory_mine.py --days 7\\`

This commit adds memory mining functionality."
```

## Dangerous Patterns to Avoid

The following patterns in commit messages can trigger shell execution:

- **Backticks**: `` `command` `` → Executes command
- **Command substitution**: `$(command)` → Executes command
- **Variable expansion**: `${variable}` → Expands variable
- **Pipes**: `command1 | command2` → Pipes output
- **Operators**: `&&`, `||`, `;` → Command chaining
- **Redirects**: `>`, `<` → File operations

## Installation

### Install the Commit Hook

To automatically warn about dangerous patterns:

```bash
# Install the commit-msg hook
python3 bin/safe_commit.py --install-hook

# Or manually
cp .githooks/commit-msg .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
```

### Configure Git Hooks Path

If using the `.githooks` directory:

```bash
git config core.hooksPath .githooks
```

## Examples

### ❌ Dangerous (Don't do this)

```bash
# This could trigger shell execution
git commit -m "Fix: implement memory_mine.py

Example: \`python3 bin/memory_mine.py --days 7\`

This mines sessions into MemPalace."
```

### ✅ Safe (Do this instead)

```bash
# Method 1: Use file
echo "Fix: implement memory_mine.py

Example: \`python3 bin/memory_mine.py --days 7\`

This mines sessions into MemPalace." > /tmp/commit-msg.txt
git commit -F /tmp/commit-msg.txt

# Method 2: Use safe commit tool
python3 bin/safe_commit.py -m "Fix: implement memory_mine.py

Example: \`python3 bin/memory_mine.py --days 7\`

This mines sessions into MemPalace."

# Method 3: Escape manually
git commit -m "Fix: implement memory_mine.py

Example: \\`python3 bin/memory_mine.py --days 7\\`

This mines sessions into MemPalace."
```

## What Happened in Issue #1430

During commit for #1124, a commit message contained:
```
Example: \`python3 bin/memory_mine.py --days 7\`
```

The backticks were interpreted by the shell during git commit processing, causing memory_mine.py to execute. While the outcome was positive (26 sessions mined), this is a security risk.

## Prevention

1. **Always use `git commit -F <file>`** for messages containing code
2. **Install the commit-msg hook** to warn about dangerous patterns
3. **Use the safe_commit.py tool** for automatic escaping
4. **Document safe patterns** in team guidelines

## Related Issues

- **Issue #1430:** This improvement
- **Issue #1124:** Original issue that triggered the problem

## Files

- `bin/safe_commit.py` - Safe commit tool
- `.githooks/commit-msg` - Commit hook (to be installed)
- `docs/safe-commit-practices.md` - This documentation

## Conclusion

Shell injection in commit messages is a real security risk. By using safe commit practices, we can prevent unintended code execution while still allowing code examples in commit messages.

**Remember:** When in doubt, use `git commit -F <file>` instead of `git commit -m`.