Tcl history Command

last modified October 20, 2026

The Tcl history command provides access to previously executed commands. It's essential for interactive Tcl sessions and debugging. The command allows recalling, re-executing, and managing command history.

Basic Definition

The history command maintains a list of previously executed commands. Each command is assigned an event number for reference. The history list has a configurable maximum size.

Syntax: history ?option? ?arg arg ...?. With no arguments, it returns the current history list, one event per line, each with its event number. The options are add, change, clear, event, info, keep, nextid and redo.

Viewing Command History

The simplest use shows the command history list with event numbers. The interactive tclsh records every command you type, but a script run from a file records nothing by itself, so the example adds the events with history add.

basic_history.tcl

history add {puts "Hello"}
history add {set x 10}
history add {expr {$x * 2}}
puts [history]

After three events have been recorded, history returns them with their event numbers. The command only returns the text; the script has to print it with puts (the interactive shell echoes results on its own).

Re-executing Commands

Commands can be re-executed using their event numbers with history redo.

history_redo.tcl

history add {puts "Hello Alice"}
history add {set count 1}
history redo 1

The history add command records two events. The history redo command then runs event 1 again using its event number. In a script the history list is empty at the start, so the numbers begin at 1. When history redo runs, it replaces the most recent event with the redone command, so it cannot be used to redo the most recent event itself.

Using Relative Event Numbers

Negative numbers reference commands relative to the current position.

history_relative.tcl

history add {puts "first"}
history add {puts "second"}
history add {puts "third"}
history redo -2

Here, -2 counts back from the most recent event (the third one), so it refers to the first command and prints "first". In the interactive shell the history command is itself the most recent event, so there -1 means the command typed before it. Relative numbers are useful for quick access to recent commands.

Searching History

The history command has no search subcommand, but history info returns the whole list, which can be filtered.

history_search.tcl

history add {set user Bob}
history add {puts hi}
history add {set count 42}

foreach line [split [history info] \n] {
    if {[string match *set* $line]} {
        puts $line
    }
}

This prints the events containing "set". Each line shows the event number and the command; event 2 does not contain "set" and is skipped. Useful for finding specific operations.

Clearing History

The history list can be emptied with the clear option.

history_clear.tcl

history add {puts "Test 1"}
history add {puts "Test 2"}
puts "Before clear:\n[history]"
history clear
puts "After clear: '[history]'"
puts "Next event number: [history nextid]"

After clearing, history returns an empty string and the event numbering starts again at 1, as history nextid shows. This is useful when starting a new sequence of commands.

Changing History Size

The maximum number of remembered commands can be adjusted.

history_size.tcl

puts "Default size: [history keep]"
history keep 50
puts "New history size: [history keep]"

Without an argument, history keep returns the current limit, which is 20 by default. Setting it to 50 limits the history to 50 commands; older commands are discarded as new ones are added.

Best Practices

Interactive Use: Most valuable in interactive sessions.
Event Numbers: Check numbers with plain history first.
Scripts: A script does not record its commands; use history add to record events yourself.
Redo: Remember that history redo replaces the current event, so it never redoes itself.
Customization: Adjust size based on your needs.

This tutorial covered the Tcl history command with practical examples showing its usage in different scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Tcl Tutorials.

Ebooks