The Basics of Using Git with Pagoda Box

Last Updated October 2014

Using Git as part of your workflow on Pagoda Box can be somewhat daunting if you've never used Git before or feel out of your element working from a command line. This doc is meant to walk you through the basics of the Git + Pagoda Box workflow. After reading it, you will be able to:

  • Confidently update and manage your application on Pagoda Box using Git

Setting Up Git

Git is an extremely fast and efficient code version control system that allows you to easily collaborate on and manage your application codebase. There is somewhat of a learning curve, but once you get the hang of it, it'll be hard to go back to how you worked before. If you haven't set up git, you'll need to do that. Our Setting up Git doc will walk you through the process.

Getting Your Code to Pagoda Box

Whenever you launch an app on Pagoda Box, you're given a few terminal commands that will get your code from your local desktop onto Pagoda Box.

Before you run any of these commands, you'll want to navigate to the root of your codebase in your Command Line Client. This is done using the cd filepath command.

Initializing an Empty Git Repo Terminal

  $ git init

This command initializes an empty git repository using the directory you're currently in. Now add the contents of that directory (your codebase) to your empty git repo using the following command:

Adding Code to Your Repo Terminal

  $ git add .

Once your code is added to your repo, you must "commit" the addition of files. Committing is basically staging code to be pushed. If code is not committed, it will not be pushed. It's a good idea to include a commit message with each commit explaining what changes have been made. Commit messages in your git history allow you to quickly identify specific commits.

Committing Your Code Terminal

  $ git commit -m "example message"

Once code is committed and ready to push to Pagoda Box, add a "pagoda" remote. A remote is a "clone" of your repo stored on a remote machine. The name of the remote does not have to be "pagoda," but all other references in our documentation refer to your pagoda remote.

Adding a Pagoda Remote Terminal

  $ git remote add pagoda git@git.pagodabox.io:apps/your-app.git

In the git remote add command, you specify the remote name (pagoda) and the git clone url of your new remote (git@git.pagodabox.io:apps/your-app.git). Your app's clone URL is found in your dashboard, just under the deploy controls. After adding your pagoda remote, use the following command to push your app to Pagoda Box

Pushing Your Code to Pagoda Box Terminal

  $ git push pagoda master

The git push command pushes all of your committed code. Specifying the pagoda remote will push your code to Pagoda box. Listing master will push your master branch to Pagoda Box.

Only the Master Branch will be Accepted & Deployed

When pushing to Pagoda Box, only the master branch is accepted and deployed. You can push a local branch other than master to your master branch on Pagoda Box using a simple git command.

Repo Size Limitations

Repos have a hard size limit of 3.5GB. Code services are not created until code is pushed to Pagoda Box. New code services are always created on cloud instances, which have 4GB of disk. Pagoda Box requires a 512MB disk buffer to allow room for binaries, possible logs, etc. If you have more the 3.5GB of code in your repo, that along with the required disk buffer will exceed the disk space available and your app's build will fail.

Getting Your Code from Pagoda Box

If you're setting up a new machine or have been added as a collaborator to app, you'll likely need to clone your app's code to your local machine. Git makes this incredibly simple with its clone command.

Get Your App's Git Clone URL

The first thing you'll need is your app's Git Clone URL. This can be found in your app dashboard under Admin > App Info.

You can also get your app's clone url in the output of the Pagoda CLI's info command.

Clone Your App's Code from Pagoda Box Terminal

  # Pattern
  $ git clone [git clone url]

  # Example
  $ git clone git@git.pagodabox.io:apps/demo-app.git

Change the Name of Your Origin Remote (Optional)

When using Git's clone command, Git assumes the clone url you're pulling from is the "origin" remote. This doc, as well as all other Pagoda Box documentation, assumes your app's repo resides at the "pagoda" remote. While it isn't necessary, we suggest changing the name of your origin remote to "pagoda".

Changing the Name of Your Origin Remote (Optional) Terminal

  # Pattern
  $ git remote rename [current remote name] [new remote name]

  # Example
  $ git remote rename origin pagoda

The Basic Git + Pagoda Box Workflow

The life of an app usually consists of repeating the simple process of making code changes locally and pushing them live. This is where Git makes life really easy. When ever you make any changes in your repository and you want to add those changes, simply run this command:

Adding Code Changes to Your Repo Terminal

  $ git add .

Then commit your changes with a message describing what changes were made:

Committing Your Changes Terminal

  $ git commit -m "your commit message"

If part of the changes to your repo was deleting files, you will need to include the -a parameter in your commit command to actually remove those files from your repo on Pagoda Box. If the -a parameter isn't included, the files you deleted will only be removed from your local repo and not from your Pagoda Box repo.

Committing the Deletion of Files Terminal

  $ git commit -am "your commit message"

Once you've committed your code, go ahead and push it to your pagoda remote:

Pushing Changes to Pagoda Box Terminal

  $ git push pagoda

If the branch you're working on is anything other than master, you can still deploy this branch, you just have to push it to the master branch of your pagoda remote:

Pushing Branches to Pagoda Box Terminal

  # Pattern
  $ git push pagoda [local_branch]:[remote_branch]
   
  # Example
  $ git push pagoda staging:master

Once you push your code to Pagoda Box, it will automatically be deployed.

Further Reading

The commands and steps that we've discussed are just the basics of Git and should fit most of your workflow scenarios. However, Git can allow you to do many more things. If you want to learn more about git, Scott Chacon has written great book that walks you through Git step by step. It's free and is called Pro Git.

If you have any questions, suggestions, or corrections, let us know.