Using this simple Nushell command to make sense of my many Nushell scripts

I use Nushell in companion with generative artificiel intelligence a lot to automate simple journalistic workflows.

I’ve already defined some basic custom commands in Nushell. These custom commands do different things.

I then use the custom commands in sequence inside small scripts to make complete workflows from the separate things each custom command does.

Sometimes just looking at a particular script, it can be difficult for me to remember what each command in the script does, and what it does in the context of the script.

To ensure that I can easily recall this information a while after I write the script, or to ensure that others can understand the script, I try to annotate each line in the script with a comment.

Here is an example:

open somefile.yaml | each {|row| $row.ai-content | opret fn --print-path $row.ai-title }    # opret markdown filer
cd /home/lk/Noter/folkets.dk/Notitser/    # skift til bibliotek
ls -f | get name | each { udgiv fn $in }    # udgiv markdown filerne
cd -    # tilbage til Scripts

Each line consists of the command in the script and then, after the ‘#’-sign, my explanation of what the line does.

If the above lines are in a file called temp.nu. I can simply write the following in my terminal:

forklar temp.nu

forklar is Danish for ’explain’.

Running the above command will give me the following clear presentation of what is going on line by line in the script:

╭───┬─────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────╮
│ # │         comment         │                                             code                                             │
├───┼─────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
│ 0 │  opret markdown filer   │ open somefile.yaml | each {|row| $row.ai-content | opret fn --print-path $row.ai-title }     │
│ 1 │  skift til bibliotek    │ cd /home/lk/Noter/folkets.dk/Notitser/                                                       │
│ 2 │  udgiv markdown filerne │ ls -f | get name | each { udgiv fn $in }                                                     │
│ 3 │  tilbage til Scripts    │ cd -                                                                                         │
╰───┴─────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────╯

The reason I can do this is because I have created a custom command in Nushell called forklar like so:

def forklar [path: string] {
 cat $path | from csv -s '#' -c '#' -n | rename code comment | move comment --before code
}

As the numbers of scripts I develop increase, this helps me remember exactly what the scripts do and how they do it.

Nushell already has an even better way of doing this for custom commands built right in to its help system.