Tumblelog by Soup.io
Newer posts are loading.
You are at the newest post.
Click here to check if anything new just came in.

April 14 2013

16:22

Get started with Web coding. Part 5: How to use Git and GitHub

If you want to design the future, learn to code.

That’s how I concluded the last post in this series. So far, I’ve discussed HTML and CSS, JavaScript and jQuery, the command line, and software and CMSs. The vast majority of journalists out there are probably not going to stick with the program much past part 1 (HTML and CSS). But for those of you still with me, Git has become a de facto standard in a very short time, so let’s go!

What is Git? Git is a version control system (VCS). Version control helps you manage and keep track of changes you make to your online projects. Version control is considered essential for teams working together on a digital project. Git is free and open source — there are no fees.

How do you get Git? You must download and install Git on your own computer. Follow these instructions for any operating system. Skip past the part “Installing from Source” and go down the page to the part for Windows or for Mac. For Mac OS, download the Git installer, which launches a typical DMG file. Note: Some steps below will not work if Git has not been installed.

How do you use Git? This has a long list of possible answers, and you will need to learn a lot more if you are working on a project together with teammates. I’m going to focus on the solo user, such as one journalism student working on his or her own files. Basically, once Git is in place in a project folder on your hard drive (explained below), you will add files from your project, commit files after you have updated or changed them, and push files to an online site or repository (repo) when ready. Even if you are not working with teammates, this can help you prevent mistakes if you work on multiple computers — you can pull the latest version from the repo to quickly incorporate any changed files on the local computer.

You might be thinking, well, my Web sites or projects are very small, only a handful of files, so I don’t need this Git stuff. Okay, fair enough. But if you ever need to share a site or a project with other people, GitHub provides an easy way to do it. Others can download your entire project by clicking the Zip button on the GitHub repo page.

GitHub image - download zipped file

I have Git — now what?

If you have installed Git and done nothing else, what’s next? Do you have an account on GitHub? No? Then let’s do that next. (Yes? Skip down to the following subheading.)

GitHub image - First steps at GitHub

GitHub is a social site for code. It has more than 3 million users and is free to use, unless you want to have private code repos (then you’ll need to pay). So if you’re not going to pay, don’t put anything on GitHub that you don’t want the world to see. Coders from all around the world share their code publicly on GitHub. This is one of the coolest things about it. Even if you do not have a GitHub account, you can look at other people’s code, like this.

Go to GitHub, type a username, your email address and a password, and you’re good to go. Now read this and do what it says. It explains how to set up your very first “repo,” which means a repository for your files and code.

GitHub image - Create a new repo

If you have a little code project on your own computer already, maybe it has a name like photo-slider or personal site or scrolling_game. That is, you’ve got files inside a folder with a name like one of those names. If so, it would make sense to name your first repo the same way, and you could try putting a real project into your first repo. (Note that repos use hyphens in the name, not an underscore or a space.) Check out the way repos are named on GitHub’s Explore page.

Note: You do not need to create a README right away. You can wait.

I have a GitHub account, and so …

You have already downloaded and installed Git, but you haven’t set it up yet. I wanted you to wait a bit because this part requires you to go to the command line. It attaches your name to your work, and your GitHub login details. If you’re already comfortable with the command line, of course this will be simple for you. If you’re not used to the command line, you can do it in the client program — read on!

Assuming you are not a command-line jockey, you should now download and install GitHub for Mac (OSX 10.7+ only) or GitHub for Windows. Each of those is a client program that lets you manage your projects and all associated files without going to the command line. To get started, you will need your GitHub username and password — which is why you had to set up GitHub before this part!

After you supply your GitHub username and password to the client program, you’ll see the name of your first repo (the one you made earlier on GitHub) appear there. (If you don’t see the name of your repo, click your username at the left side.) Notice it says “Clone to Computer” on a button to the right of the repo name (shown below). Do not click it. (There are no files in your repo on GitHub, so there’s nothing to clone!)

GitHub for Mac image - Clone to Computer button

Interlude: Set your username and email address in the client program now.

GitHub for Mac image - git config information

Now, back to the “clone” thing: If you had files on GitHub.com and not on your own computer, then you would press the clone button. This would be perfect if you had an empty folder just waiting on your computer to receive a bunch of files. Cloning would bring the whole repo from GitHub down to your local folder.

However, if you have files for this project on your computer, and no files at GitHub.com, here’s how to copy all those files up to GitHub:

  1. File menu > Add Local Repository
  2. Navigate to the folder on your computer that contains all your project files.
  3. Open the folder and click Add.
  4. The client alerts you that this is not a Git repository (yet). Click Yes to make the magic happen. (This is what I meant above when I said “once Git is in place in a project folder on your hard drive.” When you click Yes, the client invisibly runs a git init command, which enables Git in that one folder.)

GitHub for Mac client image - Add Local Repo

Now your client flips to the Changes tab, and you see all the files that are inside the folder. These files are waiting for your first commit. (This is a big difference between the client and doing Git at the command line, by the way.) You’re about to do several steps — to upload all the files to your GitHub repo (where others can see and easily download them as one zipped file) — so make sure these are files you don’t mind others having access to.

Ready? Okay. Find the text near the upper left that says “Commit summary.” Replace that text with a few words that describe what’s been changed since your last commit. Since you never committed to this repo before, type “first commit.”

GitHub for Mac client image - Type a commit message

Click the button Commit & Sync. Now your local folder and the (remote) repo are sync’d. But your files are not at GitHub.com yet.

To send the files this first time requires two steps in the client:

  1. Click the Settings tab in the client. This is where you provide the Web address of your repo at GitHub. Get the address from your repo’s page at GitHub (see illustration below). Then click Update Remote.
  2. Click the Branches tab in the client. Then click the Publish button on the right side. Refresh your repo’s page at GitHub, and you will see all your files there. Click any file to open it. You can even edit files right there, on GitHub. (Warning: If you make a change on GitHub, be sure to do a pull in the client program — it’s on the Repository menu.)

GitHub image - Get the URL of a GitHub repo

You’ll need to explore the help document for your client program — Mac or Windows — to get the hang of keeping everything sync’d up in true Git fashion. You might even find yourself yearning to learn more about the command line in just a little while.

GitHub image - Help files for GitHub for Mac client program

Forking and branches

Two bits of jargon you’ll hear often around the world of Git are fork and branch.

If you fork someone’s code on GitHub, you get an independent copy of that whole repo, in your GitHub account. You can then modify any part of it without affecting the original. The files will not appear on your computer unless you clone the repo locally (about cloning: see the third paragraph under the subheading above, “I have a GitHub account, and so …”). Note: You can download someone’s repo without forking it.

Branches are vital for teams working on different pieces of one project. A branch is a copy of the code that stays in the same project, a parallel duplicate. A branch can later be merged back into the master, or original set, of all files and code. If any changes are incompatible, Git highlights them all for you so that human intelligence can decide what to keep and what to delete. Note: The original, first or only set of files is also a branch, named master. So every repo has at least one branch.

Git vs. FTP

Are you regularly updating and uploading files to a Web server? You might like to use Git to handle that for you. There’s a repo for that, in fact! Separately, there’s a very straightforward how-to for the command line. Less straightforward — this 26-minute video is almost scary (the guy opens a lot of apps in the process of figuring out, live, how to do this) but kind of fun to watch; he uses Beanstalk, a paid service. See also: Using Git for Deployment (detailed).

You must know your way around your hosting server before you try this part (replacing FTP). And you’ve got to be comfortable with the command line. If you’re not, better stick with FTP, I think.

More Information About Git

This Series

16:22

Get started with Web coding. Part 5: How to use Git and GitHub

If you want to design the future, learn to code.

That’s how I concluded the last post in this series. So far, I’ve discussed HTML and CSS, JavaScript and jQuery, the command line, and software and CMSs. The vast majority of journalists out there are probably not going to stick with the program much past part 1 (HTML and CSS). But for those of you still with me, Git has become a de facto standard in a very short time, so let’s go!

What is Git? Git is a version control system (VCS). Version control helps you manage and keep track of changes you make to your online projects. Version control is considered essential for teams working together on a digital project. Git is free and open source — there are no fees.

How do you get Git? You must download and install Git on your own computer. Follow these instructions for any operating system. Skip past the part “Installing from Source” and go down the page to the part for Windows or for Mac. For Mac OS, download the Git installer, which launches a typical DMG file. Note: Some steps below will not work if Git has not been installed.

How do you use Git? This has a long list of possible answers, and you will need to learn a lot more if you are working on a project together with teammates. I’m going to focus on the solo user, such as one journalism student working on his or her own files. Basically, once Git is in place in a project folder on your hard drive (explained below), you will add files from your project, commit files after you have updated or changed them, and push files to an online site or repository (repo) when ready. Even if you are not working with teammates, this can help you prevent mistakes if you work on multiple computers — you can pull the latest version from the repo to quickly incorporate any changed files on the local computer.

You might be thinking, well, my Web sites or projects are very small, only a handful of files, so I don’t need this Git stuff. Okay, fair enough. But if you ever need to share a site or a project with other people, GitHub provides an easy way to do it. Others can download your entire project by clicking the Zip button on the GitHub repo page.

GitHub image - download zipped file

I have Git — now what?

If you have installed Git and done nothing else, what’s next? Do you have an account on GitHub? No? Then let’s do that next. (Yes? Skip down to the following subheading.)

GitHub image - First steps at GitHub

GitHub is a social site for code. It has more than 3 million users and is free to use, unless you want to have private code repos (then you’ll need to pay). So if you’re not going to pay, don’t put anything on GitHub that you don’t want the world to see. Coders from all around the world share their code publicly on GitHub. This is one of the coolest things about it. Even if you do not have a GitHub account, you can look at other people’s code, like this.

Go to GitHub, type a username, your email address and a password, and you’re good to go. Now read this and do what it says. It explains how to set up your very first “repo,” which means a repository for your files and code.

GitHub image - Create a new repo

If you have a little code project on your own computer already, maybe it has a name like photo-slider or personal site or scrolling_game. That is, you’ve got files inside a folder with a name like one of those names. If so, it would make sense to name your first repo the same way, and you could try putting a real project into your first repo. (Note that repos use hyphens in the name, not an underscore or a space.) Check out the way repos are named on GitHub’s Explore page.

Note: You do not need to create a README right away. You can wait.

I have a GitHub account, and so …

You have already downloaded and installed Git, but you haven’t set it up yet. I wanted you to wait a bit because this part requires you to go to the command line. It attaches your name to your work, and your GitHub login details. If you’re already comfortable with the command line, of course this will be simple for you. If you’re not used to the command line, you can do it in the client program — read on!

Assuming you are not a command-line jockey, you should now download and install GitHub for Mac (OSX 10.7+ only) or GitHub for Windows. Each of those is a client program that lets you manage your projects and all associated files without going to the command line. To get started, you will need your GitHub username and password — which is why you had to set up GitHub before this part!

After you supply your GitHub username and password to the client program, you’ll see the name of your first repo (the one you made earlier on GitHub) appear there. (If you don’t see the name of your repo, click your username at the left side.) Notice it says “Clone to Computer” on a button to the right of the repo name (shown below). Do not click it. (There are no files in your repo on GitHub, so there’s nothing to clone!)

GitHub for Mac image - Clone to Computer button

Interlude: Set your username and email address in the client program now.

GitHub for Mac image - git config information

Now, back to the “clone” thing: If you had files on GitHub.com and not on your own computer, then you would press the clone button. This would be perfect if you had an empty folder just waiting on your computer to receive a bunch of files. Cloning would bring the whole repo from GitHub down to your local folder.

However, if you have files for this project on your computer, and no files at GitHub.com, here’s how to copy all those files up to GitHub:

  1. File menu > Add Local Repository
  2. Navigate to the folder on your computer that contains all your project files.
  3. Open the folder and click Add.
  4. The client alerts you that this is not a Git repository (yet). Click Yes to make the magic happen. (This is what I meant above when I said “once Git is in place in a project folder on your hard drive.” When you click Yes, the client invisibly runs a git init command, which enables Git in that one folder.)

GitHub for Mac client image - Add Local Repo

Now your client flips to the Changes tab, and you see all the files that are inside the folder. These files are waiting for your first commit. (This is a big difference between the client and doing Git at the command line, by the way.) You’re about to do several steps — to upload all the files to your GitHub repo (where others can see and easily download them as one zipped file) — so make sure these are files you don’t mind others having access to.

Ready? Okay. Find the text near the upper left that says “Commit summary.” Replace that text with a few words that describe what’s been changed since your last commit. Since you never committed to this repo before, type “first commit.”

GitHub for Mac client image - Type a commit message

Click the button Commit & Sync. Now your local folder and the (remote) repo are sync’d. But your files are not at GitHub.com yet.

To send the files this first time requires two steps in the client:

  1. Click the Settings tab in the client. This is where you provide the Web address of your repo at GitHub. Get the address from your repo’s page at GitHub (see illustration below). Then click Update Remote.
  2. Click the Branches tab in the client. Then click the Publish button on the right side. Refresh your repo’s page at GitHub, and you will see all your files there. Click any file to open it. You can even edit files right there, on GitHub. (Warning: If you make a change on GitHub, be sure to do a pull in the client program — it’s on the Repository menu.)

GitHub image - Get the URL of a GitHub repo

You’ll need to explore the help document for your client program — Mac or Windows — to get the hang of keeping everything sync’d up in true Git fashion. You might even find yourself yearning to learn more about the command line in just a little while.

GitHub image - Help files for GitHub for Mac client program

Forking and branches

Two bits of jargon you’ll hear often around the world of Git are fork and branch.

If you fork someone’s code on GitHub, you get an independent copy of that whole repo, in your GitHub account. You can then modify any part of it without affecting the original. The files will not appear on your computer unless you clone the repo locally (about cloning: see the third paragraph under the subheading above, “I have a GitHub account, and so …”). Note: You can download someone’s repo without forking it.

Branches are vital for teams working on different pieces of one project. A branch is a copy of the code that stays in the same project, a parallel duplicate. A branch can later be merged back into the master, or original set, of all files and code. If any changes are incompatible, Git highlights them all for you so that human intelligence can decide what to keep and what to delete. Note: The original, first or only set of files is also a branch, named master. So every repo has at least one branch.

Git vs. FTP

Are you regularly updating and uploading files to a Web server? You might like to use Git to handle that for you. There’s a repo for that, in fact! Separately, there’s a very straightforward how-to for the command line. Less straightforward — this 26-minute video is almost scary (the guy opens a lot of apps in the process of figuring out, live, how to do this) but kind of fun to watch; he uses Beanstalk, a paid service. See also: Using Git for Deployment (detailed).

You must know your way around your hosting server before you try this part (replacing FTP). And you’ve got to be comfortable with the command line. If you’re not, better stick with FTP, I think.

More Information About Git

This Series

April 26 2012

14:00

LedeHub to Foster Open, Collaborative Journalism

I'm honored to be selected as one of the inaugural AP-Google Journalism and Technology Scholarship fellows for the 2012-13 academic school year, and am excited to begin work on my project, LedeHub.

I believe in journalism's ability to better the world around us. To fully realize the potential of journalism in the digital age, we need to transform news into a dialogue between readers and reporters. LedeHub does just that, fostering collaborative, continuous and open journalism while incorporating elements of crowdsourcing to allow citizens, reporters and news organizations to come together in unprecedented ways.

LedeHub in Action

Here's a potential case study: "Alice" isn't a journalist, but she loves data and can spot the potential for a story amid the rows and columns of a CSV file. She comes across some interesting census data illustrating the rise of poverty in traditionally wealthy Chicagoland suburbs, but isn't quite sure how to use it, so she points her browser to www.ledehub.com. She creates a new story repository called "census-chicago-12," tags it under "Government Data," and commits the numbers.

Two days later, "Bob" -- a student journalist with a knack for data reporting -- is browsing the site and comes across Alice's repository. He forks it and commits a couple paragraphs of analysis. Alice sees Bob's changes and likes where he's headed, so she merges it back into her repository, and the two continue to collaborate. Alice works on data visualization, and Bob continues to do traditional reporting, voicing the story of middle-class families who can no longer afford to send their children to college.

A few days later, a news outlet like the Chicago Tribune sees "census-chicago-12" and flags it as a promising repository -- pulls it, edits, fact-checks and publishes the story, giving Alice and Bob their first bylines.

As you can see, LedeHub re-imagines the current reporting and writing workflow while underscoring the living nature of articles. By representing stories as "repositories" -- with the ability to edit, update, commit and revert changes over time -- the dynamic nature of news is effectively captured.

Fostering Open-Source Journalism

GitHub and Google Code are social coding platforms that have done wonders for the open-source community. I'd like to see similar openness in the journalism industry.

My proposal for LedeHub is to adapt the tenets of Git -- a distributed version control system -- and appropriate its functionality as it applies to the processes of journalism. I will implement a web application layer on top of this core functionality to build a tool for social reporting, writing and coding in the open. This affords multiple use cases for LedeHub, as illustrated in the case study I described above -- users can start new stories, or search for and contribute to stories already started. I'd like to mirror the basic structure of GitHub, but re-appropriate the front end to cater to the news industry and be more reporter-focused, not code-driven. That said, here's a screenshot of the upcoming LedeHub repository on GitHub (to give you a general idea of what the LedeHub dashboard might look like):

ledehub.jpg

Each story repository may contain text, data, images or code. The GitHub actions of committing (adding changes), forking (diverging story repositories to allow for deeper collaboration and account for potential overlap) and cloning will remain analagous in LedeHub. Repositories will be categorized according to news "topics" or "areas" like education or politics. Users -- from citizens to reporters or coders -- will have the ability to "watch" different story repositories they are interested in and receive updates when changes to that story are made. Users can also comment on different "commits" for a story, offering their input or suggestions for improvement. GitHub offers a "company" option, which allows for multiple users to be added to the organization, a feature I would like to mimic in my project for news outlets, in addition to Google Code's "issues" feature.

Next Steps

I recognize that the scope of my project is ambitious, and my current plan is to segment implementation into iterations -- to build an initial prototype to test within one publication and expand from there.

Journalism needs to become more open, like the web. Information should be shared. The collaboration between the New York Times and the Guardian over WikiLeaks data was very inspiring, two "competing" organizations sharing confidential information for publication. With my project, LedeHub, I hope to foster similar transparency and collaboration.

So, that's the proposal. There's still a lot to figure out. For example, what's the best way to motivate users to collaborate? What types of data can be committed? What copyright issues need to be considered? Should there be compensation involved? Fact-checking? Sound off. I'd love to hear your thoughts.

Keep up with all the new content on Collaboration Central by following our Twitter feed @CollabCentral or subscribing to our RSS feed or email newsletter:







Get Collaboration Central via Email

Katie Zhu is a junior at Northwestern University, studying journalism and computer science, and is particularly interested in human-computer interaction, data visualization and interaction design. She has previously interned at GOOD in Los Angeles, where she helped build GOOD's mobile website. She continues development work part-time throughout the school year, and enjoys designing and building products at the intersection of news and technology. She was selected as a finalist in the Knight-Mozilla News Technology Partnership in 2011.

This is a summary. Visit our site for the full post ».

May 10 2011

15:23

February 23 2011

20:10

Help Me Investigate is now open source

I have now released the source code behind Help Me Investigate, meaning others can adapt it, install it, and add to it if they wish to create their own crowdsourcing platform or support the idea behind it.

This follows the announcement 2 weeks ago on the Help Me Investigate blog (more coverage on Journalism.co.uk and Editors Weblog),

The code is available on GitHub, here.

Collaborators wanted

I’m looking for collaborators and coders to update the code to Rails 3, write documentation to help users install it, improve the code/test, or even be the project manager for this project.

Over the past 18 months the site has surpassed my expectations. It’s engaged hundreds of people in investigations, furthered understanding and awareness of crowdsourcing, and been runner-up for Multimedia Publisher of the Year. In the process it attracted attention from around the world – people wanting to investigate everything from drug running in Mexico to corruption in South Africa.

Having the code on one site meant we couldn’t help those people: making it open source opens up the possibility, but it needs other people to help make that a reality.

If you know anyone who might be able to help, please shoot them a link. Or email me at paul(at)helpmeinvestigate.com

Many thanks to Chris Taggart and Josh Hart for their help with moving the code across.

July 20 2010

22:06

How to Get Started With Github and Release a Gem Using Jeweler

Ruby logoThese are quick notes I’m sharing with the NYC Ruby Women’s group, which I organize. One of my developer friends, Peter Harkins, recommended I share them with the world at large, so here they are.

More about Ruby and the NYC Ruby Women’s group in a bit.

SOME HELPFUL LINKS
http://rubygems.org – official repository
http://ruby-toolbox.com/ – shows the most popular Ruby gems (how many people who’ve looked at it, how many have downloaded it, how many have forked it)
http://railsplugins.org/ – compatibility tracking of plugins and gems (What works with various version of Ruby and Rails 3)

SOME HELPFUL RUBY COMMANDS:
gem update –system – updates all gems on in your system
gem environment gemdir – displays the system directory for gems
gem help – basic help directory
gem env – shows the Ruby gem environment
gem list – find gems. You can include letters afterward as wildcards.
gem cleanup – deletes old gem versions
rake -T – Rake helpfile

====================================
====================================
Let’s get started…

INSTALL THESE GEMS (or check if you have them already):
(You may need/want to add “sudo” [no quotes] in front of each of these commands to install)
gem install rubygems-update
gem install thoughtbot-shoulda – Read Me at: http://github.com/thoughtbot/shoulda
gem install rspec-rails
gem install jeweler – Read Me at: http://github.com/technicalpickles/jeweler

============
Establish version control:
DOWNLOAD GIT:

http://git-scm.com/download

CONFIGURE YOUR LOCAL SYSTEM TO TALK TO GITHUB (once you’ve established an account at http://github.com)
git config –global user.name “Real Name”
git config –global user.email “youremail@foo.com
git config –global github.user username

SET UP YOUR PUBLIC KEY (See http://help.github.com/mac-key-setup/ (or your OS) for details)
Check if you have a key: cat ~/.ssh/id_rsa.pub

If you DO have a key:
$ ls
config id_rsa id_rsa.pub known_hosts
$ mkdir key_backup
$ cp id_rsa* key_backup
$ rm id_rsa*

If you DON’T have a key, then create one:
ssh-keygen -t rsa -C “youremail@foo.com

============

CREATE A GEM ON YOUR LOCAL SYSTEM USING JEWELER. (We’re calling our test gem “dabeers.”)
jeweler dabeers –rspec –rdoc –create-repo

#! If there’s a FileUtils problem (this may happen if you’re running Ruby 1.8.6), then:
#! mate /Library/Ruby/Gems/1.8/gems/jeweler-1.4.0/
#! require ‘FileUtils’ in generator.rb (if that’s the error)
#! jeweler dabeers –rspec –rdoc

VERSION YOUR GEM:
rake version:write
#! Since it’s our first rake, the version is set to 0.0.0. If you wanted something different for your initial version, write: rake version BUILD=alpha1 [or change "alpha1" a word or number without quotes]

UPDATE VERSIONS AS YOU UPDATE YOUR GEM:
rake version:bump:major
rake version:bump:minor
rake version:bump:patch

COMMIT TO GITHUB:
rake github:release

COMMIT TO GEMCUTTER:
rake gemcutter:release

Thanks to the NYC Ruby Meetup for the intro to Jeweler and Gemcutter and Peter Harkins for QA of these notes.

Related Posts:

  • No Related Posts
Share: Print Digg del.icio.us Facebook Google Bookmarks StumbleUpon Tumblr Twitter

Older posts are this way If this message doesn't go away, click anywhere on the page to continue loading posts.
Could not load more posts
Maybe Soup is currently being updated? I'll try again automatically in a few seconds...
Just a second, loading more posts...
You've reached the end.

Don't be the product, buy the product!

Schweinderl