Set up a safe playground
Beginner Git CLI VS Code UI IntelliJ UI GitLab UI GitHub UI
Why this matters
You cannot learn Git by reading, and you must not learn it on your team's real project. The playground is a small, realistic project made for breaking: documentation to edit, data to change, a program to run, tests that can fail. Every "Try it yourself" and every lab uses it. When something goes wrong, you delete the folder and start again in one minute.
What the playground is
Trailguide is a tiny command-line program that prints hiking trails for the fictional Northwind Trails company. It has everything a real project has, in miniature:
| Path | What it is | You will |
|---|---|---|
README.md |
What the project is and how to run it | edit it in Lab 2 |
CONTRIBUTING.md |
The team's rules for branches, commits and merge requests | follow it from Section 6 on |
docs/getting-started.md, docs/faq.md |
Documentation in Markdown | edit, review and resolve conflicts in |
data/trails.csv |
The trails: name, region, distance, difficulty | add rows to |
src/trailguide.py |
The program (Python, no extra packages) | run, and make one small fix in Lab 6 |
tests/test_trailguide.py |
Three automated tests | run, and watch fail when something breaks |
.gitlab-ci.yml, .github/workflows/ci.yml |
The automated checks that run on every push | read in Section 14 |
.gitignore |
Files Git must never track | read in Section 4 |
Get the files
- Download trailguide.zip (about 10 KB).
- Create a practice folder in your home folder, called
git-practice, if you did not create it in Lab 1. - Unzip the archive into it: on macOS double-click the file in Finder and move the
trailguidefolder intogit-practice; on Windows right-click → Extract All… and choosegit-practice; on Linuxunzip trailguide.zip -d ~/git-practice. - Check that you now have
~/git-practice/trailguide/README.md(on Windows:C:\Users\you\git-practice\trailguide\README.md).
Turn it into a repository
The folder is just files. Three commands make it a repository with one commit; you will run these same three commands at the start of every new project of your own.
$ cd ~/git-practice/trailguide
$ git initInitialized empty Git repository in /Users/you/git-practice/trailguide/.git/$ git add .
$ git commit -m "Initial import of trailguide"[main (root-commit) 216f956] Initial import of trailguide
12 files changed, 324 insertions(+)
create mode 100644 .github/workflows/ci.yml
create mode 100644 .gitignore
create mode 100644 .gitlab-ci.yml
create mode 100644 .markdownlint.json
create mode 100644 CONTRIBUTING.md
create mode 100644 README.md
create mode 100644 data/trails.csv
create mode 100644 docs/faq.md
create mode 100644 docs/getting-started.md
create mode 100644 docs/images/logo.svg
create mode 100644 src/trailguide.py
create mode 100644 tests/test_trailguide.pyYour hash (216f956 here) will differ. If git init mentions a branch called master, run git branch -m main before committing, and set the default for the future with git config --global init.defaultBranch main.
- File → Open Folder… and choose
git-practice/trailguide. If VS Code asks whether you trust the authors, choose Yes — it is your own folder. - Open the Source Control view (Ctrl+Shift+G / ⌃⇧G) and click Initialize Repository.
- All files now appear under Changes with the letter U. Click the + next to the Changes heading to stage them all.
- Type
Initial import of trailguidein the message box and click Commit (or press Ctrl+Enter / ⌘Enter). - The list empties; the status bar at the bottom left shows
main.
- File → Open… and choose
git-practice/trailguide. Choose Trust Project if asked. - In the menu, VCS → Create Git Repository… (in some versions VCS → Enable Version Control Integration…, then pick Git). Confirm the folder.
- Open the Commit tool window (Alt+0 / ⌘0). Tick the Unversioned Files group to include every file.
- Type
Initial import of trailguideas the message and click Commit. - The branch name
main(ormaster) appears in the status bar at the bottom right. If it saysmaster, use Git → Branches… → Rename to call itmain.
GitLab is not needed for Lab 1, but Labs 2 to 6 push this repository to a private project of your own. Create it now so it is ready:
- Sign in at gitlab.com (or your company's GitLab). Click New project (top right, or the + menu) → Create blank project.
- Project name:
trailguide. Leave the project slug as suggested. - Visibility level: Private. Only you can see it.
- Untick "Initialize repository with a README" — you will push the repository you just created on your computer, and a README on the server would conflict with it.
- Click Create project. GitLab shows a page with "Push an existing Git repository" instructions; ignore them for now, Lab 2 walks through them.
GitHub is the alternative for Labs 2 to 6 if your team uses it. Create a private repository of your own:
- Sign in at github.com. Click the + at the top right → New repository.
- Repository name:
trailguide. - Choose Private.
- Leave Add a README file,
.gitignoreand license unticked — the repository you created on your computer already has them. - Click Create repository. GitHub shows "…or push an existing repository from the command line"; Lab 2 uses exactly those lines.
Run the program and the tests
Make sure the playground works before you start changing it. From a terminal inside the trailguide folder:
$ python3 src/trailguide.py --listRidge Loop North 7.5 km moderate
Silver Lake Walk North 4.2 km easy
Eagle Summit North 14.8 km hard
Harbour Path Coast 6.1 km easy
Lighthouse Trail Coast 9.3 km moderate
Old Mill Way East 5.4 km easy
Pine Valley Circuit East 11.7 km moderate
Sunset Crag West 12.9 km hard
Meadow Stroll West 3.6 km easy
Twin Falls Track South 8.8 km moderate
10 trail(s)$ python3 -m unittest discover -s tests -vtest_format_trail_shows_distance_with_one_decimal (test_trailguide.TrailguideTests.test_format_trail_shows_distance_with_one_decimal) ... ok
test_loads_ten_trails (test_trailguide.TrailguideTests.test_loads_ten_trails) ... ok
test_longest_is_eagle_summit (test_trailguide.TrailguideTests.test_longest_is_eagle_summit) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OKIf python3 is not found on Windows, try python instead; Git Bash and PowerShell both work. If Python is missing entirely, install it from python.org (tick "Add to PATH" on Windows).
When you break it
You will, on purpose and by accident. Two levels of reset:
- Undo uncommitted edits (keeps your commits):
git restore .throws away every change since the last commit, andgit clean -fddeletes new files and folders you created. Both are irreversible for uncommitted work — which is the point in a playground. - Start completely over: delete the whole
trailguidefolder and unzip the archive again, then repeat "Turn it into a repository".
Try it yourself
Goal: make one change to the playground, see Git notice it, and put it back.
- Open
docs/faq.mdin your editor and add a line at the end, for exampleLast updated by me. - In the terminal, run
git status -s. - Put the file back exactly as it was:
git restore docs/faq.md, then rungit status -sagain.
Expected result: after step 2 the output is M docs/faq.md (modified, not staged). After step 3 the output is empty: the working tree is clean again.
Show solution
$ printf '\nLast updated by me.\n' >> docs/faq.md
$ git status -s M docs/faq.md$ git restore docs/faq.md
$ git status -sgit status -s prints nothing: no differences, nothing to report.