heroku: Deploying with Git

Git is a powerful decentralized revision control system, and is the means for deploying apps to Heroku. You don’t need to be proficient with Git to use it for deploying code to Heroku, but you may find it valuable to learn the basics.

Tracking your app in git

Heroku apps expect the app directory structure at the root of the repository. If your app is inside a subdirectory in your repository, it won’t run when pushed to Heroku.

Before you can push an app to Heroku, you’ll need to initialize a local Git repository and commit your files to it. For example, if you have an app in a directory, myapp, then create a new repository for it:

 cd myapp

 git init
Initialized empty Git repository in .git/

 git add .

 git commit -m "my first commit"
Created initial commit 5df2d09: my first commit
 44 files changed, 8393 insertions(+), 0 deletions(-)
 create mode 100644 README
 create mode 100644 Procfile
 create mode 100644 app/controllers/source_file
...

This is a local repository, now residing inside the .git directory. Nothing has been sent anywhere yet; you’ll need to create a remote and do a push to deploy your code to Heroku.

Creating a Heroku remote

Git remotes are references to remote repositories. You can have any number of these, but for now we’ll focus on just the remote to Heroku. The heroku create command creates a new application on Heroku – along with a git remote that must be used to receive your application source.

 heroku create
Creating falling-wind-1624... done, stack is cedar-14
http://falling-wind-1624.herokuapp.com/ | https://git.heroku.com/falling-wind-1624.git
Git remote heroku added

By default, Heroku configures HTTP as the Git transport. The Heroku CLI will automatically place credentials in the .netrc file on heroku login. The Git client uses cURL when interacting with HTTP remotes, and cURL will use the credentials from the .netrc file. See the Authentication section and the CLI authentication article for details.
You can verify the remote in your git configuration as well:

 git remote -v
heroku  https://git.heroku.com/falling-wind-1624.git (fetch)
heroku  https://git.heroku.com/falling-wind-1624.git (push)

You can also take an existing Git repository and add a remote using the git URL provided when you created your app. You may need to do this to associate a Git repository with an existing application. The heroku git:remote command will add this remote for you based on your applications git url.

 heroku git:remote -a falling-wind-1624
Git remote heroku added.

The remote is named heroku in this example, but you can name the remote anything you want by passing -r other_remote_name. You may find it easier to follow the examples if you stick to using the heroku remote rather than using one with a different name.
There is one special remote name: origin, which is the default for pushes. Using origin as the remote name will allow you to type just git push instead of git push heroku, but we recommend using an explicitly named remote.

To switch from SSH Git to HTTP Git, run heroku git:remote in the directory holding your local Git repository. The CLI will override the heroku Git remote to use the HTTP protocol.

Deploying code

Your Heroku app starts with a blank repository – it has no branches and no code. So the first time you deploy, you’ll need to specify a remote branch to push to. You can do your first push:

 git push heroku master
Initializing repository, done.
updating 'refs/heads/master'
...

This will push your code to the heroku remote, created earlier. Use this whenever you want to deploy the latest code committed in Git to Heroku.
During the start of your first build, Initializing repository will be displayed while your app’s repository is created on Heroku. On subsequent builds, Fetching repository will be displayed while your app’s repository is fetched and prepared to accept your push.
Branches pushed to Heroku other than master will be ignored by this command. If you’re working out of another branch locally, you can either merge to master before pushing, or specify that you want to push your local branch to a remote master. To push a branch other than master, use this syntax:

 git push heroku yourbranch:master

Applications that rely on git submodules are supported, in addition to many other dependency resolution strategies.