Good Commits, Clean Repositories and Keeping Secrets Safe

Git remembers everything, which is wonderful and also dangerous. A history full of messages like fix and stuff is hard to use. A history that contains a password is a security problem that stays until you deal with it. This lesson is about the habits that keep a repository useful and safe, and they matter a lot when employers or teammates read your work.

Commit messages that help

The message is a note to your future self and to your team. A good one says what changed and, when it is not obvious, why. Many teams follow this shape.

• A first line of about 50 characters, in the imperative, as if giving an order: Add search box to the header, Fix crash when the list is empty. It should finish the sentence: *If applied, this commit will...*
• A blank line, then, if needed, a longer explanation of the reason and any side effects.
• No full stop is needed at the end of the first line.
• Avoid fix, update, changes, asdf. Six months later, nobody knows what they mean.
• If your team uses a style such as Conventional Commits (feat:, fix:, docs:), follow it.

git commit -m "Fix crash when the task list is empty" -m "The list page read the first item without checking the length.
It now shows a friendly message instead."

Using -m twice makes the second text a separate paragraph. Without -m, git commit opens your editor, which is easier for longer messages. If you end up in an editor you do not know, such as Vim, press Esc, type :q! and press Enter to leave without saving, then set another editor with git config --global core.editor.

Small, focused commits

• One commit = one idea. Fixing a typo and adding a feature belong in two commits.
• Use git add -p to choose parts of a file for a commit. Git shows each changed block and asks yes or no. This is how you split a messy afternoon into clean commits.
• Do not commit work that is broken, if you can avoid it. A commit should leave the project in a working state.
• Commit often. Small commits are easy to understand, easy to revert and easy to review.

A README is the front door

The README.md file is shown on the front page of your repository on GitHub. For any project that you share, it should say what the project is, how to install and run it, how to use it, and what to do about problems. For a portfolio, add a screenshot and the main technologies. Lesson 10 returns to this. A repository without a README looks unfinished.

What does not belong in a repository

• Secrets: passwords, API keys, tokens, private keys, database addresses with passwords, .env files with real values.
• Personal data: other people's names, phone numbers, ID numbers, customer lists.
• Generated or downloaded files: node_modules/, build folders, caches, virtual environments, compiled files. They can be rebuilt, and they make the repository heavy.
• Large binary files: big videos and datasets. Git is built for text. Hosts also have size limits.
• Editor and system files: .DS_Store, Thumbs.db, .idea/. Put these in your .gitignore.

Keep secrets out: the .env pattern

Programs often need secrets. The standard way is to keep them in a file named .env that is in `.gitignore`, and to read them from the environment in your code. Commit a sample file named .env.example with fake values, so others know which settings are needed. Services and hosts also let you store secrets in their own settings, and GitHub has a feature for secrets used by automatic workflows.

# .gitignore
.env

# .env.example  (this one is committed; the values are fake)
DATABASE_URL=put-your-address-here
API_KEY=put-your-key-here

What if I committed a secret?

Act in this order. The first step is the most important.

1. Treat the secret as stolen. Go to the service that issued it, and revoke or rotate it at once: delete the key and create a new one. Automated bots scan public repositories within minutes, so assume that a public secret has been seen.
2. Put the file in .gitignore and remove it from tracking: git rm --cached .env, then commit.
3. Understand that the old commits still contain the secret. Deleting the file in a new commit does not remove it from the history.
4. If it matters, and especially for a repository that others have copied, rewrite the history with a tool such as git filter-repo or the BFG Repo-Cleaner, and then force-push. This is advanced, and it disturbs everyone who has a copy, so read the documentation first and ask for help.
5. Check the service's logs for use you did not make.

Licences

If you put code on GitHub publicly, and you want others to be able to reuse it, add a licence file. Without one, by default others do not have the right to copy and use your work, even though they can see it. Popular simple choices include MIT and Apache 2.0. GitHub can add a licence file for you when you create a repository, and sites such as choosealicense.com explain the differences. For a legal question about your own work or an employer's code, ask a qualified person.

Your task

1. Rewrite three bad commit messages you can imagine (for example fix, update, changes) as clear, imperative ones.
2. In a practice repo, change two unrelated things in one file and use git add -p to commit them separately.
3. Create .env with a fake secret and .gitignore containing .env. Check that git status does not list it. Add a .env.example.
4. Write a README with: what it is, how to run it, and one example.

How to check it worked

• git log --oneline shows messages that you could understand in six months.
• git status never shows your .env file.
• You can list the first two things to do if a key is committed by mistake.