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
• 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)

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.