Freeway Pro, Git and Bitbucket
Softpress, the developer of Freeway Pro announced they are closing their doors, Freeway Pro has reached end-of-life. This tutorial will continue to work with the latest (last) version of Freeway Pro 7.x.x but it’s all moot at this point.
Because a Freeway site is edited from a single proprietary document and not individual HTML/CSS files the (Git) tracking process is a bit backwards compared to typical text-files. Using Freeway with Git is akin to the round hole/square peg scenario, that it works at all is surprising. Consider this tutorial a proof-of-concept, nothing more.
Freeway users regularly (and rightly so) lament the lack of multiple undos, a situation which despite of years of complaints is unlikely to change anytime soon. I started experimenting with Freeway and Git as a possible (albeit geeky and heavy-handed) alternative to a problem that has Freeway users divided. I tend to think of version control as Big Boy multiple undos for Freeway, though I suspect most Freeway users would never venture into version control so really I did this to satisfy my own curiosity, but maybe someone else will find it of value.
At first glance this may seem like an awful lot of work to setup but it’s really not. The confusing part might be generating the SSH keys and installing the deploy script, neither of which is difficult. But those things only need to be done once. Set it and forget it. The next time you create a repo it should take less than 5 minutes.
- A free Bitbucket account.
* GitHub will also work and should be fairly similar to setup, but this tutorial is specific to Bitbucket.
- Terminal (command line).
- Optional Git client. I use Coda (or Tower) but there are other options from SourceTree, Gitbox, GitX, SmartGit etc.
- SSH access to your server. You’ll need to know the SSH settings.
Where to Put Your Local Repo
First you need to decide where you want to install your local repo. If you’re tracking a FW site then the decision has already been made for you: the repo should be created in the same folder as your Freeway (.freeway) document, not in the Site Folder.
You need to set Freeway’s publish location to the folder that contains the actual Freeway file. Also, if the folder already contains files then you need to first move everything out, we want to start with a completely empty folder. You’ll move the files back once the repo is installed.
Here’s where things get finicky. Because we’re editing the Freeway document (.freeway) and not the html/css/js files it generates, this is the file we need to track. This is counter-intuitive to how Git would typically be used.
Then why do it this way? Because Freeway can’t read the files it creates. If we tracked Freeway’s generated files then rolled back to say, a previous version of index.html, there’s no way to update the .freeway document with the previous version of index.html. Freeway simply does not work that way. This means every page we create going forward should be added to the .gitignore list (see below) to ensure we avoid this headache.
HTTPS / SSH
Depending on what you prefer there are 2 options for communicating with Bitbucket: HTTPS and SSH. I use SSH in this example but HTTPS may be easier if you’re just testing the waters, though I haven’t used it. Read more about each option.
If you go with SSH you’ll want to generate keys for your local machine as well as your remote server and each of these keys will need to be saved in your Bitbucket account under Manage Account > SSH keys.
Creating Your First Repository
- Create a Bitbucket account and sign-in.
- On your Dashboard page on the right sidebar click the “Create a repository” link.
- Fill in the required “Name” field and in the “Language” picker choose an option (in this case “HTML/CSS”).
- Click the blue “Create repository” button.
- You will be presented with 2 options for creating your repo. Choose “Start from scratch” and open the Terminal to create a local session.
- Follow the instructions for setting up your local repo and be sure to click the blue “Next” button after you complete each of the sections.
If all went well you should now have a functioning Git repo (.git) on your local computer in whatever folder you specified. It won’t be visible by default so enable viewing invisible files. If you see the .git folder go ahead and move any files back into the parent folder (i.e., the folder where your site files will live), not the .git folder. If everything is working properly then you should be able to “add” and “commit” any changes you make to your Freeway file upon publish and “push” those changes to your Bitbucket repo.
Chances are you don’t want to track every file so we can now tell Git what folders/files to ignore. Remember what I said above about ignoring Freeway’s generated site files?
- Manually create a file named .gitignore and place it your local site root.
- Add any folders/files you want to ignore. Here’s a very basic example:
*.html// All html files will be ignored.
*.css// All CSS files will be ignored.
myFolder// The folder named “myFolder” will be ignored. You can also use a trailing slash,
.DS_Store// This is a common file you’ll want to ignore.
Depending on how broad or narrow you need to be there are a number of ways to write the .gitignore file to target what you want. It’s worth looking into the various syntax options.
Cloning Your Bitbucket Repo On the Remote Server
Local changes are not yet being posted to your server because we haven’t setup a clone of the Bitbucket repo on the remote server.
- In your Bitbucket account, in the upper “Repositories” drop-down menu select the repo you created.
- On the repo page at the top of the right sidebar you’ll see a small picker with options “SSH” and “HTTPS”. Select “SSH” and copy the text in the text field next to the picker.
- Open a new Terminal session but this time you need to access the remote server via SSH.
- Once you connect to your server via SSH (you should be in the site root, e.g.,
public_html) type the following command and paste the repo text you just copied. You should end up with something that looks like the following, except with your account details:
git clone [email protected]:MyUsername/my_repo_name.git
- Hit Return in the Terminal and it will duplicate your Bitbucket repo in the public directory of your server.
- Whatever you named your Bitbucket repo when you first created it, e.g., “myRepo”, there should now be a folder on your server named “myRepo”. Inside that folder will be the (invisible) .git folder. This folder contains all the important stuff.
- Move the .git folder out of “myRepo” and place it in the site root. The “myRepo” folder should now be empty and you can delete it.
- You now have an exact clone of the repo that’s in your Bitbucket account on your local machine. At this point you can manually “pull” your changes from Bitbucket to your server but who wants to do that? So let’s automate this last part.
- Follow the instructions for installing this auto-deploy script.
Changes to the Bitbucket API in 2015 have broken many 3rd Party auto-deploy scripts. However, this script should work with the new API.
- Name the file whatever you like and put it in the site root (remote).
- Go back to your repo account page and click on the blue “cog” icon and select “Hooks” from the left menu.
- From the “Select a hook…” picker choose “POST” then click “Add Hook”.
- In the text field enter the full url to the script file, e.g., http://mysite.com/auto-deploy.php.
- If all is groovy then each time you push your local changes to Bitbucket it will automagically send those changes to your server with no further effort on your part. Easy, ain’t it? Now you have an ongoing record of every change you make to your files with the ability to rollback to any previous version.
As mentioned above, it’s important to understand that unlike a “normal” Git workflow where you rollback to a specific text file you will be reverting the Freeway (.freeway) file. As a result one of the quirks is that after reverting you may need to close/open the Freeway document to ensure Freeway uses the the rolled-back version of the .freeway file. Fortunately this is a quick, simple and painless process.