Setting Up the Project

In this step, we'll perform the last housekeeping tasks before we start actual development.

Initializing Submodules

The “Starterkit” project provides us with two things:
a) A boilerplate structure for our new project.
b) Kirby’s core code parts.

The latter could be seen as “libraries”; and, as clean coders, we know that library type of code should not be modified by us (because, if you did, you would have a hard time updating to new versions of the library).

Here’s where Git’s “Submodule” concept comes in handy: it allows you to import library code as a sub-repository into your main project. This allows you to keep your code cleanly separated.

The “Starterkit” includes two Submodules in its “kirby” and “panel” folders. Let’s initialize them properly:

Using Git with Tower Command Line

In Tower, expand the “Submodules” area in the sidebar. Then, select a submodule item - and you’ll instantly see that we have to perform an “Update” to initialize it.

After having initialized these two submodules, double-click the “kirby” submodule to open it in Tower: as it contains another submodule itself (the “toolkit” library), you’ll have to initialize this one, too.

Initializing submodules instructs Git to clone the necessary files for these libraries into your project structure. Now, it’s finally time for a little test drive.

On the command line, make sure you are in the root folder of the Starterkit project. There, enter the following command:

$ git submodule update --init --recursive

This instructs Git to clone the necessary files for these libraries into your project structure. Now, it’s finally time for a little test drive.

Testing Our Kirby Installation

Since it includes a boilerplate structure, the “Starterkit” automatically provides us with a fully functional demo site. Start up a server in your MAMP or XAMPP app to take this for a spin. Alternatively, if you have PHP 5.4 (or newer) installed, you can open your Command Line and simply type the following in the root folder of your project:

php -S localhost:8888

Open your browser on localhost:8888 to have a look at the demo site.

Cleaning Up

Now that we know that the system is running, let's remove all dummy content from the sample project:

  • All subfolders in the "assets” directory should be empty.
  • The content folder should contain only the "home", "error", and "site.txt" items.
  • In "site", make sure the "snippets" and "templates" folders are empty.

Be sure to commit our cleaned up project structure:

Using Git with Tower Command Line

In Tower, make sure the project is open and “Working Copy” is the active item in the sidebar. Then simply hit the “Stage All” button, enter a commit message like “Clean up dummy content”, and confirm by clicking “Commit”.

On the command line, execute the following commands:

$ git add .
$ git commit -m “Clean up dummy content”

Keeping it Clean

After cleaning up the project, we should make sure that it stays clean - by ignoring unnecessary files from version control. Thankfully, the boilerplate project already comes with a simple text file named .gitignore in the root of the project. Open this in your favorite editor and replace its contents with the following lines:

# General
.DS_Store

# Sass
.sass-cache/

# Kirby
/site/accounts
/assets/avatars
/thumbs/*
/site/cache/*

You will only need the .DS_Store rule if you're on a Mac (like I am). You'll also notice that we included a rule specific to Sass. This is because we'll be using Sass for our HTML/CSS template.

Each of these rules fulfills a simple task: it prevents files from being included in version control that should not be.

Just like before, we stage and commit this change to the local repository.

Connecting Our Own Remote Repo

With our first two commits made, Git informs you that we’re “2 commits ahead”:

This means we have two commits locally that haven’t been published to the remote repository, yet.

With our current setup, however, we cannot publish (or, in Git lingo: “push”) these changes: at the moment, the only remote repository that is connected is the “Starterkit” repository from which we initially cloned. And we don’t have write access to this remote repository.

Therefore, if we want to collaborate with others on the project, we’ll need to connect a remote repository of our own. For this example, I have created a blank repository on GitHub.com and will now connect it with our local repository:

Using Git with Tower Command Line

First, let’s rename the existing remote connection: in Tower’s sidebar, right-click the “origin” item and choose the “Rename” option to name it “upstream”.

Now we’ll connect our blank remote repository: right-click the “REMOTES” section header and select “Add Remote Repository”.

Note that the URL that I used here will again not be writable for you. If you want to follow along, you’ll need to enter a URL to a blank remote repo of your own.

We can then publish our local repository on this new remote - simply by dragging the local “master” branch onto our new “origin” item:

First, let’s rename the existing remote connection from “origin” to “upstream”:

$ git remote rename origin upstream

Now we’ll connect our blank remote repository:

$ git remote add origin https://github.com/gittower/blog-tutorial.git

Note that the URL that I used here will again not be writable for you. If you want to follow along, you’ll need to enter a URL to a blank remote repo of your own.

We can then publish our local “master” branch on this new remote repository:

$ git push -u origin master
Note

For the sake of brevity and clarity, I won’t list all code changes in every situation. However, I will often reference the corresponding commit on GitHub when explaining a certain step. You can then inspect these step's changes in detail.

Now that we have our project set up, let's import our HTML template.

Giveaways. Cheat Sheets. eBooks. Discounts.
And great content from our blog!

About Us

As the makers of Tower, the best Git client for Mac and Windows, we help over 100,000 users in companies like Apple, Google, Amazon, Twitter, and Ebay get the most out of Git.

Just like with Tower, our mission with this platform is to help people become better professionals.

That's why we provide our guides, videos, and cheat sheets (about version control with Git and lots of other topics) for free.