.gitignore, README Files & GitHub Issues — Making Your Projects Look Professional

In Day 1, we pushed code. In Day 2, we learned to branch and merge like a real team. Today we polish everything — keeping junk files out of Git, writing a README that makes people want to use your project, and tracking bugs and tasks with GitHub Issues. Let’s finish strong. ✨

Quick Recap of Day 1 & Day 2

• Day 1: Git = local tool, GitHub = online home. We installed everything, created a repo, and pushed code both by starting fresh (git init) and by cloning (git clone).
• Day 2: We stopped editing main directly. Instead, we created branches, opened Pull Requests, and learned to resolve merge conflicts.

Today’s focus is different — it’s not about new Git commands, it’s about making your repository clean, understandable, and professional, the way real companies expect.

Part 1: .gitignore — Keeping Junk Out of Git

The Problem

Every coding project generates files that should never be uploaded to GitHub:

• node_modules/ — a folder of installed packages that can be huge (sometimes 500MB+) and can always be reinstalled.
• .env — files containing secret API keys or passwords.
• .DS_Store (Mac) or Thumbs.db (Windows) — junk files your operating system creates automatically.
• Build output folders like dist/ or build/.

If you accidentally commit these, your repository becomes bloated, slow, and — worse — you might leak secret passwords publicly on the internet. This has happened to real companies!

The Solution: A .gitignore File

Create a file named exactly .gitignore (yes, starting with a dot, no extension) in your project's root folder:

bash

touch .gitignore

Open it in VS Code and list the files/folders you want Git to ignore completely:

# Dependencies
node_modules/
# Environment secrets
.env
# OS junk files
.DS_Store
Thumbs.db
# Build output
dist/
build/
# Editor settings
.vscode/

How to read this file:

• Each line is a pattern describing what to ignore.
• A trailing / means "ignore this entire folder."
• Lines starting with # are comments — notes for humans, ignored by Git.
• Once listed here, Git will never track these files, even if you run git add . — they simply won't show up in git status.

Important: .gitignore Only Works on New Files

If you already committed a file (like .env) before adding it to .gitignore, Git keeps tracking it. You must remove it from Git's tracking manually:

bash

git rm --cached .env
git commit -m "Stop tracking .env file"

--cached means "remove it from Git, but keep the actual file safely on my computer" — very important, so you don't delete your own secrets by accident!

Pro Tip: Use a Template

Instead of writing .gitignore from scratch every time, GitHub provides ready-made templates for every language/framework at github.com/github/gitignore. When creating a new repository on GitHub, there's even a dropdown to auto-generate the right .gitignore for you (Node, Python, Java, etc.).

Part 2: README.md — Your Project’s First Impression

Why It Matters

When someone visits your GitHub repository, the README file is the first (and often only) thing they read. A good README answers: What is this project? How do I run it? Who built it? A missing or messy README makes even great code look unprofessional.

Creating It

Create a file named exactly README.md in your project's root:

bash

touch README.md

The .md extension means Markdown — a simple text formatting language (the same one we use for these blog posts!). GitHub automatically renders it beautifully on your repository's homepage.

A Solid README Template

markdown

# Project NameA one-line description of what this project does.
## Features
- Feature one
- Feature two
- Feature three
## Screenshots
![App Screenshot](screenshot.png)
## Installation
\`\`\`bash
git clone https://github.com/yourusername/project-name.git
cd project-name
npm install
\`\`\`
## Usage
\`\`\`bash
npm start
\`\`\`
## Technologies Used
- HTML5, CSS3
- JavaScript
- Node.js
## Contributing
Pull requests are welcome. For major changes, please open an issue first.
## License
This project is licensed under the MIT License.

Breaking down why each section matters:

• Title + one-liner → tells visitors instantly what this is.
• Features → a quick scan of what the project can do (use - for an unordered list, same Markdown syntax as regular bullet points).
• Installation → step-by-step commands so anyone can run your project locally, without asking you questions.
• Usage → how to actually use it once installed.
• Technologies Used → helps recruiters and collaborators quickly see your tech stack.
• License → tells others what they’re legally allowed to do with your code.

Markdown Basics You’ll Use Constantly

Push It Like Any Other File

Get Pranshi Verma’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

bash

git add README.md
git commit -m "Added project README"
git push origin main

Refresh your GitHub page — your README now displays automatically below the file list.

Part 3: GitHub Issues — Tracking Bugs & Tasks

What Are Issues?

GitHub Issues is a built-in tool for tracking bugs, feature requests, and to-do tasks for your project — like a lightweight task manager, connected directly to your code.

Creating an Issue

1. Go to your repository on GitHub.
2. Click the Issues tab.
3. Click New issue.
4. Write a clear title, e.g., “Navbar breaks on mobile screens.”
5. In the description, explain:

• What’s wrong (or what feature is needed)
• Steps to reproduce the bug (if applicable)
• Screenshots, if helpful:

1. Optionally, add Labels (like bug, enhancement, good first issue) and assign it to a teammate.
2. Click Submit new issue.

Why Teams Use Issues Instead of WhatsApp/Email

• Every task has a permanent record, linked directly to the code it affects.
• You can discuss an issue in comments, right where the context lives.
• You can link a Pull Request to an Issue — when the PR merges, the issue automatically closes!

Linking a Commit or PR to an Issue

If Issue #4 is “Fix navbar bug,” you can close it automatically when you push the fix:

bash

git commit -m "Fix navbar overflow on mobile, closes #4"

Words like closes #4, fixes #4, or resolves #4 in a commit message or Pull Request description tell GitHub to automatically close that Issue the moment the code is merged into main. This keeps your task list accurate without manual bookkeeping.

Putting It All Together: A Professional Repository Checklist

Before you consider a project “submission-ready” or “portfolio-ready,” check:

• .gitignore is present, so no junk files or secrets were ever committed
• README.md clearly explains what the project does and how to run it
• Commit messages are clear and descriptive (from Day 1!)
• Features were built on separate branches and merged via Pull Requests (from Day 2!)
• Known bugs or pending tasks are tracked as GitHub Issues, not just remembered in your head

Quick Recap: New Concepts from Today

Common Beginner Mistakes to Watch Out For

• Adding .gitignore too late → always create it before your first commit, so secrets and junk never enter history in the first place.
• Committing .env files with real passwords → if this happens, don't just delete the file — the password is still visible in your Git history! You'd need to change the actual password/API key immediately.
• Writing a one-line README like just the project title → always include installation and usage steps, even for small projects.
• Never using Issues, just remembering tasks mentally → doesn’t scale once you’re working with a team, and you lose a record of what was fixed and why.

What We Achieved Today (Day 3 Recap)

✅ Learned why certain files should never be committed to Git

✅ Created a .gitignore file and removed an already-tracked file safely ✅ Wrote a professional README.md using Markdown

✅ Created and managed GitHub Issues for tracking bugs and tasks

✅ Learned how to auto-close Issues by referencing them in commits/PRs

Over these three days, you’ve gone from installing Git for the first time to using the exact same workflow — branches, Pull Requests, .gitignore, README, Issues — that professional software teams use every single day. That's a huge milestone!

From here, the best way to get better is to use this workflow on your own projects, even solo ones. Create issues for yourself, branch for every feature, and keep your README updated as you build. See you in the next session! 🚀

Found Day 3 useful? Give it a clap 👏 and follow along for what’s next in the series!