Setting up github for a static developer journal
17 Jul 2019
table of contents
Set up an empty Github pages repository on Githubi
- Create a new Github pages repository
- Name your repository
- Mark your repository as public
Create a homepage and see it live on Github pages (terminal)
- Clone your repo pages repository
- Add an index page to your repository
- Stage your index page to be committed
- Commit your index page
- Push your index file to your upstream repository (**READ THIS**)
- Access your Github pages website
Set up a Github Pages repository on Github
Create a new repository
To create a new repository on Github, you can click on the '+' button next to your profile image on the top right hand side of the screen.
Then you can click the 'New repository' button which will bring you to the page where you configure your new repository with a name and privacy details etc.
Name your repository like this: "username.github.io"
Name your repository like this: 'username.github.io' Your username must exactly match the username associated with your Github account for this to work, case sensitive.
Select the 'public' option to mark your repository as public
Your repo can be private, but the Github pages website itself will be publicly accessible to anyone who knows the link, which is easy to find out because it's just your username followed by github.io.
Click on the green 'Create repository' button at the bottom of the page to finish creating your Github pages repository
inish creating your project. After creating your repository, you will be brought to your repositories home page. This page includes instructions for setting up your repository on your local machine.
The instructions in the following instruction shows you how to set up a static webpage with version control. These instructions provide reasons for why you may or may not want to do something, as well as a few tips that should help make your life easier should you decide they could work for you.
Create a homepage and see it live on Github Pages (terminal)
I use the terminal, but you can also use the Github Desktop client if you prefer. Here are instructions for both cases.
Go to the folder where you want to store your repository on your computer
Create a homepage and see it live on Github Pages (terminal):
I use the terminal, but you can also use the Github Desktop client if you prefer. here are instructions for both cases.
I store my project folders in the home directory. When you open up a fresh terminal, you are automatically in the home directory so you don't need to navigate anywhere else like the Desktop to find your folder.
If your are in any other folder, you can navigate directly to the home
directory by running the
Clone your Github Pages repository to your chosen folder
git clone https://github.com/username/username.github.io
Go inside your cloned folder
Instead of typing out the full name of the folder you want to go inside, you can enter the first few characters and hit the 'Tab' key to autocomplete it.
Add and index.html page to your Github Pages repository.
The index file is the home page of your website. We call it an 'index' file because it contains an index that people can use to look up places in your website that they want to visit.
Open your index.html file and add a title to it
Your title can be anything. I wrote a standard 'Hello World!' message. You can add the boilerplate setup later. We just want to see that the Github pages site can display the webpage you have just created.
Stage your index.html file to be committed:
git add index.html
You could also have used `git add .` to add all of your files (in this case there is only one) to be committed. Though I would advise against doing this for two reasons:
- If you add files this way on bigger projects you might accidentally add files that you don't want to commit.
- Or you might end up committing a lot of files with a single commit message, whereas committing them in smaller chunks will allow you to write more meaningful commit messages that express what you were doing better.
Commit your file with a meaningful commit message:
git commit -m "home page available to start sharing dev journal entries"
Most tutorials instruct you to write your first commit message as 'first commit'. The same tutorials tell you that the best commit messages explain why you have done something instead of how you did it, which is contradictory considering the first commit message does not explain why you are making the first commit.
The first commit message is an ideal place to start explaining why you are starting your project. Again this is a personal preference, but one that makes my commit messages read like an interesting story that evolves over time with a meaningful narrative.
You can stage files and commit them in one step by combining the commands with the '&&' operator like this:
git add file.html && git commit -m "commit message"
Push your index.html homepage to your Github Pages website
git push origin master NOT
git push -u origin master
One of the reasons I document everything I learn as I learn it is to make sure that other self-taught devs have access to the same information that I am priviledged to have access to. Hence the detailed explanations about 'why' we do things and what could go wrong with them.
At this point, most tutorials tell you to use `git push -u origin master` to push your changes to the upstream repository, but this command can cause unintended consequences that have been outlined below.
Before we look at the consequences, I'll explain what the `git push -u origin master` command does. This explanation requires an understanding of the difference between a downstream and an upstream repository.
- A downstream repository is a repository that we have copied, cloned or checked out. By cloning a repository, the information contained within the original repository has flowed downstream to us.
- Whenever we make a change to our local repository that we want to share with a main repository (usually hosted on a version control server), we push our changes upstream.
In the 'git push -u origin' command, we are saying:
Push all of the changes we have made in our downstream repository (local copy) to our default upstream repository (that we are about to set). We want our default upstream repository to be the origin of our master branch, or in other words the location where we cloned our repository from.
The '-u' flag sets the default upstream repository to whatever location (branch) is specified.
After we have set our default repository, we no longer need to specify the repository that we want to push/pull our changes to/from. We can just use `git push/pull` instead of `git push/pull origin [branch]`.
While setting the upstream repository seems convenient, it can cause problems depending on what version of Git you are using (especially versions < 2.0), and depending on how Git is configured in the git config file/s.
You can check how Git is configured you can run `git config -l`. To find out what version of Git you are using, you can run `git --version`.
In Git versions before git 2.0, the default settings for 'git push' is to push all branches locally that have the same name on the upstream repository.
You are on the master branch and you make a few changes only to realise that you meant to be on a different branch. So you switch to a different branch, make a few changes and push your changes. You forgot to reset your master branch before you pushed. As the master branch is known to the upstream repository, you have accidentally pushed changes. This is pretty difficult to undo.
The good news is that in Git versions 2.0 and after, the default settings for 'git push' is to only push the branch you are currently working on (if it has the same name on the upstream), which is much better.
That being said, even if the version is current, the Git config settings may have set the default push settings to match an earlier version's way of doing things (possibly because `git push/pull` appears to be more convenient and most tutorials don't teach the problems).
Chances are, you are not going to remember to check the version of Git being used or the config file settings for all of the repositories you are working on.
The safe option then is to push your changes using the 'git push origin [branch]' command.
Using this command means that you are always being explicit (and intentional) about the changes you are pushing to your upstream repository.
You have now pushed your markdown homepage to your Github Pages repository.
Access your live Github pages URL
Open your browser and type in `https//username.github.io`
If you try to access your Github Pages website straight away, you are likely to get a 404 error page. This is because it can take up to 10 minutes for your site to be 'built' and made live by Github.