Version Control | VoidX Academy

11. .gitignore & Repository Best Practices

Best Practices

.gitignore & Repository Best Practices

A well-maintained Git repository is a professional asset. A poorly configured one leaks secrets, bloats with build artefacts, and creates confusion. These practices are the difference between a repository that teams trust and one they dread working with.

🚫 The .gitignore File

The .gitignore file tells Git which files and folders to completely ignore — never stage, never commit, never track. Create it in the root of your repository:

touch .gitignore

Inside your .gitignore file, add content like this:

# Node.js
node_modules/
npm-debug.log
.npm/

# Environment variables (NEVER commit secrets!)
.env
.env.local
.env.production

# Build outputs
dist/
build/
.next/
__pycache__/
*.pyc

# IDE / Editor
.vscode/
.idea/
*.swp

# Operating system
.DS_Store        # macOS
Thumbs.db        # Windows

Add the file to git and commit:

git add .gitignore
git commit -m "chore: add .gitignore"

⚠️The .env file must ALWAYS be in .gitignore. Every week, developers accidentally commit API keys, database passwords, and private tokens to public GitHub repositories. Within seconds, bots scan GitHub for these and abuse them. If you commit a secret, rotate it immediately — deleting the commit is not enough because it still exists in history.

📋 Repository Hygiene Checklist

README.md at root: What is this project? How do you set it up? How do you run it? How do you run the tests? This is the first file any new developer reads.
LICENSE file: Defines how others can use, modify, and distribute your code. Without a license, the default is all rights reserved.
CONTRIBUTING.md: Guidelines for how to submit pull requests and issues to open-source projects.
No build artefacts committed: node_modules/, dist/, __pycache__/ should never be in the repository.
No binary files if avoidable: Git is designed for text. Large binaries (images, compiled binaries, databases) bloat repository size permanently and slow down clones.

📏 Commit Frequency Best Practices

Commit small and often — one logical unit of work per commit. Small commits equal easier code review, make it easier to identify which commit broke something, and are easier to cherry-pick or revert specific changes.

BAD: commit everything at end of day:

git add .
git commit -m "day's work"

GOOD: commit each logical change as you complete it:

git add src/auth/login.js
git commit -m "feat: add email format validation to login form"

git add src/auth/signup.js
git commit -m "feat: add password strength indicator to signup"

git add tests/auth.test.js
git commit -m "test: add unit tests for auth validation functions"

11. .gitignore & Repository Best Practices

Best Practices

.gitignore & Repository Best Practices

🚫 The .gitignore File

The .gitignore file tells Git which files and folders to completely ignore — never stage, never commit, never track. Create it in the root of your repository:

touch .gitignore

Inside your .gitignore file, add content like this:

# Node.js
node_modules/
npm-debug.log
.npm/

# Environment variables (NEVER commit secrets!)
.env
.env.local
.env.production

# Build outputs
dist/
build/
.next/
__pycache__/
*.pyc

# IDE / Editor
.vscode/
.idea/
*.swp

# Operating system
.DS_Store        # macOS
Thumbs.db        # Windows

Add the file to git and commit:

git add .gitignore
git commit -m "chore: add .gitignore"

📋 Repository Hygiene Checklist

README.md at root: What is this project? How do you set it up? How do you run it? How do you run the tests? This is the first file any new developer reads.
CONTRIBUTING.md: Guidelines for how to submit pull requests and issues to open-source projects.
No build artefacts committed: node_modules/, dist/, __pycache__/ should never be in the repository.
No binary files if avoidable: Git is designed for text. Large binaries (images, compiled binaries, databases) bloat repository size permanently and slow down clones.

📏 Commit Frequency Best Practices

BAD: commit everything at end of day:

git add .
git commit -m "day's work"

GOOD: commit each logical change as you complete it:

git add src/auth/login.js
git commit -m "feat: add email format validation to login form"

git add src/auth/signup.js
git commit -m "feat: add password strength indicator to signup"

git add tests/auth.test.js
git commit -m "test: add unit tests for auth validation functions"

11. .gitignore & Repository Best Practices

.gitignore & Repository Best Practices

🚫 The .gitignore File

📋 Repository Hygiene Checklist

📏 Commit Frequency Best Practices

Knowledge Check

11. .gitignore & Repository Best Practices

.gitignore & Repository Best Practices

🚫 The .gitignore File

📋 Repository Hygiene Checklist

📏 Commit Frequency Best Practices

Knowledge Check