I edit my blog using Git. Learn how I set up graphical software called SourceTree to make it easier.

Git != GitHub

• Git is software that provides “version control” over a directory full of files on a computer.
• GitHub.com is a for-profit website made to host files that are controlled with Git (sort of like Dropbox can host copies of your family photos).

Install SourceTree

I’m not going to cover installing SourceTree, but it’s a “graphical user interface” (GUI) for exploring directories on your hard drive that are “tracked” with the “version control” software called Git.

Ordinarily, people teach you how to keep track of changes to a codebase through Git’s command-line interface.

Great.

But I like GUIs. So I use SourceTree whenever I can.

However, once I installed SourceTree, I still had to tell it about all the sites online (BitBucket.com, GitHub.com, Heroku.com, etc.) where I’ve keeping stashes of code (“repositories” / “repos”) I care about.

SourceTree doesn’t directly edit the files on those sites. Instead, it follows standard Git protocol and helps me organize the act of downloading a copy of my “respository” to my personal computer, tracking changes I make to my PC’s copy of files in the “respository,” and uploading those changes in an organized manner back to GitHub.com, BitBucket.com, etc.

Telling SourceTree About A “Remote Repository” from GitHub.com

1. Grab the URL. It's something along the lines of:https://YOURGITHUBUSERNAME@github.com/YOURGITHUBUSERNAME/REPOSITORYNAME
2. Open SourceTree; click File -> Clone/New. Click the "Clone" button near the top if you're not already in it.
3. In the "Source Path / URL" enter the URL you obtained in step 1.
4. The moment you hit "tab" to move onto the "Destination Path" box, you'll get a popup that says "Authenticate," with YOURGITHUBUSERNAME populated into the "Username" field and a blank "Password" box. Type your password to your GitHub account. Check the "Remember Password" box. Click "Login."
5. SourceTree will probably have already populated the "Destination Path" box with a filepath named something along the lines of C:\Users\YOURUSERNAMEONYOURPC\Documents\REPOSITORYNAME. I like to change that to something more meaningful. Also, you don't have to call the final folder "REPOSITORYNAME." For example, I'm going to grab a repository called "testprivaterepo" but save it as C:\example\GitRepos\VeryCoolRepositoryNumber1.
6. SourceTree will probably populate the "Name" box with whatever the final folder of "Destination Path" is. For example, it switched it from "testprivaterepo" to "VeryCoolRepositoryNumber1" on me as soon as I hit "tab" from setting up the path on my hard drive where I wanted to store a local copy of my GitHub content. I decided to change that to "Awesome Repo 1".
7. Leave everything else alone and click the "clone" button.

Note: these instructions presume you haven't already told your computer about the GitHub.com-based "remote repository."

• If you have (e.g. through "git clone" on a command line), then in step 2 of the instructions above, you'd click the square "Add" button, not the square "Clone" button, and would "Browse" to populate the "Working Copy Path" box with the folder where you already put a local copy (e.g. C:\example\GitRepos\VeryCoolRepositoryNumber1).
  • You wouldn't give SourceTree a URL and a folder it should put the local copy in, since that's already been done.
• You could ignore steps 3-5 of those instructions.
• You would still choose your own "Name," e.g. "Awesome Repo 1," in the "Name" box if you want to.
• In step 7, you'd click an "add" button instead of a "clone" button.
  • If not, you'll need to click the Add button and add it. Upon doing so, you may get prompted for a username and password to your GitHub account and asked if you want to save it. (Or SourceTree might wait until the first time you try to interact with the "remote" repository, such as pulling/fetching data from it, or pushing data to it.)

Verifying that setup went well

1. If I navigate to C:\example\GitRepos\VeryCoolRepositoryNumber1 on my computer, I see that it has all the same files in it that can be found by navigating in a web browser to https://github.com/MYGITHUBUSERNAME/testprivaterepo/. Cool!

Editing a file and updating GitHub.com’s copy with the changes

Editing the file

1. One of the files now on my computer files is “readme.md” a plaintext file with a “useful explanation about my repository.” (Right now, it doesn’t actually say anything but “Testing 1 2 3” inside of it.)
2. Editing was simple: I opened C:\example\GitRepos\VeryCoolRepositoryNumber1\readme.md in Notepad++ on my computer and change the “1 2 3” to “4 5 6,” then saved the file on my computer.

If I go into SourceTree, I have “Awesome Repo 1” open as a tab across the top.

(If not, I can click the “+” tab and open it from the list of repos at right.)

Clicking around, I can see that there are various places where I can see alerts that I’ve changed the contents of “readme.md” on my hard drive.

Diversion: “anonymizing” myself a bit

Before I go any further, though, I have one more piece of “setup” I want to do with “Awesome Repo 1.”

1. From the navigation bar at the top of SourceTree, I click “ Repository” -> “Repository Settings.”
2. The popup starts displaying the contents of a tab called “Remotes” with a cloud icon that has a single item in its list, “https://MYGITHUBUSERNAME@github.com/MYGITHUBUSERNAME/testprivaterepo”. But I’m going to click the “Advanced” tab with a gear icon.
3. Under “User Information,” I’m going to make sure that “Full Name” & “Email address” are set to values that I am comfortable making part of the repository’s history. You see, I first set up SourceTree with some work accounts, and I keep a meaningful name and work e-mail address as the default because that’s my primary use of SourceTree. However, for personal side projects, I’d rather use something a bit more … anonymous.
4. So I’m going to change the username to “ xyzzy ” and the email address to “ abcdefg@example.com ” and make sure “Use global user settings” is un-checked.
5. Then I click “OK.”

Verifying my “anonymization” took hold

1. If I go into File Status -> Working Copy (left nav), I can see that my old info is still there, near the bottom of the screen, below the “Staged Files” & “Unstaged Files” sections of the screen.
2. So I close and re-open SourceTree. (Lots of stuff gets better in SourceTree when you close and re-open it.)
3. Now if I have “Awesome Repo 1” open and go to (left nav) File Status -> Working Copy , I can see at the bottom of the screen that I’m identified as “ xyzzy <abcdefg@example.com> ”.

Yay.

So now I’m ready to use SourceTree to tell the internet (github.com) about the changes I made to “readme.md.”

“Staging” (“adding”) my changes

If I click on the orange pencil icon next to “readme.md” in the “Unstaged files” list, to the right of the “Staged Files” & “Unstaged Files” sections of the screen, content appears under the heading “readme.md” and shows me that I’ve deleted a line from my file containing the text “Testing 1 2 3” and added a line in its place called “Testing 4 5 6.”

Great! That’s what I expected to see.

I “stage” readme.md by:

1. Clicking “ Stage Selected ” (or “Stage All”, I suppose)

If I suddenly think, “Wait! Am I sure I wanted to do that?” I can still see the changes by clicking on “readme.md” up in the “Staged Files” section of the screen, center, near the top – the changes will again show up along the right side of the screen.

Here, I just changed one file, but I could totally stage multiple files as part of a given “change” I want to “track.”

“Committing” and “Pushing” my changes

Once I feel good about my changes, I have two things to do (although I can do them at the same time, which I typically do).

1. The first is called a “ Commit ” and adds an official history checkpoint to the “version tracking” logs stored in Git on my local computer, with an optional (but recommended) comment saying what I did that was so worth adding to the logs.
2. The second is called a “ Push ” to my “ remote repository ” and shoots the updated “readme.md” file contents, as well as the “version tracking log with its comment,” over to github.com, in response to which github.com will update its copy of “readme.md” and add the “version change note” to its log. In other words, I’ll get the copy on github.com in sync with the copy on my local computer.

Near the bottom of the screen (remember, I need to be in the “ File Status -> Working Copy ” section of SourceTree), there’s an area that says “xyzzy <abcdefg@example.com>” next to a little blank-headshot icon.

Below that is an area to type a comment.

1. In the comment box, I’ll type, “This is my first change from a local computer.”
2. THEN – and this is the part that lets me do “commit” and “push” at the same time – I will click the checkbox directly beneath the comment area (at left) that says, “Push changes immediately to origin/master.”
3. NOW I will click the “Commit” button at bottom-right.
4. If I forgot to click the checkbox, the “Push” button near the top left area of SourceTree will have a “1” in a circle; I can click it to do the “push” step (just click “OK” through all the prompts, basically).

Verifying that GitHub.com is up-to-date

Now if I navigate in my web browser to https://github.com/MYGITHUBUSERNAME/testprivaterepo/blob/master/readme.md, I can see that its contents say “Testing 4 5 6.” Great!

And if I click the “History” button on that page, it takes me to https://github.com/MYGITHUBUSERNAME/testprivaterepo/commits/master/readme.md, and I can see that there’s a line of the history from “xyzzy” claiming, “This is my first change from a local computer.” Fantastic!

Editing again and updating GitHub.com again

From here on out, to edit files on my computer and tell GitHub.com about them, I just repeat the steps above – open up files in Notepad++ or some other appropriate editor (maybe Paint or GIMP if it’s a picture), make sure SourceTree knows about the changes, and Commit+Push.

Note: if you rename a file or folder, it will typically show up in “Unstaged Changes” as 2 changes – a delete and an add – but then go to “Staged Changes” as a rename. It will also show up in the history as a rename once committed as long as it shows up in “Staged Changes” that way.

• Renames show up with a blue R box in SourceTree
• File additions show up with a green + box in SourceTree
• File deletions show up with a red - box in SourceTree

Syncing someone else’s GitHub.com-side changes into my computer’s copy

Now … what if I leave my computer alone for 5 months, but in the meantime, I edit some files directly through GitHub.com’s file-editing interface?

Or what if I’m collaborating with someone else who “pushed” changes to my GitHub.com repository while I was busy doing something else?

All the files on my hard drive are exactly as I left them on my hard drive 5 months ago. They don’t magically stay in sync with whatever’s on GitHub.com.

Seeing as I think of the repository hosted on GitHub.com as “the main copy” of my code, I don’t want to just ignore everything that’s going on there and blindly edit 5-month-old files on my computer.

If it’s been a while, I need to get a copy of GitHub.com’s present state downloaded to my computer – probably before I start making any changes on my own computer.

(How often I need to do this depends on whether I’m the only person who can edit the GitHub repository – if I am, I can safely know where I’m making my edits and keep on editing over and over again on my computer if I know I haven’t gone out and edited things directly on GitHub.com’s web interface in the meantime.)

• Q: Do I need to get a copy of what’s out there on GitHub.com BEFORE I start making changes? Or can I just make some changes to an “old” copy of my code that’s sitting around on my hard drive and worry about “cross-checking” before I try to actually “push those” changes back to GitHub.com?
• A: It depends.

1. If the changes you’re making are going to take you 2 weeks to code, and if other people need to work as well during those 2 weeks, you probably would do the latter.
   • After downloading a copy at the beginning of the 2 weeks, you might work on it while blindly hoping no one else is making incredible-headache-causing changes to the code at the same time.
   • At the end of the two weeks, when trying to “push” your changes back to GitHub.com, you would have to resolve any conflicts with other people’s work over the last 2 weeks.
   • (By the way, in that case, you might have done lots of local “Commit” operations to your local computer’s “version history” for your own checkpointing information without “pushing” to GitHub.com.)
   • This approach involves lots of complicated stuff that is actually the subject of most Git tutorials on the internet , but that I am not covering today.
2. On the other hand, if the changes you’re making are going to take you 5 minutes to code, and you’re pretty sure no one else is going to do anything meaningful to that code, and you don’t have any outstanding 2-week-long projects in the works (in other words, you don’t have code on your local computer that you care about that isn’t already on GitHub.com), I recommend completely wiping out the contents of your local copy of the repository so that its file contents, and its history log, are exactly what’s currently on GitHub.com.
   • Unfortunately, you can’t do this in SourceTree, and it often makes SourceTree run slowly if you even try to do it while SourceTree is open.
   • But it’s what I do in all my “solo repositories” and “quickie-project repositories” where the “remote” (e.g. GitHub.com, BitBucket.com) repository is the “source of truth” and my computer’s copy is just a “convenient workspace for short projects.” So that’s what I’ll explain next.

To change my hard drive’s repository to be more like if I had freshly set it up in SourceTree from GitHub.com like I did at the start of this blog post, I would:

1. Close SourceTree
2. Open a cmd prompt (Windows key on my keyboard, type “cmd”, hit “enter”)
3. Type the command cd c:\example\GitRepos\VeryCoolRepositoryNumber1 and hit “enter”
4. Type the command git fetch --all and hit “enter”
   • If your computer complains that it doesn’t understand the command “git,” Google some tutorials about setting up your computer to understand calls to “git” from the command line. Git is already installed on your computer from when you installed SourceTree, so it’s probably just a question of configuring Windows’s “environment variables” / “PATH” to know that whenever you say “git” from a command prompt, you mean the “git.exe” file that SourceTree installed onto your hard drive in some folder somewhere. Mine lives at C:\Users\MYUSERNAMEONMYCOMPUTER\Documents\A_FOLDER_WHERE_I_SOMETIMES_INSTALL_SMALL_THINGS\Git\cmd\git.exe, which means I need C:\Users\MYUSERNAMEONMYCOMPUTER\Documents\A_FOLDER_WHERE_I_SOMETIMES_INSTALL_SMALL_THINGS\Git\cmd as part of my “PATH” “environment variable.” That’s a folder I created, so I think I must’ve installed command-line-only Git by hand long before I set up SourceTree, and I must’ve told SourceTree not to bother to install Git (and to use the copy I’d installed instead) when I installed SourceTree. It’s been years, though, so not sure. You will find “Git” in a different place on your computer. For starters, though, just try the command and see if it already works.
5. At the prompt that says, “Password for 'https://MYGITHUBUSERNAME@github.com':”, type my password to GitHub.com and hit “enter”
6. When it finishes, type the command git reset --hard origin/master and hit “enter”
7. If I see the note, “HEAD is now at SOME_CODE MOST_RECENT_COMMENT_FROM_GITHUB.COM_HISTORY”, I’m good to go!
8. Type the command exit and hit “enter”
9. Re-open SourceTree (or, if I forgot to close it, close it now and re-open it).
10. In SourceTree’s left navigation area, expand the “ Branches ” section, click “ master ,” and verify that to the right, towards the top, the change log history looks exactly like it does on the web at https://github.com/MYGITHUBUSERNAME/testprivaterepo/commits/master, and that nothing I had only done on my computer still exists.

I am now ready to start coding on my computer as if contributing to GitHub.com’s copy of the repository for the very first time!

As before, I can edit local copies of the files as I see fit, save them to my hard drive, and use SourceTree to double-check that I like the changes, “commit” notes about my changes to my local-computer-repository’s “version log,” and then “push” the changes and “version notes” out to GitHub.com.

Happy git-ing!