# difft (difftastic) Advanced Usage

Semantic, AST-aware diff tool for meaningful code comparisons.

## Display Modes

### Side-by-Side (Default)

```bash
difft old.ts new.ts
# Shows files side by side with syntax highlighting
```

### Inline (Unified Style)

```bash
difft --display=inline old.ts new.ts
# Traditional unified diff format
```

### Side-by-Side in Terminal

```bash
difft --display=side-by-side old.ts new.ts
# Explicit side-by-side
```

## Filtering Options

### Skip Unchanged

```bash
difft --skip-unchanged old.ts new.ts
# Only show files that changed
```

### Context Lines

```bash
difft --context 5 old.ts new.ts
# Show 5 lines of context around changes
```

### Language Override

```bash
difft --language=python file1 file2
# Force specific language parser

# List supported languages
difft --list-languages
```

## Color and Formatting

```bash
# Force color output (for piping)
difft --color=always old.ts new.ts | less -R

# Disable color
difft --color=never old.ts new.ts

# Set terminal width
difft --width 120 old.ts new.ts

# Tab width
difft --tab-width 4 old.ts new.ts
```

## Git Integration

### As External Diff

```bash
# One-time use
GIT_EXTERNAL_DIFF=difft git diff
GIT_EXTERNAL_DIFF=difft git show HEAD~1
GIT_EXTERNAL_DIFF=difft git log -p

# With options
GIT_EXTERNAL_DIFF="difft --display=inline" git diff
```

### Configure as Default

```bash
# Add to ~/.gitconfig
git config --global diff.external difft

# Or add to .gitconfig directly:
# [diff]
#     external = difft

# Disable for specific command
git --no-ext-diff diff
```

### As Difftool

```bash
# Configure
git config --global diff.tool difftastic
git config --global difftool.difftastic.cmd 'difft "$LOCAL" "$REMOTE"'
git config --global difftool.prompt false

# Use
git difftool HEAD~1
git difftool main feature-branch
```

### Per-Repository

```bash
# In repo's .git/config
git config diff.external difft

# Or in .gitattributes for specific files
*.rs diff=difftastic
```

## Directory Comparison

```bash
# Compare directories
difft dir1/ dir2/

# Compare with options
difft --skip-unchanged dir1/ dir2/
```

## Why Semantic Diffs?

### Traditional diff vs difft

| Scenario | Traditional | difft |
|----------|-------------|-------|
| Reformatted code | Shows all lines as changed | Shows only semantic changes |
| Moved function | Delete + Add | Recognizes as move |
| Renamed variable | Many line changes | Highlights just the rename |
| Added whitespace | Shows as change | Ignores (no semantic change) |
| Reordered imports | All imports changed | Shows specific additions/removals |

### Example: Reformatting

Traditional diff:
```diff
-function foo() { return 42; }
+function foo() {
+  return 42;
+}
```

difft:
```
(no changes - semantically identical)
```

### Example: Moved Code

Traditional diff:
```diff
-function helper() { ... }
 function main() { ... }
+function helper() { ... }
```

difft:
```
function helper() { ... }  →  (moved to line 10)
```

## Supported Languages

difft parses actual ASTs for many languages:

- **Web**: JavaScript, TypeScript, JSX, TSX, CSS, HTML, JSON
- **Systems**: C, C++, Rust, Go, Zig
- **Scripting**: Python, Ruby, Perl, Lua, Bash
- **JVM**: Java, Kotlin, Scala, Clojure
- **Functional**: Haskell, OCaml, Elixir, Erlang
- **Others**: SQL, YAML, TOML, Nix, Terraform

```bash
# List all
difft --list-languages
```

## Performance Tips

```bash
# For large files, limit context
difft --context 3 large1.ts large2.ts

# Skip binary files
difft --skip-unchanged dir1/ dir2/

# Force text mode for unknown formats
difft --language=text file1 file2
```

## Piping and Scripting

```bash
# Pipe to pager
difft old.ts new.ts | less -R

# Save to file
difft --color=never old.ts new.ts > changes.txt

# Check if files differ (exit code)
difft old.ts new.ts > /dev/null
echo $?  # 0 = same, 1 = different
```

## Common Workflows

### Code Review

```bash
# Review specific commit
GIT_EXTERNAL_DIFF=difft git show abc123

# Review PR changes
GIT_EXTERNAL_DIFF=difft git diff main...feature-branch

# Review staged changes
GIT_EXTERNAL_DIFF=difft git diff --cached
```

### Before/After Refactoring

```bash
# Save original
cp module.ts module.ts.bak

# Refactor...

# Compare
difft module.ts.bak module.ts
```

### Comparing Branches

```bash
# Full diff between branches
GIT_EXTERNAL_DIFF=difft git diff main feature-branch

# Specific file across branches
difft <(git show main:src/index.ts) <(git show feature:src/index.ts)
```

### Comparing Commits

```bash
# Specific file between commits
difft <(git show HEAD~2:src/index.ts) <(git show HEAD:src/index.ts)
```

## Configuration

Create `~/.config/difft/config.toml`:

```toml
# Display mode
display = "side-by-side"

# Context lines
context = 3

# Tab width
tab-width = 4

# Color theme (try different values)
color = "always"
```

## Tips

1. **Use with git always** - `GIT_EXTERNAL_DIFF=difft` or configure globally
2. **Skip unchanged in directories** - `--skip-unchanged` for cleaner output
3. **Inline for copy/paste** - `--display=inline` when sharing diffs
4. **Force language** - `--language=X` when auto-detection fails
5. **Combine with delta** - Use difft for semantic diffs, delta for line-level

# tokei Advanced Usage

Complete reference for tokei code statistics tool.

## Filtering Options

### By Language

```bash
# Only specific languages
tokei --type=TypeScript,JavaScript,Python
tokei -t TypeScript,Rust

# Exclude languages
tokei --exclude-lang=Markdown,JSON

# List all recognized languages
tokei --languages
```

### By Path

```bash
# Specific directories
tokei src/ lib/ tests/

# Exclude directories
tokei --exclude node_modules --exclude dist --exclude vendor
tokei -e "*.test.*" -e "*.spec.*"

# Include hidden files
tokei --hidden

# Include gitignored files
tokei --no-ignore
```

### By Depth

```bash
# Limit directory depth
tokei --max-depth 2

# Only files in current directory
tokei --max-depth 1
```

## Output Formats

### Default Table

```bash
tokei
# ===============================================================================
#  Language            Files        Lines         Code     Comments       Blanks
# ===============================================================================
#  TypeScript             45        12847         9823         1456         1568
#  JavaScript             12         2341         1876          234          231
# ===============================================================================
```

### Compact

```bash
tokei --compact
# -------------------------------------------------------------------------------
#  TypeScript   45   12847    9823    1456    1568
#  JavaScript   12    2341    1876     234     231
# -------------------------------------------------------------------------------
```

### JSON

```bash
tokei --output json
# {"TypeScript":{"blanks":1568,"code":9823,"comments":1456,"lines":12847},...}

# Pretty print with jq
tokei --output json | jq .

# Extract specific language
tokei --output json | jq '.TypeScript.code'

# Get total lines
tokei --output json | jq '.Total.code'
```

### YAML

```bash
tokei --output yaml
# TypeScript:
#   blanks: 1568
#   code: 9823
#   comments: 1456
#   lines: 12847
```

## Sorting

```bash
# Sort by lines of code (default)
tokei --sort code

# Sort by number of files
tokei --sort files

# Sort by comments
tokei --sort comments

# Sort by blank lines
tokei --sort blanks

# Sort by total lines
tokei --sort lines
```

## Per-File Statistics

```bash
# Show statistics per file
tokei --files

# JSON with file details
tokei --output json --files | jq '.TypeScript.reports[].name'
```

## Common Workflows

### Compare Before/After

```bash
# Before refactoring
tokei --output json > before.json

# Make changes...

# After refactoring
tokei --output json > after.json

# Compare
diff before.json after.json

# Or with jq
echo "Before: $(jq '.Total.code' before.json), After: $(jq '.Total.code' after.json)"
```

### CI Size Limits

```bash
#!/bin/bash
# Check codebase size limits in CI

MAX_LINES=100000
LINES=$(tokei --output json | jq '.Total.code')

if [ "$LINES" -gt "$MAX_LINES" ]; then
    echo "ERROR: Codebase exceeds $MAX_LINES lines (current: $LINES)"
    exit 1
fi

echo "Codebase size OK: $LINES lines"
```

### Language Breakdown Report

```bash
#!/bin/bash
# Generate language breakdown report

echo "# Code Statistics Report"
echo "Generated: $(date)"
echo
tokei --compact --sort code
echo
echo "## Details"
tokei --output json | jq -r '
  to_entries |
  sort_by(-.value.code) |
  .[] |
  select(.key != "Total") |
  "- \(.key): \(.value.code) lines (\(.value.files) files)"
'
```

### Track Growth Over Time

```bash
#!/bin/bash
# Append to stats history

DATE=$(date +%Y-%m-%d)
STATS=$(tokei --output json | jq -c '{date: "'"$DATE"'", stats: .Total}')
echo "$STATS" >> code_stats_history.jsonl

# View history
cat code_stats_history.jsonl | jq -s '.'
```

## Configuration File

Create `.tokeirc` or `tokei.toml` in project root:

```toml
# tokei.toml
columns = 80
files = false
hidden = false
no_ignore = false
sort = "code"
types = ["TypeScript", "JavaScript", "Python"]

[languages.TypeScript]
line_comment = ["//"]
multi_line = ["/*", "*/"]
quotes = [["\"", "\""], ["'", "'"]]
```

## Understanding Output

| Column | Meaning |
|--------|---------|
| Files | Number of files of this language |
| Lines | Total lines (code + comments + blanks) |
| Code | Non-blank, non-comment lines |
| Comments | Lines that are comments |
| Blanks | Empty/whitespace-only lines |

### What Counts as Code?

- Executable statements
- Declarations
- Import/export statements
- NOT: comments, blank lines, documentation strings (in some languages)

## Comparison with Other Tools

| Feature | tokei | cloc | sloccount | wc -l |
|---------|-------|------|-----------|-------|
| Speed | Fastest | Slow | Medium | Fastest |
| Language detection | Yes | Yes | Yes | No |
| Comment detection | Yes | Yes | Yes | No |
| .gitignore respect | Yes | Yes | No | No |
| JSON output | Yes | Yes | No | No |
| Multi-threaded | Yes | No | No | No |
| Memory usage | Low | High | Medium | Lowest |

## Tips

1. **Use `--compact` for quick overview** - easier to scan
2. **Pipe JSON to jq for scripting** - machine-readable output
3. **Exclude generated code** - `--exclude dist --exclude generated`
4. **Compare branches** - checkout each, run tokei, diff results
5. **Regular tracking** - run in CI to catch unexpected growth