GitHub is a great platform for sharing ideas, collaborating with others, distributing useful code and documents, and many other things, but it can be a little intimidating for newcomers due to the complexity of Git protocol and commands. The concepts become simple and obvious once you’ve used them a few times, but what about that very first time you want to put one of your creations on GitHub – where to start?
This blog post provides a simple step by step answer to that question. We’ll go through how to publish a project in a GitHub repo, so that it’s ready to take advantage of all the capabilities GitHub has to offer. The steps here can be used for any project that you’ve started on your local hard drive – a programming project, a set of documents, anything from a single file to a massive hierarchical set of folders and files.
Here’s a diagram showing the steps covered in this blog post:
One assumption I’ve made below is that your local project isn’t already being managed with Git. As any Git expert will tell you, Git could (and should!) be used even for local projects that you’re working on by yourself, because of the ways it can help you manage versions, roll back changes, and so on. But this post is intended to help people who are new to both Git and GitHub, so I’ve assumed that your project is just some files on your hard drive, with no source control or repository involved yet.
I’ve used the command line for the steps below. You could do the same things with GUI-based Git client software, of course, but that insulates you from what’s actually going on, and I feel that using the command line makes the core concepts become clear more quickly. For similar reasons, I’m not using or mentioning any IDEs (interactive development environments) or other tools here.
If you use Windows, the quick and simple way to install Git and configure a command line for it is to simply install GitHub for Windows (G4W). After you’ve logged in to G4W at least once with your GitHub account, it auto-configures the provided Git Shell so that you don’t need to worry about the potential hassles involved in configuring two-factor authentication. This is very handy. The command line examples below are all done in the Git Shell.
The Project: scaffolding for Bootstrap/jQuery
I’ve used a simple project of my own here as an example. It’s an empty HTML5 project that provides the basic scaffolding for creating a project based on Bootstrap and jQuery. This is my customization of the Bootstrap basic template – as they say on that page, “we hope you’ll customize our templates and examples, adapting them to suit your needs,” and that’s exactly what I did. Here’s a screenshot of part of my customized template:
I included a few photos of my pets in the scaffolding, as placeholders for various image-related functionality, so we’ll include those image files as well in the GitHub repo we create:
That’s the project we’re using for this example, and now let’s go through each of the steps required to publish this project in a public GitHub repo …
Create a new (empty) GitHub repo
Once you’ve logged in to GitHub under your ID, you can go to https://github.com/<yourGitHubID> and you’ll see a tabbed interface with several options along the top of the screen. Click on Repositories, then click the New button:
Next you’ll be prompted for the repo name (GitHub repo names are most often hyphen-delimited, but you can name it anything you’d like) and a brief one-liner description. There is also an option here to initialize the repository with a README file, but I recommend you don’t do this. If you leave the repository completely empty, that keeps things a little simpler when you push your local files to it, as you won’t have “two versions” of the repo that need to be merged.
After the repo has been created, GitHub will provide a standard “quick setup” message that is displayed for any repo with no content:
By convention on GitHub, if a project has a file named readme.md in its root folder then that file (which is presumed to contain GitHub Flavored Markdown) is displayed as the repo’s home page. So after we create and upload a readme.md file, that will be displayed on our repo’s home page instead of the quick setup message shown above.
Note that you also have an option to specify a license for your project when you create the repo. It’s a good idea to do this up front, but that’s up to you (and perhaps your lawyers), so I won’t cover licensing here.
Create a local Git repo for the project
Next we need to make our existing local project into a Git repo. The details of Git workflow are beyond the scope of this post, but basically what we need to do is initialize a Git repo, add some files to it, and then commit those changes so that we’re ready to push them to GitHub.
We’ll do these steps at a Git command line – the Git Shell for Windows, in my case. Fire up your command prompt, move to the folder where your project resides, and then execute each of the following commands in that folder.
First we initialize the project with git init:
This creates a hidden .git subfolder, where Git will store all of the information about the repo’s status and change history. The .git folder is hidden, but you can see it if you view hidden files:
Next, we will add files to the repo with the git add command. In my case, I created a simple readme.md file to document the project and added that (git add readme.md), then I added various other files with git add <filename> commands.
You can also remove files with git rm, or set up a .gitignore file if that’s a better approach for your specific repo. And note that you can use git status to view what’s been staged for committing at any time.
After all of the necessary files have been added, we commit the changes with the git commit command, including an optional comment of “first commit” to identify these changes for future reference:
Push local changes to the master GitHub repo
Now we’re ready to push our changes to GitHub, thereby synchronizing our local project and the remote GitHub repo in the cloud. There are two final commands involved, a git remote and a git push, as shown here:
That’s it, we’re done! The files are now hosted on GitHub, and we can invite others to work with this repo via a Git command line and/or client software such as GitHub for Windows. People can clone the project, download a ZIP of it, or fork the project and/or do pull requests. And you can accept contributions from others if you’d like, using all of the tools that GitHub provides.
Here’s a screenshot of my new repo at https://github.com/dmahugh/scaffolding-bootstrap-jquery:
If you’re ready to start using GitHub to share your work and collaborate with others, I hope this post will help you get started! As some final food for thought and additional learning, here’s a diagram showing how various common git commands interact with the various stages in the git workflow: