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.
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
- Builds take place relative to the directory that contains your
key.yamlfile. 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
textfilesbuild 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
--- 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:
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
build directory of the Github repository (master branch) that is available at this URL:
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.
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.
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.
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" ---
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.