Creating a repository
For a brand new project I prefer to create the project in GitHub and then clone it locally. For existing projects, there is the GitHub Importer tool which should do the trick.
GitHub projects have a “default” branch. The default default is master, but if you are going to use a development branch then GitHub’s UI will be more helpful if you make this the default – instructions here.
Once you’ve created the project, you can click on the “Code” button in GitHub to get the URL, then use this to run git clone https://github.com/myproject.git.
Making a .gitignore File
The .gitignore file tells Git what files you never want to commit to the repository. This is useful for keeping things you don’t want (like IDE settings, cache directories, and compilation output) out of your code base.
Just create a file called .gitignore in the root of your project, and add each path that you want to ignore on a separate line. If you’re using a JetBrains IDE, you’ll want to add the following line to exclude your IDE index files:
.idea/
Throwing Out Uncommitted Code
Sometimes you’ve stuff something up so badly that you just want to chuck it out and start again. If you haven’t committed anything yet this is super easy.
PHPStorm: Right click on the project directory and choose Git -> Rollback. You can also do this for individual directories or files by right-clicking on them.
Terminal: From the project root do git checkout . – or you can specify the path if you want to target a specific directory or file.
If you have committed something you didn’t mean to, there’s an excellent guide here for fixing the mess.
Committing and Pushing Code in PHPSTorm
There are actually 3 steps for getting code from your local file system into the remote repository in Git. This does sound like a lot of overhead, but if you have the right tools you can do it all with a couple of clicks of the mouse.
The first step is adding, where you tell Git that you would like the changes you made to a file to be included in the next commit. Then you commit, which adds the commit to your local repository. Finally you push, which sends your new commit (and any others that hadn’t been sent yet) to the remote.
Some devs prefer to make all their in-progress commits locally, and then push the whole feature to the remote once it’s done. Others prefer to always commit and push, so that their work is backed up somewhere if their hard drive crashes.
In PHPStorm adding is taken care of for you. Once you’re ready to go, right click on the project and choose Git -> Commit Directory. You’ll see a list of all the files you’ve changed, and can deselect any you don’t want to include. You won’t lose your changes to these files – they’ll still be there on your working copy so you can continue working on them, but they won’t be added or committed.
The Commit button on this widget has a secret which is hidden to impatient devs. If you click the little arrow on the right-hand side, it will give you the option to Commit and Push. This will push your commit for you, and create a new remote branch with the same name as your local branch if needed.
Committing in the Terminal
Your first step will be to list the files that you’ve changed. For this you need git status -s, which will list all files which have been changed since the last commit.
Files that haven’t been added will have a little red status text next to them. The ones that have been added will have green status text. Use git add {path} to add what you want, and git reset {path} to un-add anything you don’t want.
Once you’re done, git commit -m "Meaningful commit message" to commit all the added files.
Your last step is to push your branch. git push will work if your branch already has a remote tracking branch. If not, you want git push -u origin {branchname}.
Opening a Pull Request
Open your repository’s GitHub homepage in your browser. If you’ve pushed something recently you may see a yellow banner across the top of the page with a quick link for you to open a PR. If not, you can go to the Pull Requests page and then click the green New Pull Request button.
Your PR’s “base” branch should be the branch you want to merge into (e.g. development) and the “compare” branch should be the one you’ve built your feature in.
The description field can be useful for a variety of things – testing or upgrade instructions, a brief explanation of why you chose to implement things the way you did, mentioning any limitations or future work that may be required. This becomes part of your project’s documentation and is easily searchable through GitHub after the PR has been closed.
Reviewing and Merging a Pull Request
The Files Changed tab is the best place to go through the code line-by-line and see what’s changed. You will notice a little blue “+” button appears on the left-hand margin of the line that you’re hovering over – you can click on this to add a note on a specific line. Use the “Start a Review” option, which just limits the amount of notification spam the PR’s author receives.
Once you’ve done your line-by-line review (and checked out and tested the code if desired) you can leave any general comments on the Conversation tab, then submit your review.
Once any concerns you raise have been addressed, it’s time to merge the PR. Once you’ve merged it, delete the branch (GitHub will give you a button to do this) since it’s no longer useful.
Deleting remote branches
As mentioned above, the easiest way to delete remote branches is to nuke them through GitHub as soon as they’ve been merged. If you didn’t do this, another option is to go to the repository home page in GitHub, open the branch switcher and choose “View All Branches” at the bottom, and then click on the delete icon next to the offending branch.
If you’d rather do it through the terminal, you can:
git push origin --delete {branchname}
Release Tags
A tag is a snapshot of the code base at a particular moment in time. They are most commonly used to record releases, so that you have a quick reference to see what code was released when. Making a new release tag off the master branch is typically one of the last things you would do before you actually publish the code onto your production servers.
The easiest way to make a release tag is to click on the link on the right-hand sidebar of your repository’s GitHub home page.
To make a new branch from the terminal:
git tag -a {v1.1} -m "{tag title}"
git push origin {v.1.1}
Summary
This concludes my series on Git for SVN devs. This is not a comprehensive guide to everything that Git has to offer, but I hope it has been a useful introduction to get you up to speed and working with Git on a daily basis. Happy coding!