Mastering GitHub with a screen reader, part 1.

A guide to becoming a Git Hubby using only the screen reader

Before we get started, I have to extend my special thanks to some special people who helped me master GitHub and write this blog:

Leonie Wattson

Matt King

Bryan Garaventa

Most of the W3C working groups and task forces have adopted GitHub as the home for all their content. To view, download, and interact with this content you need to learn a couple of things about GitHub in general, and accessing it with a screen reader in particular.

Both the GitHub website itself as well as most of the Git desktop clients are a bit of a crapshoot when it comes to accessibility.The process is a little daunting at first, but with the right combination of tricks and tools, and a healthy helping of patience, it can be mastered.

In this two-part blog we will cover the most common Github processes and how they can be tackled using a screen reader.

In this; the first part; we will start with the basics. We will help you set up the environment and then go on to explain forking, cloning and filing issues.

In the second part of this blog we will use these tools to hack our way through the mighty jungle of creating branches, using them to make changes, pushing the branch with your changes to your fork, and generating a pull request so that your branch with your changes can be merged into the master branch.

If you only understood the small words in the previous sentence, don’t worry, it will all be explained.

Configuring the GitHub environment and setting up the tools.

Working with GitHub primarily involves interacting with 3 different areas:

The GitHub repository’s master webpage – the webpage hosting the GitHub project you want to participate in. From this page you can fork the repository contents and file issues.

Your online GitHub account (which you are about to create if you haven’t already done so). Here you can upload your repository changes before you request they be merged back into the master repository. Your copy of the repository on your account is called a fork.

A Git client on your desktop, where you have a local copy of cloned repositories and where you can make changes.

Getting started with the Github website.

To get started you need to create a GitHub account. The account creation form is displayed right on the GitHub homepage if your browser does not sign you in automatically. If you already have an account and still see the username, email and password input fields on the homepage, look for the “Sign in” link in the page header and use it to sign in to your account.

The GitHub website contains a number of quirks, conundrums and annoyances for screen reader users, along with a handful of full-blown accessibility violations.
James Teh from NVDA has written a Greasemonkey script that fixes a number of these issues. For a link to the script, and instructions on how to install it, head over to theInstalling script to make Github webpage more accessible guide courtessy of Amanda Rush. You can get by without installing this script, it just makes a few things easier to locate.

Once you feel comfortable with GitHub you can contribute your own changes to this script, as the repository is hosted on GitHub. Though ultimately we want the people responsible for the GitHub website to fix it for everybody.

Selecting and installing a Git client.

Let’s start with the bad news. But don’t panic! There is also good news.

The Windows GUI clients for Git are very inaccessible, especially theGithub Desktop. It is in fact so bad that a screen reader announces nothing when it is opened. There is a client called Source Tree that is marginally better, but still too complex. If anyone is brave enough to try and use them and document how it can be done with a screen reader, that would make for one heck of a blog!

The good news: The Git command line clients are quite accessible, and are more efficient than the desktop versions once you learn to use them.
The most accessible one is Git for Windows.

After installing Git for Windows, you open its command line prompt in 3 easy steps:

Navigate to the repository folder (or the folder where you want to download the repository) in Windows Explorer.

Open the context menu (application key or shift-f10).

Find and activate the “Get Bash Here” option (third option from the top usually). Note: This option is not available for subdirectories of a Git repository.

You should get a prompt that looks a little bit like the following:

Username@machineName MINGW64 ~/pathToCurrentFolder$

You can copy to, and paste from, the Windows clipboard by bringing up the context menu from the Git Bash shell (application key or shift-f10). This is especially useful when pasting in URLs or reviewing the interaction log from your Bash shell interaction.

While in the Bash shell, Press the application key (or shift-f10).

The first two options in the context menu are “copy” and “paste”.

You can also copy from clipboard directly by pressing ctrl-insert, and paste directly using shift-insert.

To Review the Git Shell Log:

While in the Bash shell, Press the application key (or shift-f10).

Press “a”, or Locate and activate the “select all” option (3rd option in the menu)

Paste the clipboard contents into a text editor such as Notepad”.

We will cover the use of Git commands from the command line in much more detail in part 2 of this blog.

The Git Shell command line environment that comes with the GitHub desktop works in a very similar way, except you cannot bring it up from the context menu or copy and paste from the clipboard.

Working with Github

Now that we have created a Github account and downloaded the tools, we are ready to dive into the magical world of Github. This blog gives you the basics as they relate to use with a screen reader. For general guides on Github processes and commands see links to GitHub information scattered throughout.

We can roughly divide the process of downloading, changing, and committing a Github project/repository into 6 steps. The steps come with their own Github vocabulary. See sections below for further details. We are only going to cover the first 2 steps in this blog, the remaining 4 steps will be covered in part 2.

Once you have forked a project it will be displayed on your Github account homepage. Activate the link to that project on your account homepage. There you will find a button called “clone it. Click the button, locate the URL and use the clone command of your Git desktop client to download it.

Step 1 on your GitHub account page, step 2 on your local machine.

branching

Create a local branch of the project on your computer, make sure all changes related to the branch are done in that branch, and that the branch name you choose reflects the type of changes you will be doing.

Your local machine

Updating

In the branch you created for the repository change, go ahead and modify, add, and delete files using your desktop client commands until your change is implemented./td>

Your local machine.

Pushing

When you are done, push the branch with your changes back to your fork of the repository, that lives on your GitHub account page.

Your local machine.

Pull requesting

Request that the branch with your changes be merged back into the repository’s master

Your Github account website.

Step 1, Forking a repository.

So you want to join a GitHub project. The first step in your journey is to make a virtual copy of the project’s repository in your GitHub account. This is referred to as “forking the project” in GitHub speak.Forking a repository enables you to download the repository to your computer using the Git tools you just installed, a process called cloning (see next section).

To fork a repository, all you need is the URL to the repository’s Github page. Go ahead and navigate to it in your favorite browser.

There is valuable information on this page. For instance, if you find the “Compare” link and navigate down from there in the virtual buffer using the arrow keys, you will see if the project is up-to-date. If it is, the line should read “this branch is even with x master” where x is the name of the repository. Of course it is up-to-date when you fork it, but this info can be valuable later when you return to this page and want to know if your fork is still up-to-date.

You are now ready for cloning (the project, not yourself).

Step 2, cloning a project

The process of downloading a forked Github repository to your computer using the Git tools is called “cloning”. You can also download a .zip file of the contents, which is probably called “downloading”. Whichever way you choose, the instructions below will help you get there.

To clone or downoad a project you must first obtain its clone URL from your fork. If you just forked the project (see previous section) you are already on the right page. The title of the page should be your username / the repository name. If you are already there, jump to the next heading. If not , follow these steps:

Go to the Github homepage. If you are not logged in automatically (you see username and password input fields on the page), locate the “sign in” link in the header and sign in.

Locate the h3 heading “your repositories” (plus a number showing how many repositories you have forked).

The second list after this heading is a list of your repositories (it will be a list of 3 items if you have forked 3 repositories). The list starts immediately after the search landmark region ends.

Click the link to the desired repository from this list.

Locating the clone menu on the repository page.

If you want to find the clone URL for your fork, you start on your repo fork page (see previous section). These instructions also apply if you are looking for the clone URL on the repository’s master page.

Locate the “Clone or download this repository” menu button. It is the forth button on the page (if you navigate by buttons). It is approx. 15 lines under the first h1 heading on the page (after the information on the repository composition).Activate the button.

At first glance nothing seems to happen. This is because the menu is not properly implemented (this is not a menu, just an expandable section),. If activating this button forced your screen reader into forms or application mode, exit it and use arrow down key to explore the new content underneath this button. You should see a number of newly displayed choices.

You should see an h4 heading with the text “Clone with https:”. If you want to download the project using your git client, go to the next edit field and copy the URL from it (the URL should contain your username and end with “.git”), or simply activate the “copy to clipboard” button.

If you move past this field you should see 2 links: “Open in desktop” and “download zip”. The first link is not very interesting for screen reader users (we have yet to find an accessible Windows desktop Git client), but if you want to avoid using Git tools, you can simply click the “download zip” link to get a zip file of the repository contents.

Cloning the project with your Git client.

This assumes that the fork URL for the repository is on your clipboard (see previous section on how to get it there).

If you are using the Git Bash shel (see section on Git tools):

Open the Git Bash shell in the folder where you want to download the project

Type “clone” (without the quotation marks, then space.

Open the context menu and select “paste” to paste the Git Fork URL into the shell.

Press enter.

This wil clone the repository, (download the repository to the folder that is open and recreate the folder structure and everything. This process might take up to a minute or so. If you want to see waht is happening, give it a minute and then copy the contents of the shell to a text editor. Using the Jaws cursor or a braille display enables you to monitor this process in realtime.

Congratulations! The repository is now living on your computer and is ready for inspection, perusal and contributions.

Keeping your GitHub repositories up-to-date

For there may come a time, hopefully in the near future, when progress shall be made, and the repository shall forever be changed for the better.

If the master repository is updated, the updates are not automatically downloaded to your local copy or your fork. It may sound counter intuitive, but it is easier to use your Git client to update your local machine’s copy of the repository then update your GitHub fork from your local machine. To do this you have to connect your local machine with the master repository. In Git speak this is called “upstream”.

Creating an upstream reference

To get updates from the master version of the repository you need to be able to point to its URL. That reference is called “upstream” in Git speak. This is the URL we suggested you should copy in the Forking section of this blog..
If you didn’t heed our advice, no worries, just go to the master repository’s webpage, find the “clone” button and locate the “clone URL from there as described in theLocating the clone menu section..
This URL looks exactly like your fork’s clone URL except it has the project authors username.git instead of yours.

Once you have the master repository URL you need to create the upstream reference in your local repository, using your Git client.

Navigate to your local repository folder for that project on your machine and open the “Git Bash” from the context menu.

You only have to create the upstream reference once. Your Git client will remember it.

Now all that is left to do is to update your fork with the new updates. Before you do you need to know that your local fork of a repository always has the same name in your git client, it is called origin. The branch you are currently using with your Git client is called master.
Therefore it probaby sounds logical that the Git command to update your fork (aka origin) from the master repository (aka master) is simply:

git push origin master

Voila! Your fork is up-to-date.

Of course you could boycott the Git tools altogether and just download a zipped version of the master repository, delete the old repository foldder on your local machine, and recreat it by extracting the new .zip file. But that does not update your fork, and it is so not nerdy.

Join us for part 2 of this blog where we discuss how to make updates and merge them back into the master repository.

Related

Author: Birkir Gunnarsson

Approaching 40 (at the time of this writing), blind since age 5. Born and bread in Iceland. Grew up in Iceland, came to the U.S. to attend Yale University. Spent 7 years in the Banking sector as a developer, where I grew out more than growing up. Started working in assistive technology and accessibility in 2009. I have dabbled in all things accessibility, from creating braille standards, to conducting website, PDF and mobile application assessments, delivering user and developer training, and campaigning for Icelandic and European accessibility policies and regulations. Started a full-time position with Deque Systems in 2013 where I have worked on all things accessibility with some of Deque's clients, many of them Fortune 500 companies. A member of W3C ARIA/ARIA Authoring Practices working groups since 2014. I am married, have 3 kids, love listening to good music and making questionable music in my spare time (which barely exists).
See my extended BATS bio for a lot more information.
View all posts by Birkir Gunnarsson