Skip to content
Tutorials Center
My learning

Topics

Lesson 70 of 78 ยท Projects

Project: A Repository From Scratch

Build a small project's history on purpose: first commits, a feature branch, a merge, annotated release tags and a changelog generated from git log, in four runnable stages.

Reading about Git is not the same as living in a repository for a while. In this project you will build the history of a small tool from the first commit to a tagged release, making every decision a real project makes: what to commit together, when to branch, how to merge, how to name releases and how to turn the log into release notes.

The tool is deliberately tiny, a Bash script called quote.sh that prints a line from a text file, so you can concentrate on Git. The project has four stages. Every stage is a complete script that you can run with the Run button; it repeats the code of the earlier stages so that it works on its own, and the new part is marked with a # ---- stage N ---- comment. By the end you will have a repository with 13 commits, two branches that came and went, two annotated tags and a generated CHANGELOG.md.

Everything in this project works offline in a throwaway directory. The helper function g at the top of each script runs git with a new fixed date every time, so hashes are the same on every run. In real life you do not need it: Git uses the current time.

The plan: conventions first

A repository stays pleasant when the team agrees on a few rules before the first commit. These are the rules for this project, and each one pays off in a later stage:

  • Conventional commit messages: feat: for a new feature, fix: for a bug fix, docs:, test: and chore: for the rest. The prefix lets a script group commits into release notes (stage 4). See Making Good Commits.
  • main is always working. Work happens on short-lived branches (feature/...) and returns to main when its tests pass. See Branch Workflows.
  • Small, focused commits: one idea per commit, so every commit can be understood, reviewed and reverted on its own.
  • Annotated tags for releases (v0.1.0, v0.2.0), following semantic versioning: a new feature raises the middle number while the project is still 0.x.
  • A test script (test.sh) that every commit on main should pass.

Stage 1: the first commits

A first commit is a good place to put the files that describe the project rather than code. Here the first commit holds a README and a .gitignore. The second adds the working script with its data. The third adds a smoke test. Three commits, three clear reasons.

Bash Stage 1: README, script, test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Some details are worth a second look. git add -A && g commit ... stages everything and commits it; with only one unit of work in the directory that is safe, but in a real project you would stage precisely (git add -p, see Staging). The data file is created with printf '%s\n', which prints each argument on its own line, a tidy way to write a multi-line file. The ./test.sh run in the middle proves the test works before it is committed: never commit a test you have not seen pass.

The history is linear and each message tells the story: docs, the first feature, a test. git ls-files lists only files Git tracks. Note that .gitignore itself is tracked, which is what you want, because the whole team shares it (.gitignore).

Stage 2: a feature branch and a merge

Next feature: a --count option that prints how many quotes exist. This is a change you want to build and test in isolation, so it gets a branch. While the branch exists, a teammate (Bob) commits a documentation change to main, so the two branches diverge, which is the normal situation on any active project.

Bash Stage 2: a feature branch and a merge

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

On the branch there are two commits, the feature and a test that covers it. The test edit uses sed -i '/pattern/i text' (GNU sed: insert a line before the line that matches), which keeps the script short; in your editor you would just add the line.

Back on main, Bob's commit docs: describe usage was made with a different author (GIT_AUTHOR_NAME=Bob), and the history shows it in the last command of the stage. Because main moved on, Git cannot simply move the branch pointer forward (a fast-forward). It creates a merge commit with two parents. We asked for that explicitly with --no-ff: even when a fast-forward would be possible, the merge commit documents "this group of commits was one feature". Read the graph from the bottom: the common ancestor test: add a smoke test, then two lines of work, then the merge on top.

After the merge the branch name has done its job. git branch -d feature/count deletes it, and Git allowed that because every commit on it is reachable from main. The commits are not gone; only the label is. If you try git branch -d on an unmerged branch, Git refuses. See Merging and Branch Management.

Stage 3: cutting releases

Time to ship. A release is a named, immutable point in history, which is what a tag is. The first release is 0.1.0. A good routine is: bump the version in a file (VERSION), commit that as chore: release 0.1.0, and tag exactly that commit with an annotated tag (-a). Annotated tags are real objects with a tagger, a date and a message; lightweight tags are just names.

After the tag, development continues. We add a --list option on a second feature branch. This time main did not move while the branch existed, so the merge is a fast-forward (--ff-only says "refuse if it would need a merge commit", a useful safety net in scripts). Then a bug is found: asking for a quote that does not exist silently printed nothing and still exited with success. The fix gets its own commit with a test, a version bump and a second tag.

Bash Stage 3: tags and releases

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Look at the end of the output. git tag -n1 lists each tag with its message, and git describe answers "where am I?": v0.2.0, because HEAD is exactly the tagged commit. The graph shows the tags next to their commits (--decorate), and the --ff-only merge left no merge commit, so the second feature appears as a straight line. git diff --stat v0.1.0 v0.2.0 compares the two releases in one command: three files changed (quote.sh, test.sh and VERSION). The last lines run the tests, list the quotes with --list, and show the new error for quote 9 on stderr with exit code 1.

Notice that the bug fix and its test were committed together, in one commit. Anyone who later runs git bisect or git revert on that fix gets the test with it. See Reverting Commits and bisect.

Stage 4: a changelog from git log

Users do not read commit logs; they read release notes. Because every commit has a conventional prefix, a small script can build the notes. changelog.sh takes a title and a revision range and prints sections for features, fixes and documentation.

The script itself is worth studying as a Git exercise:

  • git log --no-merges --reverse skips merge commits and prints oldest first.
  • --grep="^feat: " selects commits whose message has a line starting with feat: . (Git's --grep is a regular expression applied to the whole message, so the anchor ^ matches at the start of any line; our subjects are on their own line, which is fine here.)
  • --format='%s (%h)' prints the subject and short hash, and sed replaces the prefix with a Markdown bullet.
  • || true stops set -e from aborting when git log finds nothing for a type (no fix: commits in the range).

The range v0.1.0..v0.2.0 means "everything reachable from v0.2.0 that is not reachable from v0.1.0": exactly the commits of release 0.2.0, regardless of how many branches contributed (Revision Syntax).

Bash Stage 4: a changelog from git log

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The stage prints the 0.2.0 notes while writing CHANGELOG.md, and then commits both the script and the file. Then it checks the release from several angles. git shortlog -sn HEAD counts commits per author (merge commits are included). The changelog.sh 0.1.0 v0.1.0 call uses a range that is only a tag: that means "everything up to 0.1.0", which gives the notes for the very first release. The chore: and test: commits are omitted from the notes by design. The last git describe prints something like v0.2.0-2-g5895965: two commits after the tag v0.2.0, at commit 5895965. That is the usual way to give a development build a version number.

What you practiced

  • Commit structure: independent changes in separate commits, tests with the code they cover, conventional prefixes.
  • Branches: creating, committing, merging and deleting short-lived branches.
  • Merge shapes: a real merge (--no-ff) when branches diverge, and a fast-forward when they do not.
  • Tags and releases: annotated tags on a dedicated release commit, git describe.
  • History as data: revision ranges, --grep, --format and shortlog to build release notes.

Extend the project

If you want more practice, take the stage 4 script and try these on your own (each uses lessons you already know):

  1. Add a quote.sh --random option on a new branch, and make the test deterministic by seeding Bash's RANDOM (RANDOM=42).
  2. Introduce a merge conflict on purpose: edit the same usage line of README.md on two branches, merge them and resolve it (Resolving Merge Conflicts).
  3. Create a release/0.2 branch from v0.2.0, fix a bug there and cherry-pick the fix to main (Cherry-Pick).
  4. Use an interactive rebase to squash two commits before merging a branch.
  5. Turn changelog.sh into a tool that also writes the breaking changes (feat!:), and let the next project, the release automation script, take over the tagging.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the project use --no-ff when merging feature/count?

    --no-ff always creates a merge commit. Here main had also moved on, so a merge commit was needed anyway, but the flag keeps the grouping visible in the history even when it would not be.
  2. 2. What does the range v0.1.0..v0.2.0 select?

    A..B means reachable from B and not from A. It selects the commits of the release regardless of branch layout, and does not depend on dates.
  3. 3. Why does the changelog script use || true on the git log line?

    With set -euo pipefail a failing command aborts the script. When a release has no fix commits the command should simply produce no lines, so the failure is ignored.
  4. 4. What is the benefit of an annotated tag over a lightweight tag for a release?

    An annotated tag is a full object with metadata. git describe ignores lightweight tags by default, which is another reason to use annotated tags for releases.
  5. 5. git describe prints v0.2.0-2-g5895965. What does it mean?

    The format is tag, number of commits since the tag, and g plus the abbreviated hash of HEAD.

Summary

  • Decide conventions up front: conventional commit prefixes, short-lived branches, annotated tags, a test script.
  • Branch for each feature, merge when its tests pass, then delete the branch label; the commits stay in history.
  • --no-ff keeps a merge commit for a feature; --ff-only makes a merge fail rather than create one.
  • Tag releases on a dedicated version-bump commit with git tag -a; git describe names any commit relative to the nearest tag.
  • With consistent messages, git log ranges (A..B), --grep and --format generate a changelog automatically.

Next: Project: Simulating a Team Workflow