Introduction to Git & GitHub

Before we start

GitHub and social coding

Git is a way to share, edit, and discuss code. GitHub makes this so much easier. There are a lot of major and minor projects tracked with Git, like Linux, Apple's Swift language, and even this Maptime Seattle website.

Before we start, it's important to remember:

Git is an active workflow.

There are many ways to accomplish the same thing with Git & GitHub.

Our goals today:

  1. Open the Git Dictionary
  2. Git on the command line
  3. Tutorial: personal workflow
  4. Tutorial: branching
  5. Tutorial: fork & pull
  6. Tutorial: merge conflicts
  7. Introduce GitHub pages (if time permits)

Git vocabulary quest

For the majority of this tutorial, I'll reference Git & GitHub interchangably. They are very different, but I'm tired of constantly saying "Git and GitHub".

Git Dictionary

Tutorial Specific Dictionary

Introduction to the command line

Git workflow: personal

  1. Create a personal project on GitHub (name it whatever you want)
  2. Open your command line and clone the new repository onto your local computer git clone repo
  3. Add a new file called README.md and write something
  4. Check the status of your Git project with git status
  5. begin tracking the new file in Git by adding it. git add README.md.
  6. Check the status again to see the difference git status
  7. Commit the file with git commit -m 'your message'
  8. Push the changes to your remote with git push origin master.

You'll notice changes on your GitHub page! But what if you didn't want to push changes directly into the master branch? What if you were experimenting with something new and wanted to push it up to GitHub for someone to see, but not commit directly to the main project?

Git workflow: branching

  1. Back to your local computer, create a new branch with git checkout -b new-branch-name. This command -b creates a new branch AND checks it out.
  2. You can list all branches and see which branch you are currently on with git branch
  3. Make some changes and add those changes with git add README.md (or if you are adding a new file)
  4. Commit those changes with git commit -m 'my cool new feature experiment'
  5. Push those changes to a new branch on your remote with git push origin new-branch-name
  6. Create a pull request on GitHub and write up the changes you made!

In an organizational setting, this will notify project maintainers of your changes and give everyone a chance to review and comment on the pull request. Others can pull this code into their local, make changes, and push up to the same branch, which will update the pull request accordingly.

Git workflow: fork and pull

Sometimes you won't have the ability to add a new branch to a project because you aren't listed as a maintainer. You can still contribute!

  1. Fork a repository you want contribute to
  2. Clone your fork to your local machine git clone https://...
  3. Make changes
  4. Push up to your remote fork
  5. Go to the main repository and create a pull request from your fork into the main project (you won't be able to merge this, only a maintainer can merge)

Let's try this same workflow with the maptimesea geojson repository. Follow the steps here: https://github.com/maptimesea/geojson#geojson

Fixing a merge conflict

Remember, Git is active! If things are broken, you've gotta fix them. Most of the time, this comes down to "merge conflicts". This typically means the code that you have doesn't match the changes of the code in a remote, and if you were to merge your code in, you'd lose someone elses work. The best way to learn how to fix a merge conflict is to see one, and try fixing it.

With the same geojson repository fork, add a location the EVERYBODY.geojson file and make a pull request again. This time, we'll all be adding to the exact same file, insted of unique files.

Depending on which pull request is merged first (before yours), you'll likely see a message from GitHub that your fork cannot be automatically merged into the MaptimeSEA repository because it is missing commits. Here's how to remedy:

  1. Get all of the changes from the primary repo (called upstream) with git fetch upstream
  2. Merge all of the upstream master branch changes into your fork's master with git merge upstream/master.
  3. You may see a merge conflict! That's okay - we can fix this. Open EVERYBODY.geojson and you'll notice some odd lines like >>>>>>>> head or something similar. This is showing you what the primary file looks like, and what your current file looks like, and why they can't be automatically merged.
  4. Manually fix the file to include all additions to the GeoJSON file (This is where being active and intentional about your code is important. It is up to you to know what code should be included).
  5. Once updated, run git add EVERYBODY.geojson
  6. Commit the file again git commit -m 'fixing merge conflicts'
  7. Push to your fork's master branch git push origin master and you'll see the pull request automatically update with your changes.