VAPOR 3: Learn Server-Side Swift with hands-on projects >>

How to save and share your work with GitHub

Paul Hudson    May 12th 2018    @twostraws

Part 5 in a series of tutorials on modern app infrastructure:

  1. How to refactor your code to add tests
  2. How to add CocoaPods to your project
  3. How to clean up your code formatting with SwiftLint
  4. How to streamline your development with Fastlane
  5. How to save and share your work with GitHub
  6. How to validate code changes using CircleCI


Although the term itself is relatively recent, open source software has been around since software has been around – teams in different universities used to just mail each other their source code.

These days, most developers store their source code on GitHub, and as a result it has become the largest repository of open-source work in existence – it hosts over 80 million repositories are stored there, with thousands more added every single day. Even better, if you’re happy releasing your code under an open source license that allows others to use your code, GitHub doesn’t cost a penny – it’s free!

In this fifth part of our series on modern app infrastructure we’re going to look at how to save our work to GitHub then share it with others. This process won’t take long, so afterwards I’m going to provide you with a useful primer of some other helpful source control commands because it’s such a useful skill for developers.

  • If you’d like to learn more about Git, I have a whole book about it and other useful topics that all coders should know: Beyond Code.

Why use version control?

GitHub is powered by Git, which is a version control system – software responsible for tracking changes to software projects in a safe way, so that all changes we make are stored for later reference. There are other version control systems available, but at this point Git is the overwhelming favorite – if you’re not using it you’re usually viewed with curiosity, distrust, or perhaps even pity.

So, Git is the standard tool for source control, which means you need to learn to use it. That, however, is easier said than done. In fact, learners usually get told various lies about Git, in a conversation that goes something like this:

  1. “Git is easy to use.”
  2. “Well, Git's not easy to use, but it is easy to learn.”
  3. “OK OK OK... Git's not easy to learn at first, but it is easy to learn once you understand that...”

...at which point their eyes glaze over as the Git-fiend goes off on multiple tangents trying to find metaphors that explain how “easy” Git is.

Here’s the blunt truth: Git isn’t simple. In fact, it’s the opposite: Git is really hard. Years ago I met a developer called Andrew Morton, who is one of the longest-serving and most senior developers of the Linux kernel. This is a guy who knows his stuff, and has years of proof of that. And yet here’s how he describes Git: “A version control system that is expressly designed to make you feel less intelligent than you thought you were.” Worse, the Git documentation is so desperately bad that someone wrote a generator to create fake Git man pages and they still look totally real. Seriously, try it yourself at https://git-man-page-generator.lokaltog.net.

So, when you’re using Git and think it’s taking up a lot more brainpower than you had expected, don’t fret: you’re not alone. And in fact even once you’ve mastered Git, there’s a chance you won’t like it. Many people do like it, and some people even love it, but most people would rather spend their time writing code rather than spending time working with complex tools to manage that code.

To make things easier, many IDEs – include our beloved Xcode – bundle visual implementations of Git commands, so that you can in theory handle source control without going near the command line. While I think these tools are extremely useful once you understand what’s going on, when you’re just learning I suggest you stick with Git on the command line. Once you master command-line Git, you can transfer those concepts to any Git user interface easily, but you’ll always understand what’s going on under the hood.

Creating a GitHub repository

Now you have an idea of what Git is, let’s look at putting our Paraphrase project on GitHub. If you completed the previous tutorials you can use what you have there, but if you don’t you can get my original implementation from GitHub (ironic, huh?), by clicking here.

Warning: The example project has been written specifically for this tutorial series, and contains mistakes and problems that we’ll be examining over this tutorial series. If you’re looking for example code to learn from, this is the wrong place.

Now let’s take a look at the least you need to know to get this code safe on GitHub. We’ll look at more Git command soon, but this is the absolute minimum.

First, head to GitHub.com and make an account if you don’t already have one. The account creation form is usually right there on the GitHub homepage, but if it isn’t look for a Sign Up link.

Second, click the + button in the top-right of your GitHub window – this is where you create new repositories (projects) or gists (source code snippets). Please click New Repository to continue.

GitHub needs to know some basic details about your project to continue:

  1. What’s your repository name? This needs to be unique only among the other repositories you have, because GitHub refers to the repository as YourUsername/YourRepository. I’m going to use “Paraphrase-Improved”.
  2. A description of your project. This will be shown to other users when they visit your project on GitHub. I’ll leave this empty.
  3. Whether it’s public (for everyone to see) or private (just for you to see). If you’re using a free GitHub account then you can only choose public here. I’m going to choose Public.
  4. Should GitHub create a simple README file for you. This is a long text description of your project in Markdown format, and again will be shown to other users when they visit. The Paraphrase project already has one of these, so you should leave this unchecked.
  5. Whether you need a .gitignore file. These tell Git that some files in your project should not be stored in version control. Again, the Paraphrase project already has one of these, so you can ignore it.
  6. Whether you want GitHub to add a license for you. If you click the dropdown arrow next to None you’ll see the full range of open source licenses that GitHub supports – the ones in bold at the top are the recommended options. You can read more about those licenses here, but because we’re going to be importing an existing project I’d like you to skip this for now – leave it set to None.

Now click Create Repository to have GitHub create your new repository and take you there.

The URL for your new GitHub repository will be something like https://github.com/twostraws/Paraphrase-Improved – obviously your username will be different from mine, but you might also have chosen a different name than “Paraphrase-Improved”. If your repository is public you can send this link to anyone else, and they’ll be able to read your code, download it, and even create their own project on GitHub based on that code – a process known as forking.

However, right now the project is empty, so rather than see any code you will instead see GitHub’s quick setup guide – a simplified set of instructions to help you add your initial code to the repository.

Before we add our own code, we need to take one precautionary measure: it’s possible your version of Paraphrase already has some Git information attached, because I stored the original project on GitHub. So, before we start we’re going to run one command that definitely removes any of my Git history so you’re starting from a clean slate – just like you would in your own projects.

Fire up your Mac’s Terminal app now, then change into your workspace directory – that’s the one that contains files such as Paraphrase.xcodeproj. Now run this command: rm -rf .git

That instructs macOS to delete the .git directory, which contains all of Git’s information about our work. It won’t delete our code, just Git’s record of it – its history of changes over time.

Putting our code somewhere safe

With the other data gone, we’re now going to create a new Git repository to store your changes going forward. This is done by running git init in the current directory. Git will tell you that it has initialized an empty repository, which means it can start tracking changes as they happen.

To start with, we need to add all our source code to Git, so run this command: git add .

The dot at the end means “everything from this directory,” which means it will include all files and all subdirectories. This command won’t send any feedback, but you can see what has been added by running another command: git status

The output from git status will show you a lot of files in green, but at the top of its output you’ll see “Changes to be committed”. This is important: when you use git add to add files to a Git repository, all you’re doing is adding the files to a temporary area before they are actually saved. This means your code isn’t safely saved in source control just yet.

This temporary area – where changes are queued up in preparation for being executed – is known as staging, and is useful for preparing a batch of changes all at once. When you’re ready, which is when you’ve added all the changes you want, you commit those changes, which is where Git saves all the changes to disk.

It’s important to run git status before you commit changes, so you can see exactly what is going to be written to your version control system. If you read through the list of files, there are two things you might query:

  1. A lot of the files are from the Pods directory that we created back in part two. Do they need to be in our GitHub repository?
  2. All the screenshots we generated with Fastlane back in part four are missing – what gives?

The answer to the first question is “it depends” – some people like to add their CocoaPods to source control, but many don’t, as I learned recently…

MASTER SWIFT NOW
Buy Pro Swift Buy Swift Design Patterns Buy Practical iOS 11 Buy Swift Coding Challenges Buy Server-Side Swift (Vapor Edition) Buy Server-Side Swift (Kitura Edition) Buy Hacking with macOS Buy Advanced iOS Volume One Buy Hacking with watchOS Buy Hacking with tvOS Buy Hacking with Swift Buy Dive Into SpriteKit Buy Swift in Sixty Seconds Buy Objective-C for Swift Developers Buy Beyond Code

About the author

Paul Hudson is the creator of Hacking with Swift, the most comprehensive series of Swift books in the world. He's also the editor of Swift Developer News, the maintainer of the Swift Knowledge Base, and Mario Kart world champion. OK, so that last part isn't true. If you're curious you can learn more here.

Was this page useful? Let me know!

Click here to visit the Hacking with Swift store >>