Track any Text File in a Github Repository with the textfiles Build Spec Field


So you want to create a project that tracks a text file in a Github repository and allows you to create new projects with an always current version of the file? This is a simple, but useful technique that you will master in a few minute read. No programming background required.

Let’s get to it.

The doxx Key File

doxx keys are command central for project builds. These files provide doxx with build instructions and can be modified to create different types of projects. The key file documentation delves into the details for interested readers.

For the purposes of this tutorial, simply understand these things about doxx keys:

  • The build specification header section of the key file is all that you need for this type of project build
  • The build specification header section is developed with YAML syntax
  • Key files are named key.yaml by default
  • Builds take place relative to the directory that contains your key.yaml file. Place it in the root directory for your project.
  • Build specification fields provide the instructions to doxx about your build type. We’ll use the textfiles build spec field here. Other types are available.

textfiles Build Spec Field

Here is the syntax for a single text file pull using the textfiles build specification field in a key.yaml file:

---

textfiles:
    filepath: "URL"

---

filepath is changed to the local filepath (i.e. filename and any additional sub-directories within your build directory) for the file write. Use standard POSIX file path syntax on all platforms (including Windows systems). URL is changed to the actual URL where doxx can access the remote file.

Github Branch URL’s

Github provides a separate URL for access to the current version of every text file by repository branch.

The URL format is:

https://raw.githubusercontent.com/[user]/[project]/[branch]/[filepath]

Replace the user, project, branch, and filepath with the appropriate definitions for the Github repository that strikes your fancy. The main page for a Github repository (i.e. when you open your browser to https://github.com/[user]/[project]) generally displays the master branch. The branch is indicated in the URL as you click through files inside a repository and is displayed in the branch selector at the top of the repository file display.

Example: Phaser Game Framework, Latest Release

Your project needs to include the latest release of the Phaser Game Framework. It so happens that the merry band of Phaser developers stick the minified release of the JavaScript source in the build directory of the Github repository (master branch) that is available at this URL:

https://raw.githubusercontent.com/photonstorm/phaser/master/build/phaser.min.js

Create the Key File

Let’s make our key file with these settings:

---

textfiles:
    phaser.min.js: "https://raw.githubusercontent.com/photonstorm/phaser/master/build/phaser.min.js"

---

Save the file as key.yaml in the directory where you would like to build the file.

Build the Project

Open your terminal and navigate to the project directory where you saved your key.yaml file. Then pull your file with the command:

$ doxx build

That’s all there is to it. Distribute that key file to anyone who needs it and anyone can build the current release of the Phaser Framework off of it.

Clean Up

If you want to get rid of the key.yaml file after your build, execute the command:

$ doxx clean

and doxx cleans up after you.

Extend It

The textfiles build specification field can be used with any URL that points to text on a publicly accessible server. It supports http:// and https:// GET requests. Use it to track any text sources that you find useful.

The textfiles field also supports multiple text file pulls in the same build. Add additional file definitions, each on a separate line following the textfiles field, like this:

---

textfiles:
    file-one: "https://coolsite.com/greatfile.txt"
    file-two: "http://anothersite.com/betterfile.json"
    file-three: "https://greatstuff.com/thebestfile.xml"

---

And define the desired file paths if you want to place them in separate sub-directories inside the build directory:

---

textfiles:
    txt/file-one: "https://coolsite.com/greatfile.txt"
    json/file-two: "http://anothersite.com/betterfile.json"
    xml/file-three: "https://greatstuff.com/thebestfile.xml"

---

Learn More

You can combine this text file tracking feature with builds that include templated text files, complete directory archive pulls (including binary files such as images, pdf files, video/audio files, etc), and more. Dig deeper into key files and the build specification types in the key file docs.