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
- Repository: https://github.com/Songhonglei/better-agent-skills
- License: MIT
Usage
# 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)
- Resolve path — CLI arg >
WORKSPACE_DIR> current directory - Infer project name — workspace basename (override with the 2nd argument)
- Read identity — env vars → existing git config → interactive prompt
- git init — skipped if a repo already exists (idempotent); sets
core.autocrlf=inputto unify line endings; default branchmain - Write
.gitignore— if one exists, shows a diff and asks before overwriting - Large-file warning — scans files >10MB to be tracked and asks for confirmation
- First commit — auto-stages and commits
- 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:
- Sensitive file detection — lists private keys / tokens / credentials already tracked by Git. Warns only, gives human-review guidance, no destructive commands.
- Untracked file detection — lists files that are neither added nor ignored.
- Config check — whether
core.autocrlfis sane and.gitignoreexists.
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
.gitignorealready 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/downloadsbash4.0+coreutils(numfmt/stat/realpath) — preinstalled on most Unix-like systems;numfmtis optional (falls back to raw byte counts when absent).
> Pure bash + git implementation, no Python or third-party packages required.
