Hi! This is a guide to help you follow along with the "introduction to git" activity - or, if you're not at an event with a mentor, to do it on your own.

Overview (ie The Plan)

There's a repository sitting on Github which contains a list of cool people in open source - a directory, if you will. You're going to make a copy of the directory, edit it, and use it as your own! (For now, at least. You can delete it later if you're shy.)

Let's get started!

The Activity

Visit 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. Github allows you to do this with repositories that have the following name scheme: $user-or-organization-name.github.io

So for the organization FOSSdirectory, we call the repository: FOSSdirectory.github.io And we can see the site live at http://fossdirectory.github.io/.

You should have already signed up for Github and created a user account. (If not, do so now!) When you make your repository, you will eventually name it {your username}.github.io.

Fork a project on Github

To "fork" a project means to make a copy of it. You can't edit the original - somebody else owns it. But you can edit your "fork".

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 it's time to rename the repository. You don't have to do this every time you fork a project, but you'll need to in order to make your site viewable on the web. To edit the repository name, go to "Settings", which is towards the bottom of the toolbar on the righthand side of your page. The top option should be the rename option. Change the repository so it's name follows the format: {your username}.github.io.

Your webpage will not show up immediately. It usually takes 10-20 minutes for Github to put new x.github.io pages online.

Now, clone the repository to your computer

You have a personal copy, but it's on Github (what git calls "a remote"), and not a local copy you can easily edit. We call the process of making a local copy "cloning".

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://fossdirectory.github.io/

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.

Add your username to the directory

The first thing we're going to do is make a simple change: you're going to add your username to the directory page.

To do this, open up directory.html. Find the list of links to users. If you're familiar with HTML, it should be easy enough for you to find. If you're not familiar with html, the line you're looking for looks like this:

   <a href="#" class="list-group-item">A person!</a>

You want to add two piece of information. First, replace "A person!" with your github username. Then, between the quote marks after "a href", add a link to your website (http://{yourname}.github.io).

Commit and push

Once you've made your change, 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 directory.html

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

   git commit -m "I added myself to the directory!"

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

But what good is a directory of one? You'll want to send your change back to the original repository so it can keep track of all the cool new people making profiles. To do this, you'll want to create what's called a "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, to make it easier for the repository's maintainer.

When the changes are accepted back into the original, it is called "merging".

Once merged, visit your changes on the web

When your changes are merged into the main project repository, the website will be updated with the merged files.

Sometimes your changes will not show because of caching. To get around this problem, add "?" to the end of the url.

Now edit your profile

Now you can go back to your local copy and edit your profile. To do this, make changes in index.html by opening it up in your favorite text or code editor. There are html comments next to the sections with text to edit. You should also feel free to make changes to the HTML and CSS, or to add additional images, code, etc as you desire.

Once you've made your changes, you can follow the steps above to push the changes to your website.

Congrats! You've made yourself a profile - and successfully used git!

The Follow Up

You might say "Wait! I want a copy of that awesome, full directory for my own site. How do I get those changes back?"

There's totally a way to do it, but it's kind of complicated. If your mind is already full with the above activity, you should take a break, and come back to this later if you want to.

Alright. Ready?

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 https://github.com/$yourusername/$your-repository-name (fetch)
   origin https://github.com/$yourusername/$your-repository-name (push)

Origin is the default name for your remote repository. The urls you see should correspond to the urls used in the "git clone" command above. 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, you'll need to add the main repository as a remote.

Below, replace $name with whatever you want to label the remote, and $url with the github url for the main repository (that is, https://github.com/FOSSdirectory/FOSSdirectory.github.io.git). Execute this command.

   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 update your remote personal repository, you can type:

   git push origin master

If you try to update the main repository directly, by typing:

   git push $name master

You should get an error, as you don't have push access to the main repository.

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

Pulling from the original repository

You want to get the most up to date version of directory.html from the original repository. To get an updated version of the main repository, you can type:

   git fetch $name
   git merge $name/master

In our case, though, this will cause a merge conflict. A merge conflict happens when two people (or the same person, at two different points in time) edit the same part of the same file. In our case, this happens both in index.html and directory.html. Let's take a moment to think about it.

Your personal repository should have an index.html that's been customized to you. The index.html from the original, however, will only be the blank template version. You want to keep your index.html. Your directory.html is mostly empty, however, while the directory.html from the original has been updated with links. You want to add their directory.html.

There are two ways to do this. We'll go over both.

Option A: Discard/keep within files

There are a number of tools you can use to help visualize merge conflicts. For simple conflicts, though, I like to use a basic editor, such as nano, vim, emacs, or whatever you're most comfortable with. To view the merge conflict, open the file that the merge conflict is in. In basic text view, it looks like this:

To resolve the conflict, scroll through the document until you find sections with these markings. The "========" line separates the two options that are in conflict. Choose which one you want to keep by deleting the other. Then delete all of the markings. Do this for each conflict and then save and exit the file.

You will then need to add and commit your changes.

Option B: Discard/keep whole files

Dealing with merge conflicts can get messy, especially when there are a lot of changes and you want to keep things from both versions of the file.

In our case, though, we don't want to take things from each version of the file. We just want to update one file, directory .html.

Luckily, there's a way to to this at the file level:

   git checkout --theirs directory.html

Again, once you have done this you will need to add and commit your changes.

Further Study

There's a lot more we haven't covered - though the above should be more than enough to get you contributing to new projects.

Here are some additional resources for learning about git and Github:

Git manual
Atlassian's git tutorials (I especially recommend the tutorials for branching.
Github's help section
Git Immersion - Covers some of the same stuff this tutorial does, possibly helpful if you're still confused.
Try Git - More tutorials. :)

Open Source Comes to Campus/Curriculum/Directory

Contents