Git, GitHub, and Phoenix Code Guide

This guide covers the essential tools and workflows you'll use throughout this course.

What Each Tool Does

Phoenix Code is your code editor - where you write HTML, CSS, and JavaScript.

Git is version control software that tracks changes to your files over time. It's like "track changes" for code, but much more powerful.

GitHub is a website that hosts Git repositories online. It provides:

Think of it this way:

Setting Up Phoenix Code

Installation

  1. Download Phoenix Code from phcode.dev
  2. Install it on your computer (Mac or Windows)
  3. Open Phoenix Code

You should be greeted with the Start Project Dialog, which provides quick access to create new projects or open existing ones.

Your First Project

We'll set up your first project in class, but here's the workflow you'll use:

For Class 1 (Using the Template):

  1. Go to GitHub.com and log into your account
  2. Navigate to the teacher's template repository
  3. Click Use this template to create your own copy
  4. Name your new repository (e.g., "personal-landing-page")
  5. In Phoenix Code, click Start Project button (or File > Git > Clone)
  6. Select Get from Git
  7. Enter your repository's SSH URL (looks like git@github.com:yourusername/repo-name.git)
  8. Choose where to save the project on your computer
  9. Click Create Project

For Future Projects (New Builds):

  1. Go to GitHub.com and navigate to the appropriate template repository (your teacher will provide the link)
  2. Click Use this template to create your own copy
  3. Name your new repository appropriately (e.g., "build-1-article")
  4. In Phoenix Code, click Start Project button (or File > Git > Clone)
  5. Select Get from Git
  6. Enter your repository's SSH URL (looks like git@github.com:yourusername/repo-name.git)
  7. Choose where to save the project on your computer
  8. Click Create Project
  9. Start building!

Why templates? Using templates ensures you start with proper HTML5 structure and keeps your workflow consistent. Your teacher will explain what each part of the template does so you understand the foundation you're building on.

Important: We'll be using SSH keys for authentication, so you won't need to enter a username and password. Your teacher will help you set up SSH keys during class.

Understanding Git Basics

The Git Panel

When working with a Git repository, Phoenix Code displays a Git icon in the toolbar. Click it to open the Git Panel, which shows:

Each file has a status indicator and options to view changes (diff), discard changes, or delete.

The Basic Workflow

Your daily workflow will look like this:

  1. Edit files in Phoenix Code
  2. Stage changes (select which changes to save)
  3. Commit (save a snapshot with a message)
  4. Push (upload to GitHub)

That's it! Let's break down each step.

Making Changes and Committing

1. Edit Your Files

Work in Phoenix Code as normal. As you make changes, you'll see them appear in the Git Panel with a "Modified" status.

Tip: Use Live Preview (lightning bolt icon) to see your changes in real-time as you code.

2. Stage Your Changes

Before committing, you need to stage your changes - tell Git which changes you want to include in this commit.

To stage all files:

To stage individual files:

Why stage? Sometimes you've changed multiple files but only want to commit some of them. Staging gives you control.

3. Commit Your Changes

A commit is a snapshot of your project at a specific point in time. Each commit needs a message explaining what changed.

  1. Click the Commit button
  2. Enter a commit message in the dialog box
    • First line: Brief summary (50 characters or less)
    • Optional: More detailed explanation below
  3. Click Commit

Good commit messages:

Bad commit messages:

Your commit message should answer: "If applied, this commit will..."

Important: Your teacher uses commit messages to track your progress and evaluate your development process. Clear, descriptive commit messages demonstrate professional work habits and help document your learning journey. Make every commit message count!

4. Push to GitHub

After committing locally, your changes are saved on your computer but not yet on GitHub. To publish them:

  1. Click the Push button in the Git Panel
  2. Verify the settings in the Push dialog (usually defaults are fine)
  3. Click Push

Your changes are now on GitHub and will appear on your published GitHub Pages site after a few moments.

Viewing Changes and History

Seeing What Changed (Diff)

Before committing, you can review exactly what changed in each file:

  1. Find the file in the Git Panel
  2. Click the diff icon next to it
  3. The diff dialog shows:
    • Green lines = added content
    • Red lines = removed content

This helps you verify you're committing what you intend.

Viewing History

Phoenix Code provides two history views:

Show History - See all commits to the entire project

Show File History - See commits that changed a specific file

Click on any commit to see exactly what changed in that commit.

Working with Branches (Advanced)

For most of this course, you'll work on the main branch. However, branches are useful for trying out ideas without affecting your main work.

Creating a Branch

  1. Click the branch name in the Git Panel (e.g., "main")
  2. Select Create new branch...
  3. Choose which branch to create from (usually "main")
  4. Name your new branch (e.g., "experiment-with-colors")

You're now on the new branch. Any commits you make won't affect main until you merge.

Switching Branches

  1. Click the current branch name
  2. Select the branch you want to switch to

Merging Branches

When you're happy with changes in a branch and want to bring them into main:

  1. Switch to the branch you want to merge into (usually main)
  2. Click the branch name to open the branch menu
  3. Click the merge icon next to the branch you want to merge
  4. Review the merge dialog and click Merge

Common Tasks

Discarding Changes

Made a mistake and want to undo uncommitted changes?

For a single file:

  1. Find the file in the Git Panel
  2. Click Discard Changes... button
  3. Confirm - this will revert the file to the last commit

For all files:

  1. Click the three dots at top-right of Git Panel
  2. Select Discard all changes since the last commit...

⚠️ Warning: Discarding changes is permanent - they can't be recovered.

Reverting to an Earlier Commit

Sometimes you need to go back to a previous version of your project. Your teacher will walk you through this process when needed, as it involves a few steps:

  1. Open the Show History panel in Git
  2. Find the commit you want to revert to
  3. Your teacher will guide you through the revert process

Note: This is different from discarding uncommitted changes. Reverting affects committed work and requires care to avoid losing important changes.

Pulling Changes

If you're working on multiple computers or collaborating with others, you'll need to pull changes from GitHub before you start working:

  1. Click Pull in the Git Panel
  2. Review the Pull dialog (defaults are usually fine)
  3. Click Pull

This downloads any changes from GitHub and merges them into your local project.

Best practice: Always pull before starting work and before pushing.

GitHub Pages Publishing

GitHub Pages automatically publishes your website from your GitHub repository. Here's how to set it up:

Initial Setup (Done Once)

  1. Go to your repository on GitHub.com
  2. Click Settings tab
  3. Scroll to Pages section (in the left sidebar under "Code and automation")
  4. Under Source, select the branch to publish (usually "main")
  5. Select the folder to publish (usually "/ (root)" or "/docs")
  6. Click Save

After a few minutes, your site will be live at: https://yourusername.github.io/repository-name/

Updating Your Published Site

Once GitHub Pages is set up, every time you push to GitHub, your site automatically updates within a few minutes. That's it!

To verify your changes published:

  1. Go to your repository on GitHub.com
  2. Click Actions tab
  3. You should see your latest commit being deployed
  4. Once the green checkmark appears, your changes are live

Troubleshooting

"Git is not installed"

Phoenix Code needs Git installed on your computer. Download it from git-scm.com/downloads and install it, then restart Phoenix Code.

"Pushing to remote failed"

This usually means there are changes on GitHub that you don't have locally.

Solution:

  1. Click Pull to get the latest changes
  2. Then try pushing again

"Authentication failed"

In this class, we use SSH keys for authentication. Your teacher will help you set up SSH keys during Class 1. Once configured, you won't need to enter credentials when pushing or pulling.

If you get authentication errors:

  1. Make sure you're using the SSH URL (starts with git@github.com:) not the HTTPS URL
  2. Verify your SSH keys are set up correctly - ask your teacher for help
  3. Check that you have permission to access the repository (it should be in your GitHub account)

Files not appearing in Git Panel

Make sure:

  1. Git is initialized (File > Git > Init)
  2. You're in the correct project folder
  3. Click Refresh Panel to update the view

Can't see Git icon in toolbar

The Git icon only appears when you have a Git repository open. Either:

Keyboard Shortcuts

Speed up your workflow with these shortcuts:

Action Windows/Linux Mac
Save file Ctrl+S Cmd+S
Live Preview Ctrl+Alt+P Cmd+Alt+P
Find in file Ctrl+F Cmd+F
Find in files Ctrl+Shift+F Cmd+Shift+F

For more shortcuts: View > Show Keyboard Shortcuts

Additional Resources

Tips for Success

  1. Commit often - Small, frequent commits are better than large, infrequent ones
  2. Write clear messages - Your future self will thank you
  3. Pull before you push - Avoid conflicts by staying up to date
  4. Use Live Preview - See your changes instantly while coding
  5. Check the diff - Review what you're committing before you commit it
  6. Back up your work - Push to GitHub regularly so your work is safe in the cloud

Questions? Ask in class or check the Phoenix Code docs linked above.