# Workspace Git Setup

> One-command Git tracking setup for any working directory, with a security-focused .gitignore (credentials, TLS/SSH private keys, tokens, runtime caches & PIDs, node_modules, Python caches, build artifacts, editor temp files), a large-file guard (>10MB), and a read-only --audit mode that detects tracked secrets, untracked files, and core.autocrlf misconfiguration. Three modes: (1) init — git init + safe .gitignore + first commit; (2) --audit — read-only health check (no mutations); (3) --dry-run — preview every change without applying. Reads Git identity from GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL env vars > existing git config > interactive prompt; falls back to the email prefix when only the email is provided. Workspace path resolution: CLI arg > WORKSPACE_DIR env var > current directory. Default branch is main; sets core.autocrlf=input to avoid CRLF false diffs. Trigger this skill when the user says any of: 'add git to my project', 'init git', 'git init', 'track my changes', 'version history', 'back up my workspa

- Skill: `songhonglei/workspace-git-setup` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add songhonglei/workspace-git-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/songhonglei/workspace-git-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Songhonglei (https://skillmd.com/u/songhonglei)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/songhonglei/workspace-git-setup

---


# workspace-git-setup

One command to set up safe, sensible Git tracking for any working directory — with a built-in security audit.

A zero-dependency Bash script that initializes Git version control for a project, ships a battle-tested security `.gitignore`, warns about large files before your first commit, and can audit an existing repo for leaked secrets and untracked files.

**Pure `bash` + `git`. No Python, no npm, no third-party packages.**

- **Author**: Evan Song · [github.com/Songhonglei](https://github.com/Songhonglei)
- **Repository**: https://github.com/Songhonglei/better-agent-skills
- **License**: MIT

## Usage

```bash
# Initialize / align config (defaults to current directory; auto-uses dir name as project name)
bash scripts/setup.sh

# Specify workspace path and project name
bash scripts/setup.sh /path/to/project "MyProject"

# Audit mode (read-only): detects sensitive files / untracked files / config
bash scripts/setup.sh --audit

# Dry-run mode: preview every action without applying anything
bash scripts/setup.sh --dry-run
```

## Path & identity resolution

| Item | Priority |
|------|----------|
| Workspace path | CLI argument > `WORKSPACE_DIR` env var > current directory |
| Git identity | `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` env vars > existing git config > interactive prompt |

> When only an email is provided, the email prefix is used as the username (you can change it later with `git config`).

## Three modes

| Mode | What it does | Mutates? |
|------|--------------|----------|
| *(default)* init / align | git init + writes safe .gitignore + large-file warning + first commit | ✏️ yes |
| `--audit` | read-only health check: tracked secrets / untracked files / core.autocrlf | 👀 no |
| `--dry-run` | preview every change without applying | 👀 no |

## Default flow (init mode)

1. **Resolve path** — CLI arg > `WORKSPACE_DIR` > current directory
2. **Infer project name** — workspace basename (override with the 2nd argument)
3. **Read identity** — env vars → existing git config → interactive prompt
4. **git init** — skipped if a repo already exists (idempotent); sets `core.autocrlf=input` to unify line endings; default branch `main`
5. **Write `.gitignore`** — if one exists, shows a diff and asks before overwriting
6. **Large-file warning** — scans files >10MB to be tracked and asks for confirmation
7. **First commit** — auto-stages and commits
8. **Summary** — shows project name, path, git identity, and audit usage

## Default `.gitignore` rules (general-purpose security)

| Category | Patterns |
|----------|----------|
| Credentials | `.env`, `.env.*`, `*.pem`, `secrets/`, `.credentials/`, `*token*.json`, `*secret*.json` |
| TLS / SSH keys | `**/certs/*.key`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, `*.p12`, `*.keystore` |
| Temp / cache | `tmp/`, `*.tmp`, `*.cache`, `*.log`, `*.pid` |
| OS / editor | `.DS_Store`, `._*`, `Thumbs.db`, `.vscode/`, `.idea/`, `*.swp`, etc. |
| Dependencies | `node_modules/`, `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `.pytest_cache/` |
| Build output | `output/`, `dist/`, `build/`, `out/`, `*.egg-info/` |

> Note: private-key ignores are scoped to `**/certs/*.key` (instead of a blanket `*.key`) so legitimate `.key` files elsewhere are not hidden.

## Audit mode (`--audit`)

Read-only run that outputs three checks, **never modifies anything**:

1. **Sensitive file detection** — lists private keys / tokens / credentials already tracked by Git. Warns only, gives human-review guidance, no destructive commands.
2. **Untracked file detection** — lists files that are neither added nor ignored.
3. **Config check** — whether `core.autocrlf` is sane and `.gitignore` exists.

## Notes

- Pure local Git, no remote; add one yourself when ready: `git remote add origin <url>`
- Script is idempotent and safe to re-run; existing config is preserved.
- If a `.gitignore` already exists, a diff is shown and you choose whether to overwrite.
- Audit only warns on tracked sensitive files — you decide how to remove them.
- When no Git identity is found in env vars or git config, the script falls back to interactive prompts (cannot run unattended without env vars).

## Dependencies

- `git` (required) — https://git-scm.com/downloads
- `bash` 4.0+
- `coreutils` (`numfmt`/`stat`/`realpath`) — preinstalled on most Unix-like systems; `numfmt` is optional (falls back to raw byte counts when absent).

> Pure bash + git implementation, no Python or third-party packages required.