Skip to content

Understanding Git Files

Jump to bottom
ThanuMahee12 edited this page Oct 20, 2025 · 1 revision

Understanding Git Files

A comprehensive guide to all Git-related files in this starter template.

Configuration Files

.gitignore

What it does: Tells Git which files to ignore and not track.

Why you need it:

  • Prevents committing sensitive data (passwords, API keys in .env files)
  • Keeps repository clean (no OS files like .DS_Store, Thumbs.db)
  • Avoids committing build artifacts (node_modules/, dist/, *.log)
  • Reduces repository size

When to use:

  • Every project needs this
  • Add patterns as you discover files that shouldn't be tracked

Common patterns:

# Secrets
.env
*.key

# Dependencies
node_modules/
vendor/

# Build output
dist/
build/
*.log

Tips:

  • Start general, add specific patterns as needed
  • Use git status to find files that should be ignored
  • Visit gitignore.io for language-specific templates

.gitattributes

What it does: Controls how Git handles files (line endings, merging, diffs).

Why you need it:

  • Prevents line ending issues between Windows (CRLF) and Unix/Mac (LF)
  • Ensures consistent behavior across different operating systems
  • Marks binary files so Git doesn't try to merge them

When to use:

  • Working in teams with different operating systems
  • Project has shell scripts (need LF) and batch files (need CRLF)
  • Repository contains binary files (images, PDFs)

Key settings:

* text=auto          # Auto-detect and normalize line endings
*.sh text eol=lf     # Force LF for shell scripts
*.bat text eol=crlf  # Force CRLF for Windows batch files
*.png binary         # Treat as binary (don't try to merge)

Benefits:

  • No more "line ending changed" in diffs
  • Scripts work on any OS
  • Binary files don't get corrupted

.editorconfig

What it does: Ensures consistent code formatting across different editors.

Why you need it:

  • Team members use different editors (VS Code, IntelliJ, Sublime)
  • Automatic formatting without manual configuration
  • Prevents "tabs vs spaces" debates

When to use:

  • Multi-developer projects
  • Want consistent indentation and formatting
  • Working with multiple file types

Common settings:

indent_style = space  # Use spaces, not tabs
indent_size = 2       # 2 spaces per indent
end_of_line = lf      # Use LF line endings
charset = utf-8       # Use UTF-8 encoding

Supported by:

  • VS Code
  • IntelliJ IDEA
  • Sublime Text
  • Vim/Neovim
  • Many others

.gitkeep

What it does: Keeps empty directories in Git.

Why you need it:

  • Git doesn't track empty directories
  • Needed for project structure (logs/, temp/, uploads/)

When to use:

  • You want a directory in the repository but it starts empty
  • Build process expects certain directories to exist

How to use:

mkdir logs
touch logs/.gitkeep
git add logs/.gitkeep

Example structure:

project/
├── logs/.gitkeep       # Empty logs directory
├── uploads/.gitkeep    # Empty uploads directory
└── temp/.gitkeep       # Empty temp directory

Alternative: Create a .keep or README.md file instead.

Documentation Files

README.md

What it does: Main documentation file that appears on GitHub homepage.

Why you need it:

  • First thing people see when they visit your repository
  • Explains what the project does and how to use it
  • Improves project discoverability

When to use:

  • Every project should have one
  • Update whenever project changes significantly

Essential sections:

# Project Name
Brief description

## Installation
How to install

## Usage
How to use

## Contributing
How to contribute

## License
License information

Tips:

  • Keep it concise but informative
  • Add badges (build status, version)
  • Include examples/screenshots for UI projects
  • Use clear, simple language

LICENSE

What it does: Defines legal terms for using, modifying, and distributing your code.

Why you need it:

  • Without a license, your code is protected by copyright (others can't use it)
  • Makes it clear what others can and cannot do
  • Required for open-source projects

When to use:

  • Public repositories (always)
  • Private repositories if shared with others

Common licenses:

  • MIT - Very permissive, can do almost anything (most common)
  • Apache 2.0 - Permissive, includes patent protection
  • GPL v3 - Copyleft, derivative works must use same license
  • Unlicense - Public domain, no restrictions

How to choose:

  • Want maximum freedom? → MIT
  • Want protection from patent claims? → Apache 2.0
  • Want derivatives to remain open? → GPL v3

Resources: choosealicense.com

CONTRIBUTING.md

What it does: Guidelines for how others can contribute to your project.

Why you need it:

  • Sets expectations for contributors
  • Reduces low-quality contributions
  • Makes it easier for new contributors to start

When to use:

  • Open-source projects accepting contributions
  • Team projects with external collaborators

Key sections:

  • How to report bugs
  • How to suggest features
  • How to submit pull requests
  • Code style guidelines
  • Testing requirements

Benefits:

  • Fewer incomplete PRs
  • More consistent contributions
  • Saves maintainer time

CODE_OF_CONDUCT.md

What it does: Defines acceptable behavior and community standards.

Why you need it:

  • Creates welcoming environment
  • Provides recourse for dealing with bad behavior
  • Required by some organizations/communities

When to use:

  • Public open-source projects
  • Projects with active community
  • Projects under organizations with CoC requirements

Common standard:

  • Contributor Covenant (used by thousands of projects)
  • Sets baseline for respectful communication

SECURITY.md

What it does: Instructions for reporting security vulnerabilities.

Why you need it:

  • Provides private channel for security reports
  • Prevents public disclosure of vulnerabilities before fix
  • Shows you take security seriously

When to use:

  • Production applications
  • Libraries/frameworks used by others
  • Projects handling sensitive data

Key information:

  • How to report (email, GitHub Security Advisory)
  • What to include in report
  • Expected response time
  • Disclosure policy

Benefits:

  • Responsible disclosure
  • Time to fix before public knows
  • Professional appearance

CHANGELOG.md

What it does: Human-readable history of changes between versions.

Why you need it:

  • Users can see what changed without reading git log
  • Helps users decide whether to upgrade
  • Documents breaking changes

When to use:

  • Projects with version releases
  • Libraries/packages others depend on
  • Any project with users who need to know about changes

Format (Keep a Changelog):

# Changelog

## [1.0.1] - 2025-01-15
### Fixed
- Login bug on mobile devices

## [1.0.0] - 2025-01-10
### Added
- User authentication
- Profile pages

### Changed
- Updated homepage design

Categories:

  • Added (new features)
  • Changed (changes to existing)
  • Deprecated (soon to be removed)
  • Removed (removed features)
  • Fixed (bug fixes)
  • Security (security fixes)

GitHub Templates

Pull Request Template

What it does: Pre-fills PR description with a template.

Why you need it:

  • Ensures PRs have consistent information
  • Reminds contributors what to include
  • Makes reviewing easier

When to use:

  • Projects with multiple contributors
  • Want consistent PR descriptions
  • Need specific information in PRs

Benefits:

  • Better PR descriptions
  • Faster reviews
  • Less back-and-forth

This template:

  • Minimal (just Description + Notes)
  • Works for any project
  • Can be expanded as needed

Automation

GitHub Actions Workflows

What it does: Automates tasks when events happen (push, PR, etc.).

Why you need it:

  • Saves manual work
  • Ensures consistency
  • Catches problems early

Common use cases:

  • Run tests on every PR
  • Auto-format code
  • Build and deploy
  • Create releases (this template)

This template includes:

  • Auto-release - Creates version tags and releases on merge to main

Benefits:

  • No manual versioning
  • Automatic release notes
  • Consistent release process

Summary

Must-Have (Every Project)

  • .gitignore - Don't commit junk
  • README.md - Explain your project
  • LICENSE - Legal protection

Highly Recommended

  • .gitattributes - Consistent line endings
  • .editorconfig - Consistent formatting
  • CONTRIBUTING.md - Guide contributors

When Needed

  • .gitkeep - Keep empty directories
  • CHANGELOG.md - Track versions
  • SECURITY.md - For production apps
  • CODE_OF_CONDUCT.md - For communities
  • PR Template - For multiple contributors
  • GitHub Actions - Automate repetitive tasks

Start Simple, Add as You Grow

You don't need everything at once. Start with the must-haves and add more as your project grows and needs evolve.

Maintained by @ThanuMahee12

Home | Getting Started | Understanding Git Files | Auto Release Workflow

Clone this wiki locally