Warning: This how-to is for Mac users, since it provides information on installing Mac OS X apps. Windows is quite similar though, you’ll have to google.
What is GitHub?
GitHub is a platform for hosting and collaborating on projects.
Say you want to create a cool handmade visualisation or a webpage template or a scraper (as opposed to using automated but limited tools with user-interface, like Datawrapper, CartoDB, Shorthand). You’ll need to code the whole thing yourself – and you’ll want to store all the code and documentation in one place online. That’s GitHub. Not only does it store your files but it also remembers all the changes you make – it’s called version control – so you can always go back to an earlier stage and correct errors.
GitHub is also cool because it makes your work open source, i.e. free for others to share, use and improve. In return, you’ll be able to use the gems put on GitHub by others. Search for them and, yes, copy (‘fork‘) and reuse (if you can). Or ‘star‘ for later.
Although GitHub is far from being a Content Management System (like WordPress or Adobe CQ), you can host a blog on GitHub, or publish your amazing handmade projects as standalone GitHub Pages. No worries if that seems intimidating, though; thanks to its open source ideology, why not just start by inputting your data into somebody else’s template? It’s a great way to learn.
Blogging via GitHub is geeky. There is no database where you can access all your posts and make changes in minutes. You’ll need to use some magic to post (see below). But the value for money (it’s free) is great – you can make your blog and its features look however you want. With some extra magic like Heroku, you can publish interactives of any complexity (compare to the limitations of a platform like Wordpress.com). But for a start, you may well choose one of the suggested themes.
You may think, ‘Why should I bother going the hard route if I can’t really code (yet)?’ Makes sense. But maybe, like me, you decided to take up the challenge early instead of postponing it ‘until I finally learn coding’ (=forever). I decided to fight my dev ignorance along the way because it’s much more fun (and better motivation) to learn things when you need them in real projects rather than to start from the very (boring and theoretical) beginning.
My friend Martin Gonzalez taught me how to use GitHub a while ago, and here I have put down the key steps as simply as I could. Follow them and you’ll be fine. Well, there might be a few hitches, but it’s worth a try!
There are only two types of people, a good old dev colleague told me: a developer (everything works) and a tester (everything fails). Test who you are.
Let’s start by setting it up
1. Go to GitHub.com and sign up
As easy as registering for Facebook. Choose a free plan obviously. (Later on, don’t forget to add a nice pic of yourself and some About Me wording).
You’ll arrive at this start page:
2. Create your first repository
To keep your files in order, you’ll store each project in a separate space called a ‘repository’.
Once you’re registered, GitHub will offer to create one. If not, use ‘+ New repository’ button.
Choose these options:
Boom! You’re set.
3. Create your first GitHub Page
If you plan to publish your work with GitHub, remember that a free account allows having one site per GitHub account/organisation and unlimited project sites.
You can generate a one-page project-site automatically by following the simple steps in this guide (choose Project Site -> Generate a site).
Try publishing your CV, for example.
4. Work locally on your computer and sync changes with online
The smart guys say it works best. What you need to do now is to ‘clone’ your repository to your local machine, do whatever work you need and push the changes back online (you will actually need to push every new change – called ‘commit’ – because this allows GitHub to keep versions of your work).
I am sorry, but at this stage you need to do everything in Terminal. Type Terminal in Spotlight and open the app. It looks sweet, doesn’t it?
Terminal is a Unix command line programme – a magic window into the deep dark world of your computer’s internal system. Obviously, it’s here for you to give it commands, and it will obey.
For instance, (always) find a $ sign and type whoami after it. Press enter (always press enter and wait, however long it takes, for something to happen, at least an ERROR).
See, it obeys! I am shveda indeed.
If you have some extra patience, do check this Command Line Crash Course.
There is also a desktop app for managing GitHub but using a command line is honestly more straightforward.
5. Install GitHub Pages and other important packages to your computer
Before you can proceed to using a hipster GitHub, you’ll need to install some development packages on your Mac. It’s not too painful, just do it.
As Wiki explains, Xcode is an integrated development environment containing a suite of software development tools developed by Apple for developing software for OS X and iOS. You’re not going to develop an iPhone app today, but you still need it.
Simply search for Xcode in AppStore and install (or update) it for free. Warning: it’s a large app, so it’ll take ages to install. But you have no choice.
In case something goes wrong, check this installation guide.
Homebrew is a package manager for Mac OX. Installation is very straightforward – go to Homebrew website, it will tell you to paste this code into the command line of Terminal (just paste and enter):
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
The code should work without your help. In case of an error message, read what it says and google how to solve it. Probably, you’ll need to download an extra package like the ones above. Or if the error says you have no administrator rights, try typing ‘sudo‘ before any other command (sudo prompts the systems to ask for your password as an admin).
After the $ sign is back in Terminal, type this command:
gem install github-pages
6. Clone your repository to the computer
Finally, you can clone (make a copy of) your online repository to your computer. Go to the repository page on Github.com and copy its HTTPS clone URL in the bottom right corner of the page.
Go back to Terminal and type this command:
git clone https://github.com/dummy-student/myblog.git
(Use your own URL obviously).
As a result you will find a GitHub folder named after your repository in the Home folder of your Mac (Finder – Go – Home, if you’re lost).
Yay, you can start posting now!
> > > HOW TO POST WITH GITHUB WILL BE EXPLAINED IN THE NEXT ARTICLE. FOLLOW FOR MORE UPDATES.
Meanwhile, here are some words of the wise on the value of using GitHub for journalism:
- Getting GitHub: Why journalists should know and use the social coding site by Knight Lab’s former student Emily Ferber
- Seven ways to use GitHub that aren’t coding by Lauren Orsini
- Journalist datastores: Where can you find them? by Simon Rogers
- GitHub: Make reporting better together at IRE NICAR Conference blog
For an alternative to my writing, try this video tutorial on GitHub for beginners.
Let us know how it went or what problems you’ve faced via Twitter!