Presentations

Setup

• Prepare RPCEmu:
  • Use 0.9.x, as 0.8.x appears to record as a black screen and you'll be very disappointed after everything going so well that you got an empty screen.
  • The version of RPCEmu I use lives at "~/Library/Applications Support/hostfs".
  • Clear the home directory on HostFS, to make it easier to see what we're doing.
  • Start the emulator, enter the desktop.
  • Set Wimp$Font Homerton.Medium
  • Be aware the menu is Alt-Click

• Prepare git configuration

  • We need to disable the credential stores and custom configuration so that we can demonstrate the commit and login
  • Rename .gitconfig to .gitconfig-mine

  • Create an empty .gitconfig and add a separate credential store, using a clean file:

    [credential] helper = store --file ~/.git-credentials-demo

  • Edit /usr/local/etc/gitconfig (or maybe /etc/gitconfig) to disable the osxkeychain store

  • This will be equivalent to what the user would see if they had never used git before and had to obtain some credentials.
  • Git requires personal access tokens, so we'll need to demonstrate that without them you get an error, and you should create a token using the URL suggested.
  • Remember to empty the .git-credentials-demo file before each demo.
  • Prepare the screen:
  • Terminal window on the left
  • Prepare a terminal
  • bash
  • clear
  • Scale the window up a bit so that what we're doing is going to be readable.
  • Prepare the remote repository
  • Ensure that the branch add-my-name has been deleted before we start the demo with: git push origin :add-my-name
  • Open an editor window with your GitHub personal token in.

Script

I'm going to demonstrate using git on macOS with RPCEmu. I assume that you're either familiar with git itself, or happy to learn about the system yourself. That you have a copy of RPCEmu installed.

To demonstrate this, I've already got RPCEmu running, and a terminal that we can work in.

I am going to use a fork of the LineEditor module as an example repository. I'm using a fork because I'm going to push changes, but if you're not making changes you can use public repositories.

Set up prerequisites

You will need to have the git tool installed on macOS. The tool is supplied as part of the XCode development environment. If you do not have the full XCode installed, you can use the command xcode-select --install to install the tool.

xcode-select --install

I already have the tools installed. You can check that git has installed properly by running git --version

git --version

When we make changes, we need to enter a commit message. The default editor might have been set to be vim, so you can configure a slightly more friendly editor, like nano:

export EDITOR=nano

The editor you use is your preference, but this is easier for many users.

Having set things up, we need to locate the directory that RPCEmu uses for HostFS. This might be different on your version of RPCEmu, but the default is ~/Library/Application Support/RPCEmu/hostfs here:

cd ~/Library/Application\ Support/RPCEmu/hostfs

alt-tab to the RPCEmu window, then move the mouse into the window (something about focus makes that odd on my old install)

click HostFS to show that there is nothing is present

Using Git

As you can see, this is a bare system just to demonstrate the principles.

alt-tab back to the terminal

I'm going to clone one of my repositories, so that I can demonstrate making changes. The same principle applies to public repositories as well. We do this through a git clone command:

git clone https://github.com/gerph/LineEditor

This has downloaded the repository and checked it out into the LineEditor directory, as we can see here:

ls
cd LineEditor
ls

The recommended way to handle RISC OS filetypes in the host filing system is to append the filetype number to the filenames, separated by a comma. As you can see here there a couple of files with filetypes. In particular the LESrc file has type FD1.

FD1 is the filetype for BASIC text. It is strongly recommended that you keep your BASIC files in text format, as this means that comparing files and editing them on other systems is significantly easier.

If we return to RISC OS, we can see the files are now there. The Filer won't update automatically so you will need to refresh the directory after making changes.

alt-tab to the RPCEmu window, then move the mouse into the window

Menu on the filer, select Refresh and go open the LineEditor window

The files we checked out are here. As you can see there are filetypes set on a few of the files. If we run the !!Release it will create a new LineEditor module.

Double Click on !!Release

This has built the module and placed a copy in the Release directory.

Clear the command window by clicking, and point to the LineEditor module

This is the newly built module.

So, let's make a change to the code and rebuild it. I'm not going to do anything complicated - I'm just going to change the help string to demonstrate the principle. If we use Shift-double-click on the line editor source file, it will load into the editor. I'm using !Edit here because this is a cut down system - but you should use whatever editor you are familiar with.

Shift-double click on LESrc, and make it full screen

I want to change the helpstring, so I'll find it and them make a simple change.

Open menu, Edit->Find, enter 'helpstring' and click go. Click continue to move to the second use and close the search window Click on the end of Olly Betts and add and me

We can then save the file...

Press F3 to save the file and click ok Close the window

And build the new module.

Double click !!release

If we load the module we just built, we should see our change is present.

Double Click on lineeditor to load it F12

Help lineEditor

We can see the help message now has the change in it.

Ok, so we've made our change, so let's see what that looks like in Git. We can return to the terminal and see the change.

alt-tab back to the terminal

Git status will show us what files are changed in the repository.

git status

We can also see that we only changed one line with git diff:

git diff

This shows the old line in red, and the new line in green.

We want to commit this change because it's been tested, and we're happy with it. But it needs to be put on a branch so that it's separate from the main development. This will make it easier for other people to review it. So we create a new branch called 'add-my-name' and move on to it:

git checkout -b add-my-name

Before I can commit anything we need to configure who I are. Git may try to infer this, but it is much better to be explicit about who you are. This is configured in the global settings with git config:

git config --global user.name "Charles Ferguson"
git config --global user.email "gerph@gerph.org"

Then I need to commit the change, so I use git commit. For this we need to use the filename of the file I'm changing. You could use git add and git commit, but this is quicker here:

git commit LESrc,fd1

This opens the nano editor, for me to describe the change. You should always explain the changes you made so that it is clear to people in the future what you were doing and why. The first line is a summary of the change, so should be one line that just says what you were trying to do.

Type...

Add my name

My name is now in the Help string.

Press Ctrl-X to exit the editor and save the file, and that change is now committed.

Ctrl-X, Y, Return (slowly so that people can see the prompts)

We can see the change is present in the history by showing the most recent change.

git show

There's the change we made.

Committing the change here only updates our local repository. To make it available to other people, it is necessary to push the change to the remote repository. The remote repository is called 'origin' by default, and we only want to put the branch we just created.

git push origin add-my-name

Pushing is a write operation, so the remote server needs to know who you are. So we can enter our username and password.

Enter 'gerph' and 'password' at the prompts

But... GitHub doesn't allow you to push with a password any more. Fortunately the documentation that's printed there explains how to create a personal access token which you can use to push code. If you have such a token you can use it in place of your password.

Enter gerph and then copy the token from the window you stashed away

I've pasted my token from another window, there. As you can see, that was successful.

In macOS the default is to store your credentials for a given site in your personal keychain, so this login should only be necessary the first time you use a given site.

And that's it for the basics. I've shown how to git on macOS with RPCEmu, and how to make changes and push them. There are lots of tutorials and help on the Internet on using Git, which you should be able to use with what you've seen here.

Thank you for watching.