Git & GitHub
collaboration.

You’ll build The silent station, a tiny Markdown adventure. Mara creates a forest path. Leo creates a tower path. You’ll bring both into one story, then repeat the workflow with a small edit.

Your starting checklist

• Have VS Code, Git, and a GitHub account ready.
• Use your established GitHub sign-in and commit identity. You need access to the demo repository. Ask for help if authentication is not ready.
• In VS Code, choose Terminal → New Terminal to check Git below. The next section explains exactly where to create your project folder and run the clone command.
• Keep this guide and GitHub open beside VS Code. Run commands one line at a time and read the output.

git --version

A version number means Git is available. If the command is not found, install Git using the link above, restart VS Code, and ask for help if it still fails.

Give everyone the same first commit before any branch starts its own adventure.

1. Create the repository on GitHub · owner only

1. Sign in to GitHub. In the upper-right corner, open the + menu and choose New repository. You can also open the Create a new repository page.
2. Under Owner, select the account that will own this demo. Under Repository name, enter webdev4-git-live-demo. If that name is already in use in your account, use an unused name such as webdev4-git-live-demo-2; use the actual name consistently when sharing its URL.
3. In Description, enter: MTM6407 Week 1: a collaborative Markdown story for practising branches, pull requests, and merge conflicts.
4. Choose the visibility indicated by the professor. Leave Add README off, choose No .gitignore, and choose No license (or leave those starter checkboxes unchecked if your layout uses checkboxes). Select Create repository.

2. Find the new-file link and write intro.md · owner only

1. On the new repository’s page, select the Code tab at the top if it is not already selected.
2. Scroll past the Start coding with Codespaces and Add collaborators to this repository cards, if shown. Find the box headed Quick setup — if you’ve done this kind of thing before.
3. Look directly below the HTTPS / SSH repository address in that box. The sentence starts Get started by. Click the small blue creating a new file link. It is a text link, not a large button.

4. In the file editor, find the filename field at the top, often labelled Name your file…. Enter exactly intro.md: lowercase, no spaces, and no folder name before it.
5. Click Copy on the story block below. Click the large text editor under the filename and paste with ⌘V or Ctrl+V. If there is existing text in the editor, select that text first and replace it. Keep the #, blank line, and final question exactly as shown.
6. Choose Preview above the editor if available. Expect a heading, “The lights go out.”, and “What do you do next?” There should be no forest or tower choices yet.

# The silent station

The lights go out.
What do you do next?

3. Save the first commit · owner only

1. Above the editor, choose the green Commit changes… button. This opens the commit dialog; the file is not saved to the repository yet.
2. In Commit message, replace the suggested message with Start the station story. The extended description can stay empty.
3. If GitHub shows branch options, choose Commit directly to the current branch (normally main). If its name differs, finish this first commit, then follow The first branch has a different name below before anyone clones. Do not create a feature branch or pull request for this starting file. An empty repository may not show branch options.
4. Choose the green Commit changes button inside the dialog. Wait for GitHub to return to the repository or file page.
5. Select the repository’s Code tab. Confirm that intro.md appears in the file list and that the branch selector above the list says main. Open intro.md and check the three story lines again. Everyone must start from this same committed version.

4. Give your partner access · pairs only

1. The owner opens the repository’s Settings tab, then Collaborators in the left sidebar. GitHub may ask the owner to confirm their sign-in.
2. Choose Add people, enter the partner’s exact GitHub username, select the correct account, and choose Add [username] to this repository.
3. The invited partner signs in to their own account and accepts the repository invitation from their GitHub notification or invitation email. The owner checks that the invitation is no longer pending.
4. Share this repository’s URL with the partner. Both contributors work in this same repository; the partner does not create another repository or a fork. A public repository can be read by anyone, but a collaborator invitation is still needed to push changes.

Working alone? Skip invitations. The owner already has access and does not invite themselves.

5. Clone into VS Code · each contributor

1. On GitHub, return to the repository’s Code tab after the first commit. Above the file list, open the green Code button. In its Local tab, choose HTTPS, then use the copy icon beside the address ending in .git.
2. Paste that address into the field below to prepare your clone command. Use the shared repository’s HTTPS URL, not a file page, password, or token.
3. On your computer, use Finder on Mac or File Explorer on Windows to create a folder named MTM6407 inside Documents if you do not already have one.
4. In VS Code, choose File → Open Folder…, select Documents → MTM6407, and open it. This is the parent folder. Do not create adventure-demo yourself; Git will create it. If that folder already exists from an earlier attempt, ask the professor to help inspect or reuse it before continuing.
5. Choose Terminal → New Terminal in VS Code. Run the generated git clone line below and wait for it to finish. Complete the browser sign-in if your configured Git authentication opens one. Only after the clone succeeds, run cd adventure-demo.

Used only on this page. Copying the clone command becomes available when the URL is valid.

git clone <repository-url> adventure-demo
cd adventure-demo

6. In VS Code, choose File → Open Folder… again. This time select Documents → MTM6407 → adventure-demo and open it. In the left-hand Explorer, you should now see intro.md.
7. Choose Terminal → New Terminal inside this opened repository folder. Run the checks below. Expect main, a clean working tree, and the shared GitHub repository URL for origin. If any check differs, ask the professor before creating a branch.

git branch --show-current
git status
git remote -v

6. Create and publish Mara’s branch · Mara only

Following along alone? Run this block now. Working as a pair? Only the person playing Mara runs it. Leo keeps their own clone on main and waits until Merge the tower path first. Do not publish two copies of Mara’s branch from separate clones.

git switch -c demo/mara-forest
git push -u origin demo/mara-forest
git branch --show-current

Create a change your teammate can review: one new choice and the page it opens.

1. Check the branch, then edit

git status
git branch --show-current

Confirm demo/mara-forest. In VS Code, replace all of intro.md with the first block. Create forest.md beside it and paste the second block. Save both files.

# The silent station

The lights go out.
[Enter the forest](forest.md)

# The forest

A narrow path leads between the trees. Footsteps stop when you stop.

[Enter the forest](forest.md) is a relative Markdown link: the brackets hold the label and the parentheses hold the destination filename. Preview intro.md in VS Code and follow the forest link.

2. Inspect, stage, commit, and push

git diff
git add intro.md forest.md
git diff --staged
git commit -m "Add forest choice and scene"
git push

git diff shows changes to tracked files; the new forest.md appears in git status before staging. After git add, check git diff --staged for both the link and the new scene. If Git opens a scrolling view, press q to return to the prompt.

3. Open Mara’s pull request on GitHub

1. Choose Pull requests → New pull request.
2. Set base: main and compare: demo/mara-forest, then choose Create pull request.
3. Use the title and suggested description below. Only keep the testing claim after actually checking the link.
4. Below the description, choose the green Create pull request button to submit the form. Confirm the new PR page shows Open. Filling in the form alone does not open the PR.

Add the forest path

Adds a forest choice to intro.md and a new forest.md scene.

Checked: I opened intro.md on demo/mara-forest and followed the forest link to the new scene.

Open Files changed to inspect the difference. Then browse the repository on demo/mara-forest, open the rendered intro.md, and test the link there too.

Leo starts from the original story and changes the same line. Main still has no forest choice.

1. Create Leo’s branch from original main

git status
git switch main
git switch -c demo/leo-tower
git push -u origin demo/leo-tower

Check that intro.md still asks “What do you do next?” Replace it with Leo’s version and create tower.md in the same folder. Save and preview the tower link.

# The silent station

The lights go out.
[Climb the tower](tower.md)

# The tower

A spiral staircase rises above the tracks. A light flashes from the top window.

git diff
git add intro.md tower.md
git diff --staged
git commit -m "Add the tower choice and scene"
git push origin demo/leo-tower

2. Open and review Leo’s PR

On GitHub, choose Pull requests → New pull request. Set base: main and compare: demo/leo-tower, then choose Create pull request to open the form. Fill in the title and description below after checking the story link. Choose Create pull request again below the description to submit the form. Confirm that the PR page says Open.

Add the tower path

Adds a tower choice to intro.md and a new tower.md scene.

Checked: I opened intro.md on demo/leo-tower and followed the tower link to the new scene.

1. A real teammate opens Files changed. Check filenames, the exact link target, and whether the scene makes sense.
2. Open the story on demo/leo-tower and follow the tower link. Looking at main would show the older story.
3. Give specific feedback. To submit a formal review, choose Review changes, select the appropriate review option, and choose Submit review. Pending review comments are not shared until submitted.
4. If something needs fixing, the author edits on demo/leo-tower, commits, and pushes. The same PR updates.

Visual help: where to submit a GitHub review

On your teammate’s pull request, inspect Files changed, choose Review changes, and submit the appropriate review. Review the actual story links as well as the text difference.

3. Merge Leo first

1. After review, choose Create a merge commit from the merge options, then Merge pull request → Confirm merge. This demo uses merge commits throughout.
2. Confirm that the PR says Merged, then choose Delete branch for demo/leo-tower.
3. Open intro.md on GitHub’s main. The tower choice is present. Return to Mara’s open PR and inspect its conflict status.

A conflict is a decision point. Write a combined introduction that gives the reader both choices.

1. Bring shared main into Mara’s branch

git status
git switch demo/mara-forest
git status
git fetch origin
git merge origin/main

Begin with a clean working tree. The last command should stop with a content conflict in intro.md. tower.md normally arrives and stages automatically. The merge is still unfinished.

2. Read the conflict markers

Open intro.md in VS Code’s text editor. If the merge editor opens instead, you can right-click the file in Explorer and choose Open With… → Text Editor to inspect the raw text.

# The silent station

The lights go out.
<<<<<<< HEAD
[Enter the forest](forest.md)
=======
[Climb the tower](tower.md)
>>>>>>> origin/main

3. Resolve the file

Propose the finished text first. Then expand the reference below and replace intro.md with the combined version. Leave forest.md and tower.md intact.

# The silent station

The lights go out.
What do you do next?

- [Enter the forest](forest.md)
- [Climb the tower](tower.md)

Save the file. Preview it in VS Code and follow both links. Confirm there are no <<<<<<<, =======, or >>>>>>> markers left.

Visual help: VS Code’s optional 3-way merge editor

Open the conflicted file from Source Control and choose Resolve in Merge Editor. Compare Incoming and Current; edit Result to match the combined introduction above. Complete Merge stages the resolved file. Continue with the inspection and commit commands below.

Accepting both changes may still need editing. Restore the question and format each choice as its own list item.

4. Finish and share the resolution

git diff --check
git add intro.md
git diff --staged
git diff --staged --check
git status
git commit -m "Resolve story choices"
git push

Check the staged result before committing. The checks should report no problems. On GitHub, open Mara’s existing PR: it updates automatically. Review its current difference and test both story links on demo/mara-forest.

Bring the reviewed story into main and update the copy on your computer.

1. Finish Mara’s PR on GitHub

1. Review the updated Files changed and test both links on the proposed branch. Use a real teammate for any required approving review.
2. Use Create a merge commit, then confirm the merge. Check the PR says Merged.
3. Choose Delete branch for remote demo/mara-forest.
4. Open intro.md on GitHub’s main and follow both paths.

2. Update local main

git status
git switch main
git pull --ff-only origin main
git fetch --prune origin

If git status shows unfinished work, stop before switching. After the pull, local main should contain both story choices.

3. Delete only the completed local branches you own

For the single-clone instructor demo, both branches exist locally:

git branch -d demo/mara-forest
git branch -d demo/leo-tower
git status

A one-sentence change gets the same care: a fresh branch, a clear commit, a pull request, and a review.

1. Start from updated main

git status
git switch main
git pull --ff-only origin main
git switch -c demo/mara-edit

Replace only forest.md with the version below. It adds one lantern sentence. Save and preview the forest scene.

# The forest

A narrow path leads between the trees. Footsteps stop when you stop.

In the distance, a lantern moves between the trees.

2. Inspect, commit, and publish the new branch

git diff
git add forest.md
git diff --staged
git commit -m "Add a lantern detail to the forest scene"
git push -u origin demo/mara-edit

3. Repeat the PR and review cycle

On GitHub, choose Pull requests → New pull request. Set base: main and compare: demo/mara-edit, then choose Create pull request. Fill in the title and description below after checking the forest path. Choose Create pull request again below the description to submit the form, and confirm that the PR says Open.

Add a lantern detail to the forest scene

Adds a lantern sentence to forest.md.

Checked: I opened intro.md on demo/mara-edit, followed the forest path, and confirmed the new sentence appears.

Review Files changed and the forest path on the branch. Merge using Create a merge commit, confirm Merged, and delete remote demo/mara-edit.

4. Finish locally

git status
git switch main
git pull --ff-only origin main
git fetch --prune origin
git branch -d demo/mara-edit
git status
git log --oneline --graph --decorate -10

Open the final intro.md, follow both paths, and check the new lantern sentence. Your working tree should be clean. The graph shows the contribution history; press q if the log opens in a pager.

Now apply the workflow to a story your team creates. Work in a group of 3 or 4, use one repository, and complete two contribution cycles per person.

1. 1

   Setup

   Create the shared repository and intro.md. Arrange collaborator access and accept invitations. Create each member’s branch from the shared starting point.

2. 2

   Expand

   Each member adds a new path and opens one pull request. Keep the link and destination file together in the contribution.

3. 3

   Review

   Review each other’s work, resolve any conflicts, merge, delete completed branches, and synchronize main.

4. 4

   Edit

   Each member starts a fresh branch from current main and makes one small story change. Commit, push, and open another PR.

5. 5

   Review and submit

   Review and merge the second-round changes. Delete completed branches, sync main, test the story, and submit the repository URL.

Names that tell your team what changed

Use your GitHub username in assignment branches. The examples below illustrate the pattern; replace the username and story topic with your own.

The demo repository name and demo/mara-forest branches are classroom examples. Follow Brightspace for any additional repository naming, visibility, story, rubric, or submission requirements.

Before your team submits

• Every member, including the leader, completed both contribution cycles.
• Your team reviewed and merged the intended PRs.
• The story on main has working relative links, exact filenames, and no conflict markers.
• Completed branches are cleaned up and team members synchronized main.
• The repository is accessible as required by the assignment, and you have the correct URL to submit.

Read the message first. It is usually telling you which assumption needs checking.

Your “where am I?” toolkit

git status
git branch --show-current
git branch
git remote -v
git diff
git diff --staged

When asking for help, share the step number, current branch, and exact error. Keep credentials out of screenshots.

Use the exact story snapshots as a reference while you practise.

Copy only the contents of the named file when the relevant step tells you. Do not add the numbered snapshot folders to your story repository. Keep the resolution closed until you have proposed your own answer.