Document Halt

[lishaduck]

EDIT: Halt should get documented so people can know how it exists.

Old description below:

---

Hello! I'm trying to convert some existing code that uses child_process to zx. It's working fine, but I want to print out the commands that are run. I know I can enable verbose mode and override the logger, but that isn't as flexible as the logging I need to do. I see zx 8 uses zurk under the hood, which has a buildCmd function. While that could work, it's not a template tag, so I'd need to manually verify it's actually what zx is running. I'd love an API to create commands without running them (as I think about it, it'd also be useful if xz exposed an exec function to run a command from the proposed builder tag).

• I'd be willing to PR this if this is a direction you're willing to consider.

[antongolub]

I'd love an API to create commands without running

You can do it right now:

const p = $({halt: true})`cdm --foo=${foo}`
console.log(f.cmd)
const o = await p.run()

You can inject verification layer in various ways:

1. Build a wrapper

const _$ = (pieces: TemplateStringsArray | Partial<Options>, ...args: any) => {
   if (isTemplateString(pieces, args)) {
      const p = $({halt: true}).apply(...)
      console.log(f.cmd)
      const o = await p.run()
    }
    return ...

}

2. Override ProcessPromise proto

const _run = ProcessPromise.prototype.run
ProcessPromise.prototype.run = function () {
  // ... custom check
  return _run.call(this)
}

3. Mix custom logger

const _log = $.log
const _$ = $({log: (entry) => {
  if (entry.kind === 'cmd') {
     // ... check
  }
  return _log(entry)
}})

[lishaduck]

const p = $({halt: true})`cdm --foo=${foo}`
console.log(f.cmd)
const o = await p.run()

Yeah, that looks like what I want! I'd seen halt in intellisense but it isn't documented, so I didn't know what it did.