Publishing on GitHub¶

What is GitHub? GitHub is primarily a place to store code in "repositories". Repositories (or repos for short) are essentially folders, where each folder is a project for one or more applications, libraries, or something else.

Luckily for us, code includes the Viewer and the project.json! Using GitHub is good because there is no limit to the amount of repositories you can create, and they are very generous with storage space, allocating it per repo rather than per account.

Limits¶

GitHub has these limits:

• A recommended limit of 1 GB per repository
• A soft bandwidth limit of 100 GB per month
• A soft build limit of 10 builds per hour, if using the default GitHub Pages (Jekyll), rather than a custom GitHub actions workflow (like Static HTML)
• You are only allowed one account, but you can create unlimited repositories, hosting an unlimited amount of 1 GB subfolders under your custom domain.
• Repos must be public to use GitHub pages (this is fine because project.json files are stored in plaintext anyway)

See here for more info.

Creating an account¶

To create an account, first go to the site here: https://github.com/

That should bring you to this page:

Press the Sign up button in the top right and sign up like you usually would!

You should land on this page now:

Using a Template¶

I've made a nifty GitHub template that comes pre-packaged with:

1. Hyperlinks enabled
2. IntCyoaEnhancer's Download Progress Indicator
3. Optional CSS code in the index.html to:
   • Make your backgrounds static
   • Change the colour of your Point Bar icons
   • Override the background image in the project.json
4. An automatic GitHub workflow to republish your site on any change

It's located here. Text instructions are included in that repository, or you can watch the video below for a short 2 minute tutorial on how to host on GitHub:

Creating a repo¶

If you didn't want to use the template you can instead set up your repository manually. This will show how to do so.

You can create a repo in two ways, by pressing the green New button on the top left, or expanding the + button on the top right, and pressing New repository.

This should open up this form:

Repository name¶

This option is how you select the name of your project. I would recommend naming this after your cyoa, completely lowercase and with dashes instead of spaces (spaces will automatically be converted to dashes by GitHub).

Description¶

As this says, it is optional. It shows to you and anyone viewing your GitHub a short summary of what it's about.

Public or Private¶

Keep this on Public if you're a Free user. Free users cannot host Private repositories (though they can still use them).

Initialize this repository with¶

This just adds useful files on creation of the repo.

Add a README file¶

A README file is a file that contains useful information about a directory and its contents therein. When viewing a repository's code, a README.md (the md meaning Markdown, the markup language that this tutorial is written in) is prettily displayed at the bottom.

I recommend checking this option if you haven't already created a local git repository, as it allows you to give information on the CYOA.

As an example, here is what the README.md of this tutorial looks like:

Learn more about READMEs from GitHub here.

Learn Markdown in a matter of minutes here.

Add .gitignore¶

You can, heh, ignore this. We won't need a .gitignore for the purposes of this tutorial, so just leave it at None.

Choose a license¶

As GitHub says,

A license tells others what they can and can't do with your code.

If you wanted to control how others use your project.json (because no one but MeanDelay has the rights to the Viewer), you can do so using a Licence here.

A couple of common licences include:

For source code (such as the README.md and project.json):

• MIT – You can do anything with it but you have to credit me (by including the licence), and I am not responsible for what you do with it
• AGPLv3 – You can do anything with it but:
  • You have to make it open-source (such as uploading it publicly on GitHub) if you're distributing it
  • You have to include this licence, including copyright notices
  • Serving this over the internet counts as distribution
  • You have to use this licence too
  • You have to state your changes
  • I am not responsible for what you do with it

For content (such as for making a static CYOA or original content inside of the project.json):

• CC BY – You can do anything, but you must credit me
• CC BY-SA – You can do anything, but:
  • You must credit me, and
  • You must use this licence for any derivative works
• CC BY-NC – You can do anything, but:
  • You must credit me, and
  • You cannot use the material commercially
• CC0 – This work is dedicated to the public domain, you can do anything with it!
  • An equivalent for source code is The Unlicense.

Learn about more licences here.

Overall, this only matters if you expect others may want to create derivative CYOAs (such as how Lt Ouroumov's Worm CYOA V6 is a fork of PixelGMS's original).

Additionally, it's a bit of a legal grey area considering you could potentially be hosting copyrighted content such as images and text (if you're adapting someone else's CYOA). To play it safe, you can:

• Attribute images to their authors (asking for permission may not be tenable if the project is large enough or if the authors don't respond)
• Ask for permission from whoever made the original static, and
• Write in your README.md that you are only licensing the unique content in the project.json, such as the Mechanics, Styling, etc

Creating the repo¶

To actually create the repo now, press the Create repository button.

You should now have made a repository!

Uploading files¶

To upload files is easy, simply press the Add file dropdown menu, and select Upload files.

To upload your site, simply upload the Viewer files and your project.json!

Publishing to GitHub pages¶

Now that your site is uploaded, it's time to publish it for the world to see!

There are two methods we will be using in this tutorial: Jekyll and Static HTML. There are pros and cons to both:

Using Jekyll¶

This is the default action that GitHub uses, and it's very easy to set up.

Simply go into Settings → Code and Automation/Pages → Branch → Change None to main → Save.

This will start the build process.

Going back to your repository you should see an orange icon, this indicates that GitHub Actions is working in the background to publish the site.

Pressing on that icon gives you an overview of its status:

And pressing details should give you even more details:

After some time, it will complete:

You should be able to access your CYOA at https://your-user-name.github.io/your-repo-name/ now!

You can repeat this with each and every CYOA you've made, and they will all be available under the subfolders of your special custom domain!

This example will always be available at https://upasadena.github.io/icct-example-cyoa/.

If you want a quick way to get your link, see Adding a link to your project down below.

Using Static HTML¶

If you didn't want to use Jekyll and just wanted to serve the files as-is, this is the option for you!

To start with, go into the Pages menu in the Settings. Select the Source dropdown menu and select GitHub Actions.

You should see two suggestions workflows now. Select Configure under Static HTML:

Then save the file by committing your changes (green button up at the top right).

You should notice it is rebuilding now, and you have a new .github folder:

As you can see here, there is a performance difference, even for such a small repository, so you can be rest assured if you have a massive one, then swapping over to Static HTML will improve the deployment times. This is useful if you want to send out updates to your audience quickly.

Adding a link to your project¶

If you want to quickly get the link to your site and have it ready to press in your repo, you'll want to do this. This is especially useful for newcomers who may want to preview your site, but don't have the time to host it themselves.

Simply press the settings icon in the top right (but NOT the settings tab, a bit below that, to the right of About) → and tick Use your GitHub Pages website.

You can also manually input a website in the Website input field if you were hosting elsewhere.

Unpublishing your site¶

If you ever need to take down the site for some reason, it's simple!

Navigate to Pages in the settings, press the three buttons where it says your site is live, and press Unpublish site.

But your repo is still accessible to the public. You can either:

• Make it private
• Delete it, or
• Do nothing, I just want to unpublish the site only

Configuring your root site¶

If you wanted to configure the very root of your site (Such as https://yourname.github.io/) then it's simple. Just create a repository called yourname.github.io, and activate Pages for that.

Learn more about GitHub Pages here

Releases¶

Releases are, you guessed it, releases. Specifically, they snapshot a version of your project that then becomes immutable, meaning you cannot change it.

They are significant because they allow you to go back to an earlier point at view what it was like then, and, because Releases automatically create tags, you can compare using git diff the difference between the two releases: what changed, what was deleted, and what was added.

You can create "releases" by pressing Create new release in the bottom right, under the Releases header.

Git CLI¶

Git is an incredibly tool that is vast and complex. As such, it is simply untenable to go through each and every aspect of it. Instead, we will go through the very basics in order to get you up and running.

To begin, download the tool from here (if you're on Windows or Mac; if you're on Linux install using your package manager).

After installing, make sure it is in your path by running:

1

git --version

where it should display like so:

Initializing a repository¶

Use the command in the folder you want to initialize:

1

git init

or to initialize it outside of the folder:

1

git init my-interactive/

This display "Initialized empty Git repository" when completed:

And you may notice a hint here if this is your first time using Git. Git repositories can have many "branches", which can be thought of as a branch of a tree. They can split off at any time (and thus are separate) but – unlike real trees, I assume – can also rejoin the original branch, merging them together.

The default branch that Git starts with is master. However, the default branch that GitHub uses is main. I recommend changing it to main:

1

git config --global init.defaultBranch main

You may have noticed --global. There are two levels to Git config settings. There are the global settings, which are the default for each project you use, and repo-specific settings, which override the global ones. So an existing repo using master as the main branch will not be overridden by your default, and you can rest assured.

As it says, to rename your current branch use:

1

git branch -m main

Changing the config¶

Git needs a name and an email in order to commit. Set this up globally like so:

1
2

git config --global user.name "Pasadena"
git config --global user.email "underscore.pasadena@gmail.com"

Remove the global flag for repository-only settings. You can see the current values by simply not typing anything after user.name or user.email.

Tracking files¶

To first do something with Git, you must have files.

Let's create a file right now:

Now let's track the status of our Git repository:

1

git status

As you can see, it knows the file exists, but it is untracked. That means Git will ignore that file.

To individually add the file into the Git repository:

1

git add test_file.txt

To add all files in the current folder recursively, do:

1

git add .

Now let's check the git status again:

Great! The changes made (a new file in the directory) are now ready to be committed.

But what if you want to exclude files from being included (especially useful if you're using git add .)? If you read the earlier sections, you know about the .gitignore file. Creating this and setting rules allows you to ignore files and folders according to patterns. Here are some basic patterns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# This is a comment, it will be ignored, and is used to document what a
# specific thing does

# Ignoring single files
example.txt

# Keeping single files
!example.txt

# Multiple files of the same extension
*.txt

# Multiple files of the same name
example*

# Folders
examples/

# Files inside of folders
examples/example.txt

# Ignoring files in every directory
**/example.txt

See more information at this cheat sheet here.

Making a commit¶

A "commit" is essentially a mini-release. It is you stating that all changes to the repository have been finished, and to officially register all the cumulative changes in the Git repository. Commits only affect tracked files.

To make a commit you must use the git commit command:

1

git commit -m "Your message here!"

The -m flag (short for message) is where you put information about what you changed. GitHub has the message of the very first commit be Initial commit, and has changes to files by default be Update <file name>. The important thing is to be consistent with this.

And you just made your first commit!

Viewing the log¶

You may wish to view the commit history at one point.

To do so, simply type:

1

git log

And it will display lots of information:

For now, it's pretty sparse. But come more commits you'll be able to see more and more.

To view it in a more compact manner, simply type:

1

git log --oneline

to get this:

Downloading a repository¶

Whether you're downloading someone else's repo or your own, the process is the same.

Simply use the clone subcommand:

1

git clone <URL>

For example, this will clone the repository of this tutorial (warning: this tutorial is 324 MB as of v0.15.0):

1

git clone https://github.com/upasadena/interactive-cyoa-tutorial

which will look like this when done:

Using Git clone is important, because it preserves the Git repository. Other methods of downloading may only download the files themselves, rather than with the Git repository.

Uploading to GitHub¶

Now, we'll be assuming that the repository we're uploading to hasn't been initialized yet, and so is empty. If it already has been initialized, clone it, make your changes, commit, then jump to #pushing.

Setting up the remote¶

In order to upload your files to the cloud, Git must first know where it resides. To that end, use the git remote add command:

1

git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPOSITORY-NAME.git

1

git remote add origin https://github.com/upasadena/git-cli-tut.git

Now Git knows where to upload your files!

Pushing¶

To push (upload to the remote), make sure you have at least one commit. Then, do this command:

1

git push -u origin main

1

git push

However, when it asks for your password, do not put in your GitHub password. This is because GitHub fazed out passwords in 2021. Instead, you have to create a personal access token, which is available here.

Pushing with the username and access token looks like so (note that the token being pasted in is not invisible):

Now your repository should change from an empty one:

Into a full one:

Note the lack of a README.md makes it look bare.

Reverting changes¶

Made an irreversible mistake? Don't worry, Git can help (so long as you committed every so often).

First, you need to get the commit ID you wish to revert to, it usually being the last one, so use git log.

1
2
3
4
5
6

$ git log --oneline
0dfd423 (HEAD -> main, origin/main) Another file added!
89e8a4d Update!
2835eb5 Update
1b4bdc3 Update
6db4a53 Initial commit

To revert to the last commit, simply put in the ID of the commit that you want to revert to with the format git reset <ID>:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

$ git log --oneline
0dfd423 (HEAD -> main, origin/main) Another file added!
89e8a4d Update!
2835eb5 Update
1b4bdc3 Update
6db4a53 Initial commit
$ git reset 89e8a4d
Unstaged changes after reset:
M       another_file.md
$ git status
On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   another_file.md

no changes added to commit (use "git add" and/or "git commit -a")

As we can see, we reversed the commit. However, we did not reverse the changes we made, only the fact that a commit happened. In order to that, we attach the --hard flag to the command:

1

git reset <ID> --hard

Which, as we can see, removes the file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ git log --oneline
2835eb5 (HEAD -> main) Update
1b4bdc3 Update
6db4a53 Initial commit
$ ls
another_file.md  icct  test_file.txt
$ git reset 1b4bdc3 --hard
HEAD is now at 1b4bdc3 Update
$ ls
icct  test_file.txt

Putting it all together¶

After making changes it should look like this:

1
2

git add .;git commit -m "Update!"
git push

And you're all set! You should now know the basics of GitHub and Git, and how to use them to host your CYOAs!

Comments