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.
If you plan on viewing a git repository without modifying its content, you can get by without using Git desktop tools at all (see Keeping your Repositories up to date for details.
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 the
Installing 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 the
Github 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.
|Forking||Locate the webpage of the GitHub repository you want to participate in. Click the “Fork” button.||The GitHub page of the repository.|
|cloning||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.
Before you fork the repository you may want to Locate and copy its clone URL, it will come in handy when you need to update your local copy and your fork with the latest master repository updates See Keeping your repositories up-to-date section for details<. The third button on this page should be labeled "fork your own copy of x to your account" (where x is the name of the repository). Visually this button is located in the top right corner of the page. To fork the repository, simply click that button. Keep in mind this button will navigate away from the webpage. If you are not logged in, clicking this button will take you to your account sign in page, go ahead and sign in. If you are already signed in, the forking should now be done. You should now be on the project page in your account. The page title should have changed to "your username/the repository name", and the h1 heading on the page contains a bunch of information and links, along the lines of:
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 the
Locating 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.
- Type the command:
git remote add upstream URL
(where URL is the master repository URL, you can also paste it from the clipboard.
- You can verify that an upstream repository was added using the command:
git remote -v
You can always review the output of the Bash shell in a text editor.
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.
Let’s collaborate fearlessly and move accessibility forward!
You may also wish to read this Git cheet sheet