Using GitHub to Share with SparkFun

Contributors: SFUptownMaker

Committing, Pushing and Pulling

Now that you've got a local copy and a copy on your GitHub account, there are four things that you'll need to know how to do in order to collaborate with SparkFun:

• Commit - committing is the process which records changes in the repository. Think of it as a snapshot of the current status of the project. Commits are done locally.
• Push - pushing sends the recent commit history from your local repository up to GitHub. If you're the only one working on a repository, pushing is fairly simple. If there are others accessing the repository, you may need to pull before you can push.
• Pull - a pull grabs any changes from the GitHub repository and merges them into your local repository.
• Sync - syncing is like pulling, but instead of connecting to your GitHub copy of the forked repo, it goes back to the original repository and brings in any changes. Once you've synced your repository, you need to push those changes back to your GitHub account.

Committing

The first step in getting a change back to us is to commit it to your local repository. Look at this sequence of commands:

Again, one command at a time:

• git status - checks the current status of the repository. This tells you a lot of things; at the moment, it's telling you that you don't have any uncommitted changes in your repository.
• touch README.md - create a README file. The .md suffix is indicative that the file will be formatted in Markdown, which is widely used for formatting on the GitHub website.
• git status - same command, second time. This time, you can see that there's a new file, but it's "untracked". That means it won't be included in the commit. You'll need to add it, first.

• git add . - add all untracked files to the repository (at least, those untracked files which are not omitted by the .gitignore file). You can, of course, add files individually by replacing the . with the file name.
• git status - now the README.md file is showing as a new file to be committed.
• git commit -m "Add README.md" - commit the recent changes. The -m switch allows you to enter a short double-quoted commit message. Omitting that switch will cause git to open a text editor so you can enter a longer message; save and close the text editor when you're done.

Pushing

Pushing sends your changes up to GitHub, so they can be shared with the rest of the world. It also serves as a hedge against data loss.

• git status - our status tells us we have no local changes pending, but that the remote is one commit behind. This isn't actually checking against the remote repository, just letting us know how many times we've committed since our last push.
• git remote -v - check out where our remote target is. We'll revisit this in a bit, when we start working on syncing to the original repository.
• git push -u origin master - push the changes in branch master (we're going to skip branches, in order to keep this tutorial kind of easy) to remote location origin, and remember the settings (-u).

Pulling

Pulling is the opposite of pushing--it retrieves changes from the remote location and applies them to your local repository. You probably won't do it that much; it's more useful in a group environment where more than one person is submitting changes to a single repository.

Visit the repository page again; you'll see that, since we pushed it back to GitHub, the README.md file is now in the file list. We can change the text in that file right on GitHub, then pull the change back down to our local repository. Start by clicking the file name link. That'll give you this page:

Since we didn't put anything in the file after we created it, there's nothing on the page. You can add something to the file by clicking the "Edit" button:

At the bottom of the page, you'll find a commit window which lets you put in a description, an extended description, and commit the changes.

Now that you've made a change on the server which is not reflected in your local repository, we'll need to pull it down.

• git status - note that even though we know there's a difference on the server, git status does not reflect that, because it only gives us status on the local repository.
• git pull -u origin master - the syntax is the same as push, but the changes go in the other direction.

At this point, our local repository is in sync with our GitHub repository. But what about the original repository? What if something has changed there, and we want to bring those changes into our copy (both local and on GitHub)?