The Command Log¶
As you use VisiData, it generates a temporary log of every modifying command you’ve run. This “command log” can assist you with a few things:
- Seeing what you’ve done during a VisiData session
- Saving that history (so that you can use it later or share it with others)
- Replaying those commands
This chapter walks you through each of these steps.
Viewing the command log¶
From anywhere within VisiData, you can press D to view the command log relevant to your current sheet. It ignores actions you may have taken outside of the current sheet’s direct lineage. Essentially, it answers the question: What steps did I take to get here?
Let’s start with a simple example, following these steps:
- Initiate a fresh VisiData session with
vd faa-wildlife-strikes.csv - Rename the sheet to
strikes: Press Space to raise the type-a-command prompt, typerename-sheet, press Enter, and typestrikes, and then press Enter again - Navigate to the
AIRPORTcolumn - Press F to generate a frequency sheet of the
AIRPORTcolumns - Navigate to the sixth row, and press s to select it
You should see something like this:
File Edit View Column Row Data Plot System Help | VisiData 3.0.2 | Alt+H for help men AIRPORT ║↓count♯│ percent%│ histogram ~║ UNKNOWN ║ 8424 │ 11.47 │ ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ ║ DENVER INTL AIRPORT║ 2756 │ 3.75 │ ■■■■■■■■■■■■ ║ DALLAS/FORT WORTH …║ 2392 │ 3.26 │ ■■■■■■■■■■ ║ CHICAGO O'HARE INT…║ 1583 │ 2.16 │ ■■■■■■■ ║ JOHN F KENNEDY INTL║ 1302 │ 1.77 │ ■■■■■ ║ •MEMPHIS INTL ║ 1217 │ 1.66 │ ■■■■■ ║ SALT LAKE CITY INTL║ 1179 │ 1.61 │ ■■■■■ ║ PHILADELPHIA INTL ║ 1131 │ 1.54 │ ■■■■■ ║ ORLANDO INTL ║ 1026 │ 1.40 │ ■■■■ ║ SACRAMENTO INTL ║ 1021 │ 1.39 │ ■■■■ ║ LA GUARDIA ARPT ║ 974 │ 1.33 │ ■■■■ ║ CHARLOTTE/DOUGLAS …║ 960 │ 1.31 │ ■■■■ ║ NEWARK LIBERTY INT…║ 917 │ 1.25 │ ■■■■ ║ LOUISVILLE INTL AR…║ 841 │ 1.15 │ ■■■ ║ AUSTIN-BERGSTROM I…║ 817 │ 1.11 │ ■■■ ║ LOUIE ARMSTRONG NE…║ 809 │ 1.10 │ ■■■ ║ KANSAS CITY INTL ║ 807 │ 1.10 │ ■■■ ║ HARTSFIELD - JACKS…║ 775 │ 1.06 │ ■■■ ║ GEORGE BUSH INTERC…║ 746 │ 1.02 │ ■■■ ┌─────────────────────────────| statuses |─┐ DETROIT METRO WAYN…║ 734 │ 1.00 │ ■■■ │ selected 1217 rows │ BALTIMORE/WASH INT…║ 691 │ 0.94 │ ■■■ └──────────────────────────────────────────┘ 2› strikes_AIRPORT_freq| s select-row 1512 bins •1
Now press D to open the command log for this sheet:
File Edit View Column Row Data Plot System Help | VisiData 3.0.2 | Alt+H for help men sheet │ col │ row │ longname │ input │ keystrokes │ … ⌀│ ⌀│ ⌀│ open-file │ faa-wildlife-strik…│ o │ ⌀ faa-wildlife-strik…│ │ │ rename-sheet │ strikes │ ⌀│ R strikes │ AIRPORT │ │ freq-col │ │ Shift+F │ o strikes_AIRPORT_fr…│ │ キMEMPHIS INTL │ select-row │ │ s │ s Shift+D› strikes_AIRPORT_freq_cmdlog| Shift+D 4 logged commands
Two things you’ll see that you might not have expected:
- The command to open
faa-wildlife-strikes.csvappears in the log, with “longname”open-file. Passing filenames to VisiData on the command line is equivalent to opening them within the program viaopen-fileor keyboard shortcut o. - Navigational commands do not appear in the command log. The reason: Navigating around a sheet doesn’t alter its contents. For the frequency sheet (
freq-col) and row-selection (select-row) commands, VisiData has captured the necessary context via the log’scolandrowcolumns.
Saving the command log¶
The command log behaves virtually the same as any other sheet in VisiData. That means you can sort, filter, and otherwise edit its rows, columns, and cells. That also means you can save just like you’d save any other sheet, with Control-s. Doing so with the example above should raise a prompt that looks like this:
File Edit View Column Row Data Plot System Help | VisiData 3.0.2 | Alt+H for help men sheet │ col │ row │ longname │ input │ keystrokes │ … ⌀│ ⌀│ ⌀│ open-file │ faa-wildlife-strik…│ o │ ⌀ faa-wildlife-strik…│ │ │ rename-sheet │ strikes │ ⌀│ R strikes │ AIRPORT │ │ freq-col │ │ Shift+F │ o strikes_AIRPORT_fr…│ │ キMEMPHIS INTL │ select-row │ │ s │ s save to: strikes_AIRPORT_freq_cmdlog.vdj Ctrl+S save-sheet 4 logged commands
As you’ll see, VisiData suggests its own .vd file extension. That helps distinguish command logs from other files, but it’s not necessary. It’s just a tab-separated-values file, and you can save it with the .tsv extension if you prefer. For the sake of the subsequent steps in this tutorial, let’s save it as example-cmdlog.vd, in the same directory as faa-wildlife-strikes.csv.
Replaying the full command log¶
To fully replay the example-cmdlog.vd log we saved in the section above, run the following command from your computer’s terminal:
vd --play example-cmdlog.vd
Note that, this time, we don’t point VisiData to the dataset itself, since that information (the path to the dataset) is now specified within the command log. If the replay worked, you should see VisiData advance through each step (some more quickly than others), ultimately arriving at the result you previously obtained manually:
File Edit View Column Row Data Plot System Help | VisiData 3.0.2 | Alt+H for help men AIRPORT ║↓count♯│ percent%│ histogram ~║ UNKNOWN ║ 8424 │ 11.47 │ ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ ║ DENVER INTL AIRPORT║ 2756 │ 3.75 │ ■■■■■■■■■■■■ ║ DALLAS/FORT WORTH …║ 2392 │ 3.26 │ ■■■■■■■■■■ ║ CHICAGO O'HARE INT…║ 1583 │ 2.16 │ ■■■■■■■ ║ JOHN F KENNEDY INTL║ 1302 │ 1.77 │ ■■■■■ ║ •MEMPHIS INTL ║ 1217 │ 1.66 │ ■■■■■ ║ SALT LAKE CITY INTL║ 1179 │ 1.61 │ ■■■■■ ║ PHILADELPHIA INTL ║ 1131 │ 1.54 │ ■■■■■ ║ ORLANDO INTL ║ 1026 │ 1.40 │ ■■■■ ║ SACRAMENTO INTL ║ 1021 │ 1.39 │ ■■■■ ║ LA GUARDIA ARPT ║ 974 │ 1.33 │ ■■■■ ┌───────────────────────────────| statuses |─┐ CHARLOTTE/DOUGLAS …║ 960 │ 1.31 │ ■■■■ │ saul.pw/VisiData v3.0.2 │ NEWARK LIBERTY INT…║ 917 │ 1.25 │ ■■■■ │ opening example-cmdlog.vdj as vdj │ LOUISVILLE INTL AR…║ 841 │ 1.15 │ ■■■ │ Was I the same when I got up this morning? │ AUSTIN-BERGSTROM I…║ 817 │ 1.11 │ ■■■ │ opening faa-wildlife-strikes.csv as csv │ LOUIE ARMSTRONG NE…║ 809 │ 1.10 │ ■■■ │ Rename current sheet │ KANSAS CITY INTL ║ 807 │ 1.10 │ ■■■ │ open Frequency Table grouped on current │ HARTSFIELD - JACKS…║ 775 │ 1.06 │ ■■■ │ column, with aggregations of other columns │ GEORGE BUSH INTERC…║ 746 │ 1.02 │ ■■■ │ select current row │ DETROIT METRO WAYN…║ 734 │ 1.00 │ ■■■ │ selected 1217 rows │ BALTIMORE/WASH INT…║ 691 │ 0.94 │ ■■■ └────────────────────────────────────────────┘ 3› strikes_AIRPORT_freq| select-row 1512 bins •1
You can adjust the replay behavior via various command line arguments, such as:
vd --play example-cmdlog.vd --replay-wait 2
… which will pause two seconds between each of the logged steps. And:
vd --play example-cmdlog.vd --batch --output cmdlog-results.csv
… which will replay the command log in “batch” mode (displaying status messages but not the full VisiData interface) and, when complete, will save the final sheet to cmdlog-results.csv.
Sharing command logs on GitHub¶
Command logs can help you demonstrate specific VisiData behavior to others, especially if that behavior involves more than a few steps. You’ll want to do this, for instance, when filing potential bug reports via VisiData’s GitHub repository. Some advice for doing so:
- When attaching a command log to a GitHub issue or comment, you’ll need to change the file extension, since GitHub will reject fileames ending in
.vd. The developers recommend appending.txtto the filename; in the example above, that would beexample-cmdlog.vd.txt. - If replaying the command log requires a specific dataset, attach that dataset in the same message and aim to make it as simple as possible. Alternatively, you can use a dataset from VisiData’s sample_data directory (for instance, as done in this issue).