01.07 Repositories

##Workflow

To make changes to the website use the following basic flow. The following operations must be performed separately in ~/suttacentral and in ~/suttacentral/data as appropriate.

• git pull to obtain latest data from SuttaCentral remote server.
• Make changes to local files in the ~/suttacentral and/or ~/suttacentral/data Working Directory.
• git add . to stage changes.
• git commit -m "Commit message" to commit changes.
• git push to send changes to SuttaCentral remote server.

The following should be in a separate terminal in ~/suttacentral.

• workon suttacentral invoke server to start local server and test changes.
• invoke deploy.production.quick to restart SuttaCentral remote server with changes.

Details below.

##The basics of git

from: http://rogerdudler.github.io/git-guide/

Your local repository consists of three "trees" maintained by git. The first one is your Working Directory which holds the actual files. The second one is the Index which acts as a staging area and finally the HEAD which points to the last commit you've made.

###Add & commit

You can stage (propose) changes (add it to the Index) using

git add <filename>

for specific files, or to add the entire directory and any sub-directories use:

git add .

This is the first step in the basic git workflow. To actually commit these changes use

git commit -m "Commit message"

Now the file is committed to the HEAD, but not in your remote repository yet.

###pushing changes

Your changes are now in the HEAD of your local working copy. To send those changes to your remote repository, execute

git push origin master

Change master to whatever branch you want to push your changes to.

##SuttaCentral repositories

Two repositories are used, the suttacentral repository and the suttacentral data repository, these instructions assume that the suttacentral folder is located at ~/suttacentral and the data repository must be located in the data subfolder of that folder.

First of all, know what branch you are working on. Normally this will be master, but it could be another branch, if it is another branch replace 'master' with the branch name. To change branches use

git checkout master

This must be done separately in the sc and data repositories (if needed). If it doesn't work , try doing git pull first.

Pulling and pushing

To get the latest code, templates, css, javascript, etc

cd ~/suttacentral
git pull

To push your changes:

git push

To get the latest data (tables, texts etc)

cd ~/suttacentral/data
git pull

To push your changes:

git push

You can do one liners like this:

cd ~/suttacentral && git pull && cd data && git pull && cd ..

Dealing with merge conflicts

If there are conflicts when you perform a pull, git will note that there are conflicts. Run git gui to see what is going on, if you install meld you will be able to get helpful three-way diffs. Using meld is a bit of an art, but basically you want the three columns to look the same (i.e. all three should have the correct content).

If there are conflicts when you perform a push, git will complain and refuse to proceed. You will need to run git pull and resolve the conflicts, then run git push again.

Starting a server on your local machine

It is a good idea to test changes before pushing them, as if there is bad scss or other code you will get exceptions or other errors rather than pages. To test the site, set up a local instance of the site as a server on your computer.

To run a local copy of the server, using your local code and data, you need to activate the suttacentral python environment (which is not required merely for using git) and be in the suttacentral folder, the command invoke server will then start a local server.

cd ~/suttacentral
workon suttacentral
invoke server

It can be accessed in your browser at http://localhost:8800

To deploy changes to staging (viewable at http://staging.suttacentral.net), run:

invoke deploy.staging.quick

To production (viewable at http://suttacentral.net):

invoke deploy.production.quick

Remember any changes which break production, break the website, so be careful before running invoke deploy.production.*, however merely pushing to git will never do any harm to the website, nor will deploying to staging. Production will continue to use old code, until invoke deploy.production is run.