Subscribe to this blog!

Newbie guide for using GitHub in Mac OSX

First of all, note that I’ve said ‘newbie guide’ and not ‘guide for newbies’ ;). I’ve been using Subversion for years but I knew nothing about Git. As GitHub is quite popular these days and I want to publish some code in this blog, I’ve written this little guide for helping me to remember how to get it working. I hope you’ll find this useful too.

Set up Git

First, you need a GitHub account. If you’ve been in a coma, just woken up and you know nothing about this code hosting service, I’ll tell you that is free as long as you use it for open source projects. The repository will be public. In case you want your repositories to be private, you can sign up for a paid account.

Once you have your account, you’ll need to get Git correctly installed. Use the GitHub guide for Mac OSX. There are a few simple steps and you’ll have to do it only once.

Set up Git in OSX – GitHub help

Download GitHub for Mac

You can control your git repositories through the command line but I wanted to make the transition smooth, so I downloaded the GitHub client for Mac. I’ll use the client for the rest of the guide so I recommend you to install it.

Download GitHub for Mac

Once you have it installed, you’ll see nothing, assuming that you’ve just opened your account and you don’t have any repository yet.

GitHub for Mac

Now, we’ll create a repository in GitHub and connect it to a folder in your computer.

Create a repository

To create a new repo, go to your account page (click your name in the upper bar) and push the ‘New repository’ button.

Create new repository

In the next page, fill in the form with the desired name and description.


Enter the repository name and description

After that, you’ll see a page with several instructions. Skip the ‘Global setup’ section since you executed that two commands already while setting up Git in the first place. Go on with the ‘Next steps’ section. Open a terminal and make the directory where you want to place the local repo. These commands will have different parameters depending on your selected name and account.

Next steps for creating repo

After doing this, you’ll see the new repo with the empty README file in your GitHub account.

First commit done!

Now, we’ll take care of our local repo with the GitHub app. Open GitHub and go to ‘GitHub > Preferences’.

Open GitHub app > Preferences

Select ‘Repositories’ page and then click on ‘Scan For Repositories’.

Scan for repositories

Select the folder where you created the repository. It’ll be showed in a list. If is not selected, select it.

Select local repository

From now on, you’ll have this local repository available in the main window of the app.

Your local repository is now available through GitHub app.

Click on the arrow ont the right side of the repo box and you’ll access to the repo page, where you can watch its story, changes, branches and settings. Modify the README file in an editor and you’ll see how ‘Changes’ page reflects that. I’ve added a couple of lines to the file, as you can see in the right zone of the page.

Changes page

Now, as far as I’ve understood, if you want your changes to be reflected in the repository there are two steps to do. First, when you commit your code, your local repo will be updated. This is done using the ‘Commit Changes’ button. Next, if you want your changes to be published in the remote repo, i.e. the GitHub repo, you can sync that commit or simply push it. Sync will bring in changes from the remote and push any pending commits. This is the option that GitHub recommends in its help.

You can see your unsynced commits in this same page. When you’re ready, push the ‘Sync’ button and your code will be updated in the remote repo.

Syncing repo

That’s all, folks! Now you have your project in GitHub, synchronized with your local folder. You can begin to add your source code as any new file will appear in the ‘Changes’ page.

Using GitHub for your Xcode projects

If you plan to use your repo to host a Xcode project, the first thing recommended is to create a .gitignore file. It’ll avoid to push unneccesary files. After searching for the right ignored files in the internet, I found the one in CodeDifferent the most complete one.  Kudos to Christian for writing this file. I reproduce it here.

You can write the .gitignore file directly in the GitHub app. Go to the repo settings page, paste the text into the ‘Ignored files’ box and save changes.

Ignored files

Now you’re ready to create a new Xcode project. Proceed as always, but make sure that you create the project in the folder where you have set the local git repository and don’t check the ‘Create local git repository’ option.

As you add files to your project, they’ll appear in the ‘Changes’ page.

But wait… why don’t you use the local git repo option in Xcode?

That was my first option. I thought it’d be a walk in the park but I failed several times to get my local git repo made by Xcode correctly synched with GitHub. I didn’t find an easy way in the internet so I did the steps in this guide instead. When I’ll get used to Git I’ll try again and post another guide to use the Xcode way. If you have the solution, feel free to post it in the comments section.

Local Git option in Xcode

Have a nice commit!

  • Brandon Butler

    I’m contemplating using the github app to commit files instead of using xcode. Do you have any thoughts on this? Xcode always seems to give me an error for something. I had a problem merging a branch but used the github app to do it sucessfully. Good find on the ignore list 😉