configure-git-repository

---
name: configure-git-repository
description: >
license: MIT
---

# Configure Git Repository

Set up a Git repository with appropriate configuration for the project type.

## When to Use

- Initializing version control for a new project
- Adding `.gitignore` for a specific language/framework
- Setting up branch protection and conventions
- Configuring commit hooks

## Inputs

- **Required**: Project directory
- **Required**: Project type (R package, Node.js, Python, general)
- **Optional**: Remote repository URL
- **Optional**: Branch strategy (trunk-based, Git Flow)
- **Optional**: Commit message convention

## Procedure

### Step 1: Initialize Repository

```bash
cd /path/to/project
git init
git branch -M main
```

**Expected:** `.git/` directory created. Default branch is named `main`.

**On failure:** If `git init` fails, ensure Git is installed (`git --version`). If the directory already has a `.git/`, the repository is already initialized — skip this step.

### Step 2: Create .gitignore

**R Package**:

```gitignore
# R artifacts
.Rhistory
.RData
.Rproj.user/
*.Rproj

# Environment (sensitive)
.Renviron

# renv library (machine-specific)
renv/library/
renv/staging/
renv/cache/

# Build artifacts
*.tar.gz
src/*.o
src/*.so
src/*.dll

# Documentation build
docs/
inst/doc/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db
```

**Node.js/TypeScript**:

```gitignore
node_modules/
dist/
build/
.next/
.env
.env.local
.env.*.local
*.log
npm-debug.log*
.DS_Store
Thumbs.db
.vscode/
.idea/
coverage/
```

**Python**:

```gitignore
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
.eggs/
.venv/
venv/
.env
*.log
.mypy_cache/
.pytest_cache/
htmlcov/
.coverage
.DS_Store
.idea/
.vscode/
```

**Expected:** `.gitignore` file created with entries appropriate for the project type. Sensitive files (`.Renviron`, `.env`) and generated artifacts are excluded.

**On failure:** If unsure which entries to include, use `gitignore.io` or GitHub's `.gitignore` templates as a starting point and customize for the project.

### Step 3: Create Initial Commit

```bash
git add .gitignore
git add .  # Review what's being added first with git status
git commit -m "Initial project setup"
```

**Expected:** First commit created containing `.gitignore` and initial project files. `git log` shows one commit.

**On failure:** If `git commit` fails with "nothing to commit," ensure files were staged with `git add`. If it fails with an author identity error, set `git config user.name` and `git config user.email`.

### Step 4: Connect Remote

```bash
# Add remote
git remote add origin git@github.com:username/repo.git

# Push
git push -u origin main
```

**Expected:** Remote `origin` is configured. `git remote -v` shows fetch and push URLs. Initial commit is pushed to the remote.

**On failure:** If push fails with "Permission denied (publickey)," configure SSH keys (see `setup-wsl-dev-environment`). If the remote already exists, update it with `git remote set-url origin <url>`.

### Step 5: Set Up Branch Conventions

**Trunk-based (recommended for small teams)**:

- `main`: production-ready code
- Feature branches: `feature/description`
- Bug fixes: `fix/description`

```bash
# Create feature branch
git checkout -b feature/add-authentication

# After work is done, merge or create PR
git checkout main
git merge feature/add-authentication
```

**Expected:** Branch naming convention is established and documented. Team members know which prefix to use for each type of work.

**On failure:** If branches are already named inconsistently, rename them with `git branch -m old-name new-name` and update any open PRs.

### Step 6: Configure Commit Conventions

Conventional Commits format:

```text
type(scope): description

feat: add user authentication
fix: correct calculation in weighted_mean
docs: update README installation section
test: add edge case tests for parser
refactor: extract helper function
chore: update dependencies
```

**Expected:** Commit message convention is documented and agreed upon by the team. Future commits follow the `type: description` format.

**On failure:** If team members are not following the convention, enforce it with a commit-msg hook that validates the format (see Step 7).

### Step 7: Set Up Pre-Commit Hooks (Optional)

Create `.githooks/pre-commit`:

```bash
#!/bin/bash
# Run linter before commit

# For R packages
if [ -f "DESCRIPTION" ]; then
  Rscript -e "lintr::lint_package()" || exit 1
fi

# For Node.js
if [ -f "package.json" ]; then
  npm run lint || exit 1
fi
```

```bash
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks
```

**Expected:** Pre-commit hook runs automatically on each `git commit`. Linting errors block the commit until fixed.

**On failure:** If the hook does not run, verify `core.hooksPath` is set (`git config core.hooksPath`) and the hook file is executable (`chmod +x`).

### Step 8: Create README

```bash
# Minimal README
echo "# Project Name" > README.md
echo "" >> README.md
echo "Brief description of the project." >> README.md
git add README.md
git commit -m "Add README"
```

**Expected:** `README.md` committed to the repository. The project has a minimal but informative landing page on GitHub.

**On failure:** If `README.md` already exists, update it rather than overwriting. Use `usethis::use_readme_md()` in R projects for a template with badges.

## Validation

- [ ] `.gitignore` excludes sensitive and generated files
- [ ] No sensitive data (tokens, passwords) in tracked files
- [ ] Remote repository connected and accessible
- [ ] Branch naming conventions documented
- [ ] Initial commit created cleanly

## Common Pitfalls

- **Committing before .gitignore**: Add `.gitignore` first. Files already tracked aren't affected by later `.gitignore` entries.
- **Sensitive data in history**: If secrets are committed, they remain in history even after deletion. Use `git filter-repo` or BFG to clean.
- **Large binary files**: Don't commit large binaries. Use Git LFS for files > 1MB.
- **Line endings**: Set `core.autocrlf=input` on Windows/WSL to prevent CRLF/LF issues.

## Related Skills

- `commit-changes` - staging and committing workflow
- `manage-git-branches` - branch creation and conventions
- `create-r-package` - Git setup as part of R package creation
- `setup-wsl-dev-environment` - Git installation and SSH keys
- `create-github-release` - creating releases from the repository
- `security-audit-codebase` - check for committed secrets