Open Source Comes to Campus/Curriculum/Git/Students

Visiting the project on the web

Since this project is a website, we've specially configured the repository so that whenever there is a push to it, it is made visible on the web.

If your group's repository is called e.g. waffle-castle.github.io, then you can see that the shared version is visible on the web at http://waffle-castle.github.io/. (This is just an example. Your group's repository page should be at schoolname-#.github.io (for example, princeton-1.github.io or princeton-2.github.io.)

But note that any changes in your fork won't show up there until the maintainer of the project merges those changes in.

To fork a project on Github

• Start out logged in to Github

• Visit the project you want to fork

• Click the "Fork" button in the top-right

• Wait for the animation to conclude

• Notice that your browser is now visiting a copy of the project in your personal space, rather than the old, group-owned one. You should also see a "forked from..." remark in the top-left.

Now, clone to it to your computer

• On the right side, look for the clone URL

• Copy that to the clipboard

• Open a terminal and type: "git clone " (including the spaces, but not including the quotation marks)

• Use your terminal to "paste" the URL in. (Make sure it starts with https; if not, you'll need to use an ssh key and most students probably won't a key already set up)

• Press enter to do the "git clone" operation.

• Once you've done that, "cd" into the directory.

Make sure you have the project properly set up

• Open index.html in your favorite text editor -- it should look like a regular HTML page

• Open index.html in your favorite web browser -- it should render basically the same as http://purdue.openhatch.org/

• Make a test change in index.html, save, and reload in the browser. Make sure what you see in the the browser reflects that change.

• Undo that change, with your editor, save, and then reload in the browser. Make sure what you see in the browser reflects that change.

Find a task

Now, find a bug on the project's issue tracker that you will work on, and claim it by leaving a comment on the issue saying so.

(Before you do that, make sure to refresh the page and check that no one else has claimed it while you were reading and deciding.)

Resolve the task

How you do this depends on the issue you've chosen. If you run into a problem you can't seem to solve, try asking the student next to you or one of the mentors.

Make sure to open up index.html and check that your solution works.

Commit and push

Once you're finished making changes, you can use the following command to get a list of files you've changed:

   git status

You can commit your changes by typing "git add" followed by the files you've changed, for instance:

   git add index.html

Once you've added the changes, you can "commit" them with a message specifying what you've changed.

   git commit -m "Explanation of my changes"

Now, publish those changes on Github by typing:

   git push

You will be prompted for your username and password. (If you find constantly entering your username and password annoying, there's an alternate method we can show you called SSH.)

(Alternatively, you may be prompted to set your name and email address. This means you missed a step in setting up git. No worries, you can set them now.)

You can now visit Github and make sure your personal fork contains those changes.

Create pull request

Visit your personal fork and click the "Pull requests" button on the right. This will offer you the chance to make a new pull request by clicking on "New pull request". Explain what you did, and leave a remark that this relates to the issue number you saw.

Now, get feedback from the project's maintainer (the mentor leading your group) and eagerly await your pull request getting merged!

Once merged, visit your changes on the web

When your changes are merged into the main project repository, our specially configured repository will update the group website with the merged files.

This is a special trick that we do during the Website editing with git exercise, using Github Pages. It demonstrates that when the merge happens, it can programmatically cause a different event; this is often called hooks.

Advanced/Optional Commands

(This section is in progress.)

Setting multiple remotes

The copy of the repository you have on your computer is called your "local" copy. The copy on Github is a "remote". You can see what remotes are associated with your local repository by typing the command:

git remote -v

You should see something like this: origin url/$yourusername/$repositoryname (fetch) origin url/$yourusername/$repositoryname (push)

Origin is the default name for your remote repository. The URLs should correspond to the URLs you used in the "git clone" command above. There are separate listings for "fetch" and "push" because [??????].

Right now your only remote is your personal copy of the repository. That's fine for pushing changes, since you need to go through the personal copy to submit pull requests. But what if you want to get an up to date version of the main repository?

To do this, first you need to add the main repository as a remote. Type:

git remote add $name $URL

When you do the "git remote -v" command, you should see that you now have two sets of fetch/push listings. To get an updated version of the main repository, you can type:

git fetch $name-of-main git merge

To update your remote personal repository, you can type:

git push origin master

That's it! You can add as many remotes as you'd like, although for the most part people stick to one or two.