Development using Roots

I know that there are plans afoot to produce tutorials on how to use Roots and to highlight best practices. I am a massive fan of Roots and have used it in all our WP projects for the past 2 or more years. However I know that my current way of working is quite clunky and old fashioned.

Without wishing to jump the gun with the tutorials, I was wanting to highlight the system I currently use and ask if there could be tutorials or help in moving forwards.

When I start developing a WP website I create 3 installations at, and I start work on the site at Once the site is ready to go live I clone the dev site to and

Currently I use Dreamweaver (just the code editor) or Notepad++ on Windows and use FTP to upload/download changes.

I’ve read loads about how developing locally is the way and to use version control. I do see the advantages, but I’ll still need convincing- basically because I’ve got used to my way of working (isn’t the comfort zone great?!) However I do want to learn.

The problem for me is that most tutorials tend to be fairly advanced (I am not against using command line tools, but they it does scare me a little) and they are for development using a Mac. I’m a Windows user, so that tends to complicate matters.

From what I have read, I should be using Git (for version control) and Capistrano, WP Skeleton, WP Stack, Vagrant, Chef, Capistrano and Composer. Quite what any of those mean I don’t know!

So, is there any hope for me? I hope so and I am sure I am not the only one! I’ve managed to get my head round Roots despite it being (IMHO) for advanced users.

Thanks for listening! And thank so much for building Roots- it has transformed my web development life and we have some very happy customers at the end of it.


I’ll probably going more in depth later, but just to start with, forget about all the buzzwords you may have heard us mention. Yes, they will improve your development workflow but it won’t help you to get caught up in the hype of them all at once. One day you’ll want to start learning ONE at a time, but just ignore them for now.

There’s only 1 thing you NEED to start doing right now: use version control. I don’t mean this to sound derogatory, but to be considered a professional programmer you should be using version control. It’s a requirement at this point and there’s no excuse not to use it. Seriously, after you read this, go read some basic Git documentation (or another VCS if you want) and then go into ALL your projects and run:

git init .
git add .
git commit -am "Initial commit"

That’s it at a minimum. Then you should look into backing up that Git repository somewhere. Bitbucket offers unlimited free private repositories. If you do nothing else, at least do that.

edit: And keep committing all your changes into VCS once you’ve done that. Every single change with a nice description commit message. It’s not that much extra work and it will save you so much time (and your ass) over the course of development.


Next point: using Windows. There’s a reason most dev tutorials are targeted at a *nix based OS and that’s because they’re better for development (for anything non-Microsoft related). Most dev tools are built for *nix and although a lot can work on Windows, it just makes things more difficult.

That being said, it’s perfectly fine to code locally on Windows. However, most websites (especially WordPress based), end up being hosted on Linux servers. So if you’re developing on a local Windows stack like MAMP or whatever (local Apache and MySQL), and then deploy your code to a Linux server, you’re doing yourself no favours. You want all your environments to be identical if possible and you will run into problems the further you get away from that goal.

A popular dev workflow is to use Windows as your main OS but have a linux virtual machine where you do your actual coding. Just keep in mind that anyone who has ever used Mac OS or Ubuntu or whatever started with the exact knowledge and experience as you. Every one has learned it the same way and that’s simply by using it.

Thanks for your reply.

When you say *nix based OS (which I assume you mean Linux and Mac flavours) are “better for development”, what do you mean? Is it because they are going to be very similar to the environment on the server?

Currently I don’t develop locally. I know this will sound totally awful to you, but I make changes, FTP up and view on the dev or live site. In order for me to move over to local (and so be able to do version control) I’ll have to be able to set up all our sites locally and that is going to be a massive shift. Also, when I test my site locally, how do I then push everything to the dev or live site? It sounds like it would be a complete pain to push the database changes as well particularly when it comes to the paths to media files which tend to include the domain name as well. It also sounds like a lot of work if I’m only making minor changes.

I could use a Linux virtual machine, but then I wouldn’t be able to use my Windows software.

Looks like I have a lot of learning to do!


As a matter of fact, if you use Vagrant + puppet to set up your Virtualbox VM on Windows, you will get to use all of your Windows tools to work with code hosted on your virtual linux server. It works by utilising the shared folders features of Virtualbox, which allows you to access the files in the VM through the normal Windows filesystem.

That may sound mad, but it is certainly worth looking into.

I meant that mostly because way more tools are available, and specifically made, for Linux + Mac.

About version control, it sounds like you still write code locally, then FTP the file to a remote server. Correct?

You can still download the entire codebase to your local computer (if you don’t already have it) and create Git repositories for them. Then at least save the file locally, commit the changes to your repository, and then FTP the file up remotely. Then at least you’d still have a proper version control repository with commits for each change.

Or are you actually just editing a file straight off an FTP server and when you save it, it sends it back to the remote server? Because you should get away from that ASAP if that’s the case.

We’re going to be releasing a full WP stack setup including Vagrant for a Linux (Ubuntu) VM soon. And us Roots people have been using it for a while writing code locally. The folder/files are shared with the VM so it’s all seamless. Technically, it’s also developing locally as well but the entire dev setup is on the VM other than our local code editor. And it’s not mad at all. Actually a great way of doing things.

Sounds great. Seems like you guys are really taking roots to the top. Thanks for all of your efforts and thanks for sharing such a great tool :wink:

Hi guys,

I’m new to roots here. I’m trying to wrap my mind around as to where it shines and how to use it to maximize the benefits.

Is the base.php everything here? Do we have to use the theme wrapper concept? Is it the bread and butter here?

Though, I do get the reasoning behind the theme wrapper concept from a computer science point of view, but I’m finding it hard to justify it in use. I think it causes more confusions than it solves… Neither scribu’s nor Joel Kuzmarski’s posts help, well for me at least.

WP template hierarchy is already pretty good. With the get_header and get_template_part, we are almost there. Why seek perfection here… I don’t get it., Please help me clarify as to why it is needed to place this extra layer on top of WordPress template hierarchy?

And finally, is there a way to cancel it and make the roots work traditional way that is no theme wrapping… and if that’s possible, does that really defeat the purpose of using Roots for development at the first place and I may be better of working with another HTML5 BP + Bootstrap framework?

Thank you

1 Like

The wrapper concept totally does your head in at first. It took me weeks to work out what was happening, but now I really love it. It means much cleaner code and funnily enough is easier to work with. However I totally feel your pain.

The problem for me was that I hadn’t got to grips with the standard WordPress template hierarchy which made getting my head round how Roots worked harder.

I don’t know whether this will help you or anyone else, but here are some notes (quite a bit taken from the WP docs as well) that I made up whilst I tried to get my head round it all…

Standard WordPress set up

Normally WordPress has the following template files:

  • List item
  • style.css
  • header.php
  • index.php
  • sidebar.php
  • footer.php
  • single.php
  • page.php
  • comments.php
  • 404.php
  • functions.php
  • archive.php
  • searchform.php
  • search.php

WordPress uses the Query String (which it gets from the URL of the current page on the website) to work out what template file or template files to use to generate the page.

Firstly WordPress works out what type of page the current page is (i.e. is it a posts, archive, page, category or other page)

WordPress works out what template page or pages to use based on something called the Template Hierarchy.

WordPress firstly checks to see if it can find the most specific template file for its needs and if not it falls back to the default. For example it may check the category ID, slug, taxomony name or other criteria.

How WordPress checks depends on the type of page being requested. For example if the page being requested is a blog category page it will try the following:

  1. It checks to see if there is a category template file for the current category. For example if the current category has an ID of 4, it will check to see if category-4.php exists
  2. If not it will check to see if the generic category template file, category.php exists.
  3. If that doesn’t exist it will check to see if the archive template exists- archive.php
  4. If that doesn’t, WordPress will fall back and use the default index.php

Here are the queries depending on page type:

Front Page

  1. front-page.php (if doesn’t exist, falls back to…)
  2. index.php

Home (Blog) Page

  1. home.php (if doesn’t exist, falls back to…)
  2. index.php

Single Post

  1. single-{post_type}.php. If you are using custom post types you enter the slug of the custom post type- for example if the custom post type is “events”, this would be single-events.php (if doesn’t exist, falls back to…)
  2. single.php


  1. custom page type (The Page Template assigned to the Page. You can create your own page templates (page-templatename.php for example) and select these on the edit page section). At the top of the page template you should put the template name in comments: /* Template Name: Magazine */ (if doesn’t exist, falls back to…)
  2. page-(slug).php* (if doesn’t exist, falls back to…)*
  3. page-(id).php (if doesn’t exist, falls back to…)
  4. page.php* (if doesn’t exist, falls back to…)*
  5. index.php

Category (“Category” is an example of a “taxonomy”)

  1. category-(slug).php (if doesn’t exist, falls back to…)
  2. category-(id).php (if doesn’t exist, falls back to…)
  3. category.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php

Tag (“Tag” is an example of a “taxonomy”)

  1. tag-(slug).php (if doesn’t exist, falls back to…)
  2. tag-(id).php (if doesn’t exist, falls back to…)
  3. tag.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php

Custom Taxonomies

  1. taxonomy-(taxomony)-(term).php (if doesn’t exist, falls back to…)
  2. taxonomy-(taxomony).php (if doesn’t exist, falls back to…)
  3. taxonomy.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php


  1. archive-(post_type).php (if doesn’t exist, falls back to…)
  2. archive.php (if doesn’t exist, falls back to…)
  3. index.php


  1. author-(nicename).php (if doesn’t exist, falls back to…)
  2. author-(id).php (if doesn’t exist, falls back to…)
  3. author.php (if doesn’t exist, falls back to…)
  4. archive.php (if doesn’t exist, falls back to…)
  5. index.php


  1. search.php (if doesn’t exist, falls back to…)
  2. index.php (if doesn’t exist, falls back to…)

404 (Page Not Found)

  1. 404.php (if doesn’t exist, falls back to…)
  2. index.php (if doesn’t exist, falls back to…)

Here are the main template files that usually come with a theme excluding headers, sidebars and other sections of pages:

  • 404.php
  • author.php
  • base-front-page.php
  • base.php
  • category.php
  • front-page.php
  • index.php
  • page-custom.php
  • page-sample-page.php
  • page.php
  • single.php
  • search.php

As well as the above there are sections of pages that the above pages can use to put together the page:

  • header.php
  • footer.php
  • sidebar.php
  • searchform.php

Finally there are some special files that need to be included:

  • style.css (this gives WordPress the name and details of the theme. It can also be used for CSS styles)
  • functions.php (special functions for the theme to use)

As well as the above you can now put in special template files that the template hierarchy can use for specific pages. For example a template for a specific category “category-(slug).php”


WordPress usually puts all of the code and content into these template pages and fetches the header, sidebar and footer from the header.php, sidebar.php and footer.php files. Roots does away with all of that and uses base files to give the template structure. This means you can have different pages with different headers and footers. This changes the way the WP template hierarchy works slightly.

If the current page is the front page, WordPress would normally check for the front-page.php template. However, Roots runs some code that checks to see if there is a “base” file for that template. In this case it is looking for base-front-page.php. If that doesn’t exist it will look for base.php. The base file includes the header and footer and checks to see if the sidebar should be outputted, but actually you can get the base.php file to output whatever you like.

For example…

Front Page

  1. base-front-page.php (if doesn’t exist, falls back to…)
  2. base.php

Home (Blog) Page

  1. base-home.php (if doesn’t exist, falls back to…)
  2. base.php

Single Post

  1. base-single-{post_type}.php. If you are using custom post types you enter the slug of the custom post type- for example if the custom post type is “events”, this would be single-events.php (if doesn’t exist, falls back to…)
  2. base-single.php
  3. base.php

I hope that makes it clearer. It helped me…

(edited to fix formatting)


@iagdotme: thank you for taking the time to post your reply. I appreciate it. I read your reply line by line. Even though I knew about the WP template hierarchy, reading it once more was nice.

Let me get to the ROOTS part.

with roots… you can have different pages with different headers…

But this is also possible in a good old header.php which is brought in by a get_header() call embedded in index/single/archive/you-name-it.php, In the header.php, you could easily include a header-X.php or a header-Y.php depending on the whatever the situation is. By simply going thru a one-and-only header.php ( or footer.php for that matter), one can easily determine what’s happening…

for example, the following code, when placed in a (non-roots) functions.php, would give you the name of the template file;

add_filter( 'template_include', 'var_template_include', 1000 );
function var_template_include( $t ){
    $GLOBALS['current_theme_template'] = basename($t);
    return $t;

function get_current_template( $echo = false ) {
    if( !isset( $GLOBALS['current_theme_template'] ) )
        return false;
    if( $echo )
        echo $GLOBALS['current_theme_template'];
        return $GLOBALS['current_theme_template'];

Then, header.php would easily & clearly tap into that information thru something like this

switch ($GLOBALS['current_theme_template'] ){
	case  'home.php':
		include ('header-home.php');
		return;  //this call allows PHP to exit the include file right very here...
	case  'single.php':
		include ('header-single.php');
		return;  //this call allows PHP to exit the include file right very here...
	case  'archive.php':
		include ('header-archive.php');
		return;  //this call allows PHP to exit the include file right very here...
		//go on ( meaning stay in this header.php and output what will come after... ) 

//regular header goes here...

So, if it is the layout flexibility, doesn’t the above code achieve it in a more straight forward way that does not require the understanding of this? image

I am still not getting as to how the theme wrapper concept would simplify the work flow. But I haven’t quit yet. :slight_smile:

1 Like

Sorry, missed your comment. Thanks for this- makes sense!

I do develop locally. I make the changes in a code editor (either Notepad++ or Dreamweaver) and then FTP it up and take a look on the live or dev site. So I could use version control. Dreamweaver has one built in but I don’t like the look of it. I would love to use git because I really like the way GitHub from what I’ve seen.

I think I kind of understand…
However (forgive my ignorance) what do you mean by a “full WP stack setup”? Do you mean all the WordPress core code as well as the site? What is Vagrant?

I’m not against the idea of running Ubuntu in a virtual machine using Virtual Box, but I’d have to see the advantages. What code editor do you use on Linux?

Is the whole site (including database) stored locally? If so how do you then push it to the dev or live site? How do you make sure all the paths are correct? What happens if the main site uses SSL?

I’ve not got into using LESS yet, but I expect developing locally would help this. Presumably when you upload/push the new code to the dev/live site your less code is compiled into CSS?

Wow, this still sounds very mystical to me!

I assumed you knew a lot more about the WP theme hierarchy than me, but I thought other people might find it useful.

I suppose I haven’t actually answered WHY the Roots theme wrapper is a good thing, only a little more about how it works. The diagram you included did my head in when I saw it, but slowly I started to get my head round it particularly reading the various comments in the old Google group.

Why does Roots do this? I am hoping someone else more qualified than me can answer that…

  1. By “full WP stack setup” I mean a virtual machine that has nginx, php, php-fpm, mysql, and WP itself all setup. Using Vagrant, all you do is type “vagrant up” and you have a complete virtual machine with WP already installed and your theme loaded. Vagrant is basically just a tool for easy VirtualBox VM management specifically made for development environments.

  2. As I said before, with a setup like this you can use your local editor on Windows. The folder (WP site) you’re editing is kept in sync on the virtual machine all seamlessly.

  3. Everything is local. Usually you deploy by cloning your Git repo on your remote host and just pull down changes. Not sure why SSL on the live site would make any difference. You wouldn’t use SSL locally.

  4. Correct. Any pre-processor like LESS should ideally be run as part of the deploy process.

Thanks for clarifying what “full WP stack setup” means. I’ve just noticed you mention nginx. I’ve looked up and it seems that some people are using this as a replacement to Apache. There might be an advantage to using it, but I am stick with Apache for now since my Virtual Server uses that (under cPanel). Is that a problem?

So, I think I get that the Virtual Machine can access folders on my Windows computer and so Vagrant would be able to “do it’s stuff” on the files on the VM. Would I be running version control (git) on my Windows installation or on the VM?

I mentioned SSL because I was wondering how I could test locally if the dev and live sites had SSL (I use the Better WP Security) plugin. If the local and live sites were effectively clones of each other, wouldn’t the local site try and use SSL and fail? Also I use other plugins such as EWWW Image optimizer which uses PHP libraries to optimise images on the fly. These probably wouldn’t work locally.

Nothing is a problem :slight_smile: It’s all up to you. But obviously if you wanted to use our Vagrant setup for example, it would only support nginx by default.

You’d be running version control locally on your Windows host.

It gets a bit tricky with plugins for different environments. If you were using a virtual machine, there’s no reason you couldn’t have the EWWW Image optimizer working as well. SSL is a different story and you’d want it disabled in dev.

Scott, I have a related question about repositories. I have a lot of WordPress sites. I hate to keep all those copies of WordPress itself. So do you just Git the theme directories and custom plug-ins? All of wp-content? Or the entire site?


Thanks. Getting plugins to work both locally and remotely might be tricky. Is possible with your Vagrant set up to not overwrite certain plugins and their settings?

Would it be possible to use Apache with your set up? And if so, would it be possible to provide instructions for that as well? I am sure there will be many people still using Apache.


Ideally you have a Git repository per site including everything EXCEPT the WP core itself. Just tracking your theme and plugins isn’t really ideal because you might be missing things like wp-config.php and a proper folder structure. Currently the most popular way is probably The WP core is a separate Git submodule. This is a step up but not ideal either.

I’ll have a big blog post and screencast coming up about exactly this topic using Composer to manage WP core and keep it out of your repos. It’s a little advanced but after using it for a bit it’s much better than the alternative.