9GitHub

More of the basics; some of this we’ve done before and a lot of it is fairly obvious; I’m just going through it in a more structured manner.

There is only one thing to say about creating and editing files within GitHub: don’t do it.

It is generally better to modify the files locally (in Brackets) and push the changes up to the remote GitHub repository. This is the best practice method for using Git and GitHub.

That said, virtually everybody will at some point modify files in GitHub and this is how you do it.

Let’s go through the process of creating a new folder and then creating a new file inside it.

Against all my rules, but for the sake of simplicity I’m going to do this directly on the master branch in the lab-01-website repository.

Go to the repository home page on GitHub, mine looks like this:

Figure 9.14   GitHub—Repository contents

Click the create new file button (point 3 above).

It looks like this:

Figure 9.15   GitHub—create file page

It’s asking for a file name. If I just give it a name content.txt for example, it will create the file in the root directory i.e. lab-01-website/content.txt.

Now I want to put the file in a new folder, so how do I create the folder to put it in? The answer is just start typing the folder name and file name in the highlighted box. Separate the file name from the directory name with an oblique character (/). I want to create a file called content.txt and I want it to live in a new directory called docs.

To do this start typing docs in the name your file box:

Now hit the oblique key (/) to separate the folder from the file name, the moment you do, it will recognise docs is a directory and move it outside the box (clever isn’t it):

Continue typing the filename (content.txt) and when you are done hit return .

Now add some text into the body of the file, I’ve added the following five lines:

Figure 9.16   GitHub—add text to the file

The buttons at the top: spaces, number, no wrap show how the page is edited and displayed. The no wrap button can be changed to cause lines to wrap in the display (generally, for long lines set this to soft wrap). The spaces button determines how tabs are constructed, either from the tab character or by spaces, if spaces then the number of spaces specified in the next (number) button will be inserted whenever the tab key is pressed.

Generally, for text files, leave it set to spaces and change the number to 4, this keeps it in line with the way Brackets handles such files.

Now we need to commit the file, this is just what we did in § 8.4.

Scroll down to the bottom of the page (to the commit box) and enter the following commit message:

Figure 9.17   GitHub—commit the file

Click the commit new file button to add the file to the repository this will take you to the newly created docs folder and show you the new file and commit number [64478f4] in my case:

Figure 9.18   GitHub—new file and commit number

Go back to the repository home page:

Figure 9.19   GitHub—repository home page after new file created

The new docs folder is there and the commit number has changed to [64478f4].

Let’s add another file to the doc folder, this time by uploading it from a PC. The file in question is a short word document explaining my version control numbering mechanism. Get it here a. It’s called:

PS1002-5-2121-091 R01.00 PS Version Numbering.docx

Boy, do I like numbering things.

Back to GitHub, from the lab-01-website repository home page, navigate to the docs folder (by clicking it):

Figure 9.20   GitHub—upload file

Click the upload file button (highlighted):

This gets you:

Figure 9.21   GitHub—upload file window

Unzip the file and either drag it into the main area or click choose your file and navigate with Windows Explorer to where your file is, I did the latter:

Figure 9.22   GitHub—upload file dialogue box

Select the file and click open.

This uploads the file to GitHub, but doesn’t add it to the repository yet.

To add the file to the repository, we must complete the commit message box at the bottom of the screen. I’ve added the message:

It all looks like this:

Figure 9.23   GitHub—upload commit message

You can see the new file at the bottom of the drag window (highlighted).

Click the commit changes button to add the file to the repository home page and will show you the new file and commit number, [100bd32] in my case.

Navigate to the docs folder (by clicking it):

Figure 9.24   GitHub—uploaded file in the docs folder

All pretty straight forward.

One last thing; the file we just uploaded is a Word file, a .docx file, now GitHub knows about text file based source code (HTML, CSS, JS &c.) and it has an editor that can handle them. It does not however, have an editor for Word files, if you double click the new file to open it, GitHub will respond with:

Figure 9.25   GitHub—try to open a Word file

This is understandable. If you need to modify the file, do it in Word and upload it again.

• If you click view raw, it will just download the file.

We’ve done this before, but for completeness I’ll cover it again here.

Go to the repository home page and click the README.md file, this opens the file as a preview (just like § 9.2.3). It looks like this:

Figure 9.26   GitHub—README.md preview

Click the edit icon ( ) to open the file editor.

• Because we have opened a markdown file (with extension .md), we have the option of previewing the file (i.e. see how it will appear when it is rendered as markdown, like it is in Figure 9.26). To preview the file click the preview tab at the top, it has the symbol.

In the editor, add the following lines:

There is a version numbering document within the /docs folder that explains how version numbering can be implemented on a GitHub project

## Website contents

It looks like this on the website (I’ve highlighted the new lines):

Figure 9.27   GitHub—commit the edited file

Add the commit comments as shown and click commit changes to add the modified file to the repository.

This takes us back to the file preview page and shows the new commit number [5644edc].

You can see the changed lines at the bottom of the page (highlighted):

Figure 9.28   GitHub—final edited file

To demonstrate this, let’s rename the content.txt file that we created in § 9.3.1 let’s change its name to page-list.txt.

This is easy.

Open the file in GitHub (from the repository home page click the docs folder and then click content.txt).

Now edit the file by clicking the pencil symbol ( ), just like we did for README.md in the last section. You should have this:

Figure 9.29   GitHub—rename a file

To rename the file just change its name in the box highlighted. Change it to page-list.txt.

You could also change the directory here by adding a new folder name followed by an oblique followed by the new filename (this is similar to creating a new folder in § 9.3.1—it’s the same mechanism.

Rename the file and then add the commit message shown in Figure 9.30:

Figure 9.30   GitHub—rename a file commit message

Click commit changes and the filename has been changed; there is a new commit point [09fc21b].

• There are restrictions to what you can rename—specifically it is not possible to rename files that GitHub cannot edit; the docx file in § 9.3.3 cannot be edited and consequently cannot be renamed (it can be deleted and re-uploaded with a different name though).

To demonstrate let’s get rid of what is now the page-list.txt file—it’s not much use.

Open the file in GitHub (from the repository home page click the docs folder and then click page-list.txt).

You should have this:

Figure 9.31   GitHub—delete a file

Now delete the file by clicking the rubbish bin symbol ( ). This takes you to the commit changes page, add the commit message:

Figure 9.32   GitHub—delete a file commit message

Click commit changes and the file will be deleted; there is a new commit point [19de35d].

• You can’t delete folders from GitHub, the only way is to link the remote repository to a local repository, delete it there and then push the change back to GitHub.