Start using Git

Turning any project in to a Version controlled project is really simple and should be one of the first steps in any project workflow. By the time you realise that you need a version controlled file, it’s usually too late – whether you have accidentally overwritten a days worth of work on a file, or you deleted the wrong thing. Since it’s so easy to setup, there’s really no excuse not to. There are a few best practices and tips as well as a few gotchas to note along the way but don’t worry, I’ll be pointing them out.

We could use a GUI for setting up and managing our Git repos, but to make sure that you understand what’s going on behind the scenes we’re going to be using the command line for setting up the git repo this time.

We’re going to assume that you have an existing project that you want to turn into a Git repo. If you don’t then just create an empty folder and we’ll use that!

1. Installing Git
2. Initialising the repo
3. Ignoring certain files
4. Adding project files
5. Setting up the project with a web-based git hosting service
6. Pushing the project files to a git hosting service
7. How to clone my new Git repo
8. What to do next
9. Branching and merging (new post)
10. Conflicts and reverting (new post)

Installing Git

Depending on your OS you may or may not have Git installed. If you do then you can skip this step. If you don’t then head over to the Git – Installing page.

Now that Git is installed you need to make sure it knows who you are:

1git config --global user.name 'Your Name' git config --global user.email you@somedomain.com 

Initialising the repo

Using your CLI (command line interface – Terminal, iTerm, Command Prompt) navigate to your project folder. To initialise the folder as a git repo type the following:

1git init 

Your folder is now a git repository. Well done! This doesn’t mean any files are tracked or pushed to a server, but it’s the first step in getting that sorted.

Ignoring certain files

While adding and versioning files is the core feature of git, it’s vital to make sure that some files are never included, and that others are best not included. We specify this to Git by creating a .gitignore file. The key reasons that files that should’t be committed include:

1. Config files ( e.g. wp-config.php, local-settings.py ) which include any secret setup information such as database passwords or internal emails, password salts etc should NEVER EVER be included as this is a potential security risk. EVER!
2. Package managed files (Bower, NPM etc) are all controlled by a package manager. The package file should be version controlled but not the files. These packages often contain many Mb and hundreds of files that are not needed and might cause potential issues down the line.
3. Compiled files such as css produced by Sass or Less don’t need to be version controlled. Compiled files are often minified and on one line. This is often a cause of git conflicts (we’ll cover these later) as it doesn’t know what to do.

Add a .gitignore

To add a .gitignore file is easy. make a new file in your project folder named .gitignore and add a list of files or folders you want to ignore, 1 per line with * as a wildcard. You can do this in most text editors or via the command line if you prefer the CLI. Below is an example of part of one of my .ignore files.

1*.DS_Store wp-config.php *.log* node_modules/ static/css/* 

So this would ignore and .DS_Store files which are pointless, the config file, any log files, node modules (used for compiling sass) and any of the compiled CSS files in the static folder. It’s worth noting that if you commit a file then decide to add it to the ignore list it will still be tracked, until you delete it (move it to your desktop), commit and re-add it and commit again.

To see a list of files and folders that will be added to your repo just type git status in the command line. If you spot anything that should be ignored then add it to the .gitignore and do another git status and it should be gone from the list. Repeat until confident you’re going to be adding the right files.

Adding project files

Now that we know what not to add to the repo, it’s time to add your remaining files. This is just one simple command.

1git add . 

The . means everything in the current folder, so if you want to add files in a new folder specifically you can do:

1git add my-sub-folder/sub-sub-folder/all-the-levels-deep 

If you follow up with a git status it should give you a list of files to be added. Now it’s just a case of committing the files:

1git commit -am ‘Adding all the project files' 

The -m lets you add the message inline without it opening up a command line text editor, which I personally find quicker and easier. The ‘Adding all the project files’ is the message you want to add to your commit. This should be written so it makes sense to anyone who reads it further down the line. ‘Adding files’ is a useless message. ‘Updated the blog editor styles and updated the blog templates with a new button’ is much better. Shorter and snappy is the key here.

-a adds all currently changed files to staging so they are ready for the commit. It’s a shortcut and it only updates changed files that are already tracked by Git. New files still need to go down the git add [files] route. I always use -am and haven’t had a reason, or been told otherwise to do something different… Yet!

Setting up the project with a web-based git hosting service

Now the files are all ready to go, they just need somewhere to be hosted. There are many good web hosts for Git, including Bitbucket and GitHub of which I use both, but for this example we’ll use Bitbucket.

Signup and login to Bitbucket and from the main menu bar select the Create > New repository option. Give it a sensible and relevant name. Make sure Private is ticked (should be by default) and that Git is selected for the type. The rest are all optional, but the defaults are fine. Create the repository.

Pushing the project files to a git hosting service

You should be presented with a setup page. Under the command line section select the ‘I have an existing project’ and follow the instructions. These should be…

1. Navigate to your project folder
2. Add the web host origin with git remote add origin <bitbucket address for the repo>
3. Push the repo to bitbucket with: git push -u origin –all
4. (optional) Push any tags, which we won’t have yetgit push -u origin –tags

Once it finishes pushing your files, you should refresh the bitbucket page for your repined it should be updated. To check your files arrived find the repo navigation and select ‘source’ (on the left of the page) and they should all be there.

How to clone my new Git repo

Now that your repo is setup you can clone it to other machines, or somewhere else on your current machine and work from there. You can also edit files using Bitbucket’s editor, although this really should be a last resort and for tiny, single file changes.

To clone the repo to somewhere else you need to get the repo url. That should be back on your repo’s homepage (top right) and should end in a .git extension. e.g. git@github.com:carl-topham-tools/Chrome-Extension-Starting-Bundle.git

By default git will clone a new repo into a folder with the same name as the repo. My demo-repo will be in a folder called demo repo. There are a few other options as follows:

Default – Clone into a sub folder named after your repo:

1git clone [your git web address] 

Clone into a different named sub folder:

1git clone [your git web address] 

sub-folder-name Clone into the current folder:

1git clone [your git web address] . 

The last one is hand if you have already setup a project folder and wanted to put the repo in it. It won’t let you clone into a folder with anything in though.

More

Git is easy to get along with if you follow a few simple rules of thumb. Things can still go wrong, but they do so, it’s less often and when it does, it’ll usually less of a problem to fix!

• NEVER work directly on the master branch (this should be the latest working version of your project).
• Commit files often and when it makes sense. Don’t leave it until there are multiple random things that need committing as if one breaks the site, then you might have to revert all of them.
• Branch for each feature and fix and always branch off master (except in very few circumstances).
• Make sure commit messages are simple to understand. If it’s something you need to explain then do a Git commit (without the -m) and a text editor should load where you can explain yourself on multiple lines (similar to markdown).
• Always merge master into your branch and fix conflicts before merging your branch into master. This means conflicts won’t break master.
• Ignore secret files (configs), package managed files and compiled files for security, bloat and reduced conflicts.