AdvancedLesson 30 of 308 min read

Capstone: Audit, Repair and Release a Shared Repository

Audit a messy repository with ten checks, repair what can be repaired, tag a release, and report honestly on what cannot.

In this lesson you will

  • Audit a repository against clear checks
  • Repair tracked junk, branches and missing files
  • Tag a release
  • Report what could not be fixed, and why

About 40 minutes

The repository nobody wants to touch

The garden club’s shared site repository has grown over a year. Several people have committed to it, some in a hurry. Nobody is sure what is in it, and the volunteers are afraid to change anything. Dev asks Nia, “Can you make it safe to work in, and tag a proper release?” This capstone uses every Advanced skill: look carefully, audit with clear checks, repair what can be repaired, tag the result, and be honest about what cannot.

Step one: see what we are dealing with

The session below builds the messy repository for real. It contains the usual signs of neglect: a settings file with a fake key committed along with a log file, vague commit messages, a finished branch left lying around, an unfinished idea on another branch, a large media file, a leftover note, and no README, no ignore rules and no release tag.

$ mkdir club-site
$ cd club-site
$ git init
Initialized empty Git repository in /home/nia/club-site/.git/
$ echo "Beans: row 1" > plan.txt
$ echo "Mon: Nia" > rota.txt
$ echo "API_KEY=FAKE-example-not-real" > .env
$ echo "debug line" > debug.log
$ git add .
$ git commit -m "stuff"
[main (root-commit) d13fe15] stuff
 4 files changed, 4 insertions(+)
 create mode 100644 .env
 create mode 100644 debug.log
 create mode 100644 plan.txt
 create mode 100644 rota.txt
$ echo "Carrots: row 2" >> plan.txt
$ git commit -am "more"
[main 8ceaef5] more
 1 file changed, 1 insertion(+)
$ git switch -c old-idea
Switched to a new branch 'old-idea'
$ echo "Idea: a seed swap" > idea.txt
$ git add idea.txt
$ git commit -m "Try an idea"
[old-idea c45fce2] Try an idea
 1 file changed, 1 insertion(+)
 create mode 100644 idea.txt
$ git switch main
Switched to branch 'main'
$ git switch -c add-peas
Switched to a new branch 'add-peas'
$ echo "Peas: row 3" >> plan.txt
$ git commit -am "Add peas"
[add-peas 7cbe910] Add peas
 1 file changed, 1 insertion(+)
$ git switch main
Switched to branch 'main'
$ git merge add-peas --no-edit
Updating 8ceaef5..7cbe910
Fast-forward
 plan.txt | 1 +
 1 file changed, 1 insertion(+)
$ python3 -c "import random; open('media.bin','wb').write(random.Random(7).randbytes(300000))"
$ git add media.bin
$ git commit -m "Add media"
[main 219ebbb] Add media
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 media.bin
$ echo "TODO: check rota" >> plan.txt
$ git commit -am "Update"
[main 772e86b] Update
 1 file changed, 1 insertion(+)
$ git branch
  add-peas
* main
  old-idea
$ git log --oneline | wc -l
5

Step two: audit before touching anything

Repairs should start from evidence. The audit below runs ten checks against the real repository and prints the verdict of each, with one line of detail. The checks use ideas from earlier lessons: tracked junk and secrets, clear titles, merged and unmerged branches, large files, release tags and history scanning. The 100,000 byte size limit is a made-up teaching number.

import os, re, subprocess
REPO = "/home/nia/club-site"
def git(*a):
    return subprocess.run(["git", "-C", REPO, *a], capture_output=True, text=True).stdout.strip()
tracked = git("ls-files").split()
results = []
def check(name, ok, detail):
    results.append(ok)
    print(("PASS " if ok else "FAIL ") + name + ": " + detail)
check("README present", "README.md" in tracked, "yes" if "README.md" in tracked else "missing")
check(".gitignore present", ".gitignore" in tracked, "yes" if ".gitignore" in tracked else "missing")
junk = [f for f in tracked if re.search(r"\.env$|\.log$", f)]
check("no junk or secret files tracked", not junk, str(len(junk)) + " found")
subjects = git("log", "--format=%s").splitlines()
vague = [s for s in subjects if s.split()[0].lower() in {"stuff", "more", "update", "wip", "fix"} or len(s.split()) < 2]
check("clear commit titles", not vague, str(len(vague)) + " vague of " + str(len(subjects)))
merged = [b for b in git("branch", "--merged", "main").replace("*", "").split() if b != "main"]
check("no merged branches left", not merged, str(len(merged)) + " left")
stale = git("branch", "--no-merged", "main").replace("*", "").split()
check("no undecided side branches", not stale, str(len(stale)) + " waiting")
big = [f for f in tracked if os.path.getsize(os.path.join(REPO, f)) > 100000]
check("no large files tracked", not big, str(len(big)) + " over 100000 bytes")
check("a release tag exists", bool(git("tag")), git("tag") or "none")
leak = git("log", "--all", "-p", "--format=").count("API_KEY=")
check("no secret anywhere in history", leak == 0, str(leak) + " matching diff lines")
dirty = git("status", "--porcelain")
check("working folder clean", dirty == "", "clean" if dirty == "" else "changes waiting")
print("checks passed:", sum(results), "of", len(results))
FAIL README present: missing
FAIL .gitignore present: missing
FAIL no junk or secret files tracked: 2 found
FAIL clear commit titles: 3 vague of 5
FAIL no merged branches left: 1 left
FAIL no undecided side branches: 1 waiting
FAIL no large files tracked: 1 over 100000 bytes
FAIL a release tag exists: none
FAIL no secret anywhere in history: 1 matching diff lines
PASS working folder clean: clean
checks passed: 1 of 10

Only 1 of 10 checks passed, and the one that passed is the working folder being clean. That is a long list, but a list is exactly what makes the job manageable: each failure is a single task.

Step three: repair what can be repaired

The repair is one tidy commit, plus branch clean-up and a tag. In order: stop tracking the secret, the log and the big file with the cached removal from lesson 6, which leaves them on disk. Add a README and ignore rules so they do not come back. Remove the leftover note. Delete the finished branch with the safe delete, which only works because it is merged. Delete the unfinished idea with the forced delete, which is a team decision, and the commit would still be recoverable for a while from lesson 27. Finally, create an annotated tag.

$ git rm -q --cached .env debug.log media.bin
$ printf "# Club site\n\nPlanting plan and rota for the garden club.\n" > README.md
$ echo ".env" > .gitignore
$ echo "*.log" >> .gitignore
$ echo "media.bin" >> .gitignore
$ sed -i '/TODO/d' plan.txt
$ git add README.md .gitignore plan.txt
$ git commit -m "Add README, ignore rules and clean up"
[main 523ba02] Add README, ignore rules and clean up
 6 files changed, 6 insertions(+), 3 deletions(-)
 delete mode 100644 .env
 create mode 100644 .gitignore
 create mode 100644 README.md
 delete mode 100644 debug.log
 delete mode 100644 media.bin
$ git branch -d add-peas
Deleted branch add-peas (was 7cbe910).
$ git branch -D old-idea
Deleted branch old-idea (was c45fce2).
$ git tag -a v1.0.0 -m "First tidy release"
$ git branch
* main
$ git status -sb
## main

Step four: audit again, and be honest

PASS README present: yes
PASS .gitignore present: yes
PASS no junk or secret files tracked: 0 found
FAIL clear commit titles: 3 vague of 6
PASS no merged branches left: 0 left
PASS no undecided side branches: 0 waiting
PASS no large files tracked: 0 over 100000 bytes
PASS a release tag exists: v1.0.0
FAIL no secret anywhere in history: 2 matching diff lines
PASS working folder clean: clean
checks passed: 8 of 10

Now 8 of 10 pass. Two checks still fail, and they are the interesting ones: clear commit titles and no secret anywhere in history. Neither can be fixed with another commit. The old messages are part of the history, and changing them means rewriting commits that others already have, which lesson 19 warned about. The secret is worse: it sits in the very first commit, and in every copy of the repository. Deleting the file did not remove it.

For the old messages, the practical answer is to accept them and write better ones from now on, enforced by the hook from lesson 23. For the secret, the only responsible answer is the one from lesson 6: treat the key as compromised and replace it with the service that issued it. Rewriting history to remove it is an advanced, risky job that affects everyone with a copy, and it does not recall copies already made. A good report says exactly this, instead of claiming a perfect score.

What to deliver

  • The repaired repository, with the new tag.
  • The before and after audit results, side by side.
  • A short note listing what was done, what was left, and why.
  • The action for the owner: replace the key, and decide whether a history rewrite is worth the disruption.
  • A follow up: add the hook and the checks from lessons 23 and 24 so the problems do not return.
Common mistake: moving the goalposts

Reporting a clean score by quietly changing what the audit tests. If a check is hard to pass, explain it, do not delete it.

Made-up repository, teaching rules

The repository, people, key and files are made up, and no real GitHub repository was changed. The ten checks are teaching rules, and the size limit is invented. A real audit would also look at access settings, protected branches and dependencies on the hosting site, which cannot be seen here.

Run an audit like this on one of your own repositories. Write down every failure before you fix any, and keep the before and after results.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

Why audit before repairing?

  1. Evidence shows what needs fixing and proves the result afterwards
  2. Audits are required by Git
  3. Repairs are impossible without one
  4. It makes the repository smaller

Each failed check became one task.

What does git rm –cached do to a file?

  1. Deletes it everywhere
  2. Stops tracking it but leaves it on disk
  3. Signs it
  4. Pushes it

The secret and the log stopped being tracked and stayed on disk.

Why could the old commit titles not be fixed with a new commit?

  1. Titles cannot be edited by anyone
  2. GitHub forbids titles
  3. New commits delete old titles
  4. They are part of history, and rewriting shared commits causes trouble

That check was still failing after the repair.

Why does the secret still fail the history check after the repair?

  1. The audit is wrong
  2. It is still in the first commit and in every copy
  3. Git never deletes tags
  4. The file was renamed

Deleting a file does not remove it from history.

What is the responsible step for the secret?

  1. Do nothing
  2. Delete the branch
  3. Add it to the README
  4. Replace the key with the service that issued it

Treat any committed secret as compromised.

Summary

  • Audit first, so every repair is a named task with a before and after result.
  • git rm –cached, ignore rules, a README and branch clean-up fix most neglect.
  • History problems, such as old messages and committed secrets, cannot be fixed with a new commit.
  • An honest report names the failures that remain and the action for the owner.

Next lesson

You have finished the Git and GitHub course. Keep a real project under Git, and read the help pages of the services you use.

Questions

Should I rewrite history to remove the secret?

Only after replacing the key, and only if the disruption is worth it. Rewriting affects everyone with a copy and cannot recall copies already made. Many teams replace the key and leave the history alone.

Why delete the unfinished branch?

In this made-up case the team decided the idea was abandoned. In real life, ask first, because the branch may hold someone's work. A deleted branch can be recovered for a while with the reflog.

What would a full real audit add?

It would also look at the hosting site: who has access, which branches are protected, which checks run, and whether secret scanning is on. None of those can be seen from the local repository.

Progress is saved in this browser.