[Feature Request] Task export history option

[notklea]

I propose that taskwarrior expose some command to export history (and thus also possibly import it)

I'm not exactly sure how it'd work, i was thinking maybe reuse the already existing export/import commands, but hide this feature behind an option, which would allow showing history or not (maybe also make that same option allow adding to history when with false it wouldn't, but i'm not sure)

[djmitche]

This has been discussed although I'm not immediately finding the discussion.

Note that the CLI doesn't use "options" in the normal sense -- task export --with-history would be really unusual. But something like task export-history would be OK.

I suspect the right way to do this, keeping true to the underlying data structures, would be to export each task as a sequence of operations that ends in that task. We already have that data (we use it to generate the history in task info), so exporting it shouldn't be too hard.

I'm not sure this is a good-first-issue, but shouldn't be too hard for someone to get started with.

[notklea]

This has been discussed although I'm not immediately finding the discussion.

oh

Note that the CLI doesn't use "options" in the normal sense -- task export --with-history would be really unusual. But something like task export-history would be OK.

I meant a config option that defaults to 0/disabled/off/false.

I suspect the right way to do this, keeping true to the underlying data structures, would be to export each task as a sequence of operations that ends in that task. We already have that data (we use it to generate the history in task info), so exporting it shouldn't be too hard.

Yeah that's more or less what i was thinking of

[smemsh]

We touched on this in #3835.

Rather than have two export formats, we could add a special task field in the export that is an array of all previous task versions, or a dictionary keyed by either the change time or a monotonic version number.

Or, probably it's better (definitely smaller) if the special field contained the sequence of changes that resulted in the task, as suggested.

By using a field of the task to export the changes, 'import' could read it if it was there (and I guess "replay" it to constitute the imported task), or use a blank history if it wasn't, and then we wouldn't need another command (for either import or export, although its presence in export could be controlled by an rc option). It should probably check that the replayed task materializes to be the same as the exported task, though.

This extraneous field would I think be treated as an unconfigured UDA by other tools that didn't know or care about it.

[djmitche]

As long as that's controlled by an option, I think that's OK. We would want to check that older versions' task import is OK with this additional field (that is not of type string).

[notklea]

By using a field of the task to export the changes, 'import' could read it if it was there (and I guess "replay" it to constitute the imported task), or use a blank history if it wasn't, and then we wouldn't need another command (for either import or export, although its presence in export could be controlled by an rc option). It should probably check that the replayed task materializes to be the same as the exported task, though.

I wonder, would that allow adding custom history changes after a task was made?

[djmitche]

That raises an interesting point: it's critical to the data model that the set of operations on a task since its creation result in the current state of the task. So if we had a JSON import with both a "current state" and a "set of operations" we would need to pick one or the other as authoritative, and basically ignore the other one.

Maybe a different approach is a pair of task import-operations and task export-operations which consume/produce only a sequence of operations for each task, and whatever that sequence produces is the task content. Then you could export, edit, and re-import.

More details at https://gothenburgbitfactory.org/taskchampion/sync-model.html

[notklea]

That raises an interesting point: it's critical to the data model that the set of operations on a task since its creation result in the current state of the task. So if we had a JSON import with both a "current state" and a "set of operations" we would need to pick one or the other as authoritative, and basically ignore the other one.

We could add another config option to set which to pick as authoritative.

Maybe a different approach is a pair of task import-operations and task export-operations which consume/produce only a sequence of operations for each task, and whatever that sequence produces is the task content. Then you could export, edit, and re-import.

More details at https://gothenburgbitfactory.org/taskchampion/sync-model.html

Seems interesting, however, i'd like to be able to import and export operations for more than one task with the same command, but yes, your idea would allow easily extending taskwarrior's syncronization methods without having them implemented in TW

[smemsh]

Either way could be sound. My preference is for in-band history, and then yes check that the replayed history ends up with all the same fields and contents as the task describes. They should be the same. I would just reject the whole record as invalid if it wasn't the same, and be OK with the history being missing (the stub history would just be one commit of the whole thing). If supplied, it needs to match.

Two separate import modes, one with history and one with all the task fields, leaves the history as kind of a separate database. Although I suppose, in a sense, it is, because different histories could nonetheless result in the same task.

[djmitche]

Seems interesting, however, i'd like to be able to import and export operations for more than one task with the same command

The suggested command wouldn't preclude that!

I would see a command that imports operations only as strictly more useful than a command that imports tasks+operations. The latter is equivalent to the former with the addition of a "checksum" (the task contents). That checksum might be difficult to calculate correctly for external tools, meaning that the mode would be most useful just for exporting from one taskwarrior and into another.

A simple operation-import mode would be a convenient way to modify tasks from external tools without going through the usual task CLI or interfacing with TaskChampion. For example, it would be relatively easy for a shell script to export all tasks, filter them using jq and grep, and then synthesize a few Update operations to add tags to the filtered tasks. I wouldn't want to build an application that way, but for one-off scripts it seems pretty appealing.

It would also be more difficult to implement the "checksum" variant -- the best way I can imagine is to apply all the operations, call get_task, and if it does not match, call undo to undo the applied operations.

[smemsh]

I would see a command that imports operations only as strictly more useful than a command that imports tasks+operations. The latter is equivalent to the former with the addition of a "checksum" (the task contents). That checksum might be difficult to calculate correctly for external tools, meaning that the mode would be most useful just for exporting from one taskwarrior and into another

I was thinking of it more like a "polymorphic import" where the history field was optional and if supplied then replaying it would be authoritative. you could just as well discard the top level task information if the history was supplied, as trying to make it match. Then if only task data is supplied (without history), it just retains current behavior.

So in the proposed "operation-import" system (I might suggest new single words like "dump" and "load" or something), with separate commands from the existing ones, the use of them would abandon/bypass completely the existing task import/export functionality right? And conversely all such "complete" tasks will be imported as a reconstruction of timestamped event replays? and "task export" will become just like an alias to export the end of the replay sequence? Or would it continue to have the property of having (1) a task and (2) a history that were maintained separately? I can see some histories as having a lot of changes which might end up being expensive to insert all those especially if they're like individual synchronous operations.

A simple operation-import mode would be a convenient way to modify tasks from external tools without going through the usual task CLI or interfacing with TaskChampion

Hmm so like import a list of uuid+operation primitives. almost like a "task assembler". Yes, I can see that being useful in the shell...

[djmitche]

We do not maintain (a) a task and (2) a history separately -- they are just two perspectives on the same data. There are many task histories that could lead to the same task state, but only one task state that can result from a task history. It's impossible to store a task different from that which results from the history. Think of it like a bank account: there are transactions and a current balance, but the bank will not show a current balance that is not equal to the sum of all transactions.

The current import/export pair "lose" history because import synthesizes a minimal set of operations to create the task as it appears in the input JSON data: a Create followed by an Update for each field, timestamped with the import time. In the bank analogy, "export" records the balance, and "import" performs a single lump-sum transaction.

My proposal is two new commands, which for the sake of argument we can call operation-export and operation-import. These would handle data of the form

[
{"Update":{"uuid":"49f5f020-e552-46b8-9bdd-c880452bdd46","property":"status","value":"completed","timestamp":"2025-11-08T16:17:24.465237917Z"}},
{"Update":{"uuid":"4cada0d4-da45-4435-ada0-b76f1d9151a9","property":"status","value":"completed","timestamp":"2025-11-08T17:04:50.723868905Z"}}
]

where, on import, those operations would be added directly to the task database. The bank analogy is exporting and importing a transaction history, with the balance adjusted correctly on import.

I am not sure what to make of the abandon/bypass question -- these new functions would not synthesize operations, but otherwise would be pretty similar to the existing import/export commands.

[smemsh]

yeah, I'm just asking if there won't be any use for the "old" import/export anymore because these new operations-based transaction logs would supersede them for import and export purposes. because the original import/export commands don't contain change history.

however the original exports would still be useful for tools that don't care about the history. I guess that's actually most tools, which just want field values, not their history.

I guess "task export" and then "task import" on a different system will not ever work then, only the new operations based commands will preserve everything.

in that case I'd vote for a flag to import/export (maybe auto-detect on import) to use the operations log format instead. but separate command also works.