oliverdavies.uk/content/node.cdfbc891-17fa-45e3-9ea6-b0b1bc6defd2.yml

uuid:
  - value: cdfbc891-17fa-45e3-9ea6-b0b1bc6defd2
langcode:
  - value: en
type:
  - target_id: daily_email
    target_type: node_type
    target_uuid: 8bde1f2f-eef9-4f2d-ae9c-96921f8193d7
revision_timestamp:
  - value: '2025-05-11T09:00:57+00:00'
revision_uid:
  - target_type: user
    target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
revision_log: {  }
status:
  - value: true
uid:
  - target_type: user
    target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
title:
  - value: 'Using a "run" file to simplify project tasks'
created:
  - value: '2022-08-15T00:00:00+00:00'
changed:
  - value: '2025-05-11T09:00:57+00:00'
promote:
  - value: false
sticky:
  - value: false
default_langcode:
  - value: true
revision_translation_affected:
  - value: true
path:
  - alias: /daily/2022/08/15/using-run-file-simplify-project-tasks
    langcode: en
body:
  - value: |
      <p>Every project has its own set of commands that need to be run regularly.</p>

      <p>From starting a local server or the project's containers with Docker or Docker Compose, running tests or clearing a cache, or generating the CSS and JavaScript assets, these commands can get quite complicated and time-consuming and error-prone to type over and over again.</p>

      <p>One common way to simplify these commands is using a <code>Makefile</code>.</p>

      <p>A Makefile contains a number of named targets that you can reference, and each has one or more commands that it executes.</p>

      <p>For example:</p>

      <pre><code class="language-language-yaml"># Start the project.
      start:
          docker-compose up -d

      # Stop the project.
      stop:
          docker-compose down

      # Run a Drush command.
      drush:
          docker-compose exec php-fpm drush $(ARGS)
      </code></pre>

      <p>With this Makefile, I can run <code>make start</code> to start the project, and <code>make stop</code> to stop it.</p>

      <p>Makefiles work well, but I don't use the full functionality that they offer, such as dependencies for targets, and passing arguments to a command - like arguments for a Drush, Symfony Console, or Artisan command, doesn't work as I originally expected.</p>

      <p>In the example, to pass arguments to the <code>drush</code> command, I'd have to type <code>ARGS="cache:rebuild" make drush</code> for them to get added and the command to work as expected.</p>

      <p>An agency that I worked for created and open-sourced their own Makefile-like tool, written in PHP and built on Symfony Console. I gave a talk on it called <a href="/presentations/working-with-workspace">Working with Workspace</a> and used it on some of my own personal and client projects.</p>

      <h2 id="what-i%27m-using-now">What I'm using now</h2>

      <p>The solution that I'm using now is a <code>run</code> file, which is something that I learned from Nick Janetakis' blog and YouTube channel.</p>

      <p>It's a simple Bash file where you define your commands (or tasks) as functions, and then execute them by typing <code>./run test</code> or <code>./run composer require something</code>.</p>

      <p>Here's the Makefile example, but as a <code>run</code> script:</p>

      <pre><code class="bash">#!/usr/bin/env bash

      function help() {
        # Display some default help text.
        # See examples on GitHub of how to list the available tasks.
      }

      function start {
        # Start the project.
        docker-compose up -d
      }

      function stop {
        # Stop the project.
        docker-compose down
      }

      function drush {
        # Run a Drush command with any additional arguments.
        # e.g. "./run drush cache:rebuild"
        docker-compose exec php-fpm drush "${@}"
      }

      # Execute the command, or run "help".
      eval "${@:-help}"
      </code></pre>

      <p>As it's Bash, I can just use <code>$1</code>, <code>$2</code> etc to get specific arguments, or <code>$@</code> to get them all, so <code>./run drush cache:rebuild</code> works as expected and any additional arguments are included.</p>

      <p>You can group tasks by having functions like <code>test:unit</code> and <code>test:commit</code>, and tasks can run other tasks. I use this for running groups of commands within a CI pipeline, and to extract helper functions for tasks like running <code>docker-compose exec</code> within the PHP container that other commands like <code>drush</code>, <code>console</code> or <code>composer</code> could re-use.</p>

      <p>As well as running ad-hoc commands during development, I also use the run file to create functions that run Git pre-commit or pre-push hooks, deploy code with Ansible, or build, push or pull the project's latest Docker images.</p>

      <p>I also use one within my Talks repository to generate PDF files using rst2pdf, present them using phdpc, and generate thumbnail images.</p>

      <p>For examples of <code>run</code> files that I use in my open-source code, <a href="https://github.com/search?l=Shell&amp;q=user%3Aopdavies+filename%3Arun&amp;type=Code">you can look in my public GitHub repositories</a>, and for more information, here is <a href="https://nickjanetakis.com/blog/replacing-make-with-a-shell-script-for-running-your-projects-tasks">Nick's blog post where I first found the idea</a>.</p>

              
    format: full_html
    processed: |
      <p>Every project has its own set of commands that need to be run regularly.</p>

      <p>From starting a local server or the project's containers with Docker or Docker Compose, running tests or clearing a cache, or generating the CSS and JavaScript assets, these commands can get quite complicated and time-consuming and error-prone to type over and over again.</p>

      <p>One common way to simplify these commands is using a <code>Makefile</code>.</p>

      <p>A Makefile contains a number of named targets that you can reference, and each has one or more commands that it executes.</p>

      <p>For example:</p>

      <pre><code class="language-language-yaml"># Start the project.
      start:
          docker-compose up -d

      # Stop the project.
      stop:
          docker-compose down

      # Run a Drush command.
      drush:
          docker-compose exec php-fpm drush $(ARGS)
      </code></pre>

      <p>With this Makefile, I can run <code>make start</code> to start the project, and <code>make stop</code> to stop it.</p>

      <p>Makefiles work well, but I don't use the full functionality that they offer, such as dependencies for targets, and passing arguments to a command - like arguments for a Drush, Symfony Console, or Artisan command, doesn't work as I originally expected.</p>

      <p>In the example, to pass arguments to the <code>drush</code> command, I'd have to type <code>ARGS="cache:rebuild" make drush</code> for them to get added and the command to work as expected.</p>

      <p>An agency that I worked for created and open-sourced their own Makefile-like tool, written in PHP and built on Symfony Console. I gave a talk on it called <a href="/presentations/working-with-workspace">Working with Workspace</a> and used it on some of my own personal and client projects.</p>

      <h2 id="what-i%27m-using-now">What I'm using now</h2>

      <p>The solution that I'm using now is a <code>run</code> file, which is something that I learned from Nick Janetakis' blog and YouTube channel.</p>

      <p>It's a simple Bash file where you define your commands (or tasks) as functions, and then execute them by typing <code>./run test</code> or <code>./run composer require something</code>.</p>

      <p>Here's the Makefile example, but as a <code>run</code> script:</p>

      <pre><code class="bash">#!/usr/bin/env bash

      function help() {
        # Display some default help text.
        # See examples on GitHub of how to list the available tasks.
      }

      function start {
        # Start the project.
        docker-compose up -d
      }

      function stop {
        # Stop the project.
        docker-compose down
      }

      function drush {
        # Run a Drush command with any additional arguments.
        # e.g. "./run drush cache:rebuild"
        docker-compose exec php-fpm drush "${@}"
      }

      # Execute the command, or run "help".
      eval "${@:-help}"
      </code></pre>

      <p>As it's Bash, I can just use <code>$1</code>, <code>$2</code> etc to get specific arguments, or <code>$@</code> to get them all, so <code>./run drush cache:rebuild</code> works as expected and any additional arguments are included.</p>

      <p>You can group tasks by having functions like <code>test:unit</code> and <code>test:commit</code>, and tasks can run other tasks. I use this for running groups of commands within a CI pipeline, and to extract helper functions for tasks like running <code>docker-compose exec</code> within the PHP container that other commands like <code>drush</code>, <code>console</code> or <code>composer</code> could re-use.</p>

      <p>As well as running ad-hoc commands during development, I also use the run file to create functions that run Git pre-commit or pre-push hooks, deploy code with Ansible, or build, push or pull the project's latest Docker images.</p>

      <p>I also use one within my Talks repository to generate PDF files using rst2pdf, present them using phdpc, and generate thumbnail images.</p>

      <p>For examples of <code>run</code> files that I use in my open-source code, <a href="https://github.com/search?l=Shell&amp;q=user%3Aopdavies+filename%3Arun&amp;type=Code">you can look in my public GitHub repositories</a>, and for more information, here is <a href="https://nickjanetakis.com/blog/replacing-make-with-a-shell-script-for-running-your-projects-tasks">Nick's blog post where I first found the idea</a>.</p>

              
    summary: null
field_daily_email_cta: {  }