HERON
Get started

Basics · 4

Git and GitHub

Git keeps the history of every change in your site folder. GitHub keeps a copy of that folder online and builds the site when you send changes. This page sets up both, from a new account to your first push.

About twenty minutes. You can build and look at a site without git, so come back to this page when you want to store the history of your content. Git is the best place to keep a site's content; publishing is a separate choice.

In plain words

Git is a program that takes snapshots of a folder. Each snapshot, a commit, remembers what changed, when and why. You can look back at any snapshot and undo a change, even weeks later.

GitHub is a website that stores your folder with all its snapshots, called a repository. When you send new snapshots there, a push, GitHub can build a fresh image of your site by itself (GitHub Actions) and store it next to the code (GitHub Container Registry): no extra accounts. With HERON Agent (paid) that image is then also updated on your server. Other ways to publish are on Publish.

An everyday comparison: git is the "track changes" mode of a document that never forgets. GitHub is the shared drive where that document lives, with a robot that prints a fresh copy every time you save.

When you need this page: before publishing with git push or on GitHub Pages. When you can skip it: if you publish by copying files to a hosting yourself.

Words you will meet

WordMeaning
repositoryYour site folder together with its whole history. On GitHub it has an address like github.com/you/my-site
commitOne saved snapshot with a short note: "New page about prices"
pushSending your new commits to GitHub
pullGetting commits from GitHub to your computer
branchA parallel line of history. Your main one is called main
tokenA long password for programs, which you can limit and revoke
GitHub ActionsGitHub's robot that runs a build after each push

Install git

Tell git who you are

Every commit carries a name and an email. Set them once on each computer. Use the email of your GitHub account, or GitHub's private no-reply address from Settings → Emails.

git config --global user.name "Anna Smith" && git config --global user.email "anna@example.com" && git config --global init.defaultBranch main

Create a GitHub account and a repository

  1. 1

    Sign up

    On github.com press Sign up, enter your email, a password and a user name. The user name becomes part of your addresses: github.com/your-name.
  2. 2

    Create a repository

    The plus sign at the top right → New repository. Name it like your site, for example my-site. Leave "Add a README" unticked: your folder already has files.
  3. 3

    Private or public

    Private hides your drafts. Public is required for free GitHub Pages on a free account. You can change it later in the repository settings.
  4. 4

    Copy the address

    GitHub shows the address of the empty repository, like https://github.com/your-name/my-site.git. You need it in the next step.

Create a token

GitHub does not accept your account password from the terminal. You use a token instead: a long password that only works for what you allow and that you can revoke at any time.

First push

In the terminal go to your site folder and run this, with your user name instead of your-name:

git init && git add . && git commit -m "First version" && git branch -M main && git remote add origin https://github.com/your-name/my-site.git && git push -u origin main

What each part does:

  • git init turns the folder into a repository;
  • git add . marks every file for the snapshot;
  • git commit -m "First version" takes the snapshot with a note;
  • git branch -M main names the main line main;
  • git remote add origin … remembers where GitHub is;
  • git push -u origin main sends everything.

Git asks for a user name and a password: type your GitHub user name and paste the token as the password. Nothing appears while you paste, that is normal. On macOS the keychain remembers it; on Linux and WSL run git config --global credential.helper store once to keep it.

Refresh the repository page on GitHub: your files are there. If the site folder has .github/workflows/, open the Actions tab and watch the first build.

Every change after that

  1. 1

    Edit

    Change a page in the editor and save.
  2. 2

    Look

    Check it at localhost:8000.
  3. 3

    Snapshot and send

    git add . && git commit -m "Prices updated" && git push
  4. 4

    Wait a minute

    GitHub builds the site. A green tick in the Actions tab means done, a red cross shows what went wrong.
  5. 5

    Check the live site

    Open your address and refresh.

Without the terminal: GitHub Desktop

If you prefer buttons, install GitHub Desktop from desktop.github.com (macOS and Windows). Sign in with your GitHub account: no token needed. File → Add local repository → choose the site folder → Publish repository. After that every change appears in the app: write a note, press Commit, then Push origin. VS Code has the same buttons in its Source Control panel.

Questions

Is GitHub free?

Yes for private and public repositories. GitHub Actions has free build minutes every month, which is plenty for a site. GitHub Pages on a free account needs a public repository.

I committed a password by mistake. What now?

Revoke it at once where it was issued (GitHub token page, Docker Hub, the service it belongs to) and create a new one. Deleting the file is not enough: it stays in the history.

What is .gitignore?

A list of files git should not save, like the built dist/ folder and HERON's cache. New HERON sites come with one.

Can I use GitLab or my own git server?

Yes. Git works the same. The automatic build file is written for GitHub Actions; other services need their own. See Publishing.

What next?

Publish the site: git push, or for free on GitHub Pages with your domain.