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!