borg2: use 3 timestamps for archives

[tve]

When I pass --timestamp /some/directory I was expecting that borg would record the mtime of that dir as timestamp for the archive. But I don't see anything like that when running borg info. Also, borg info doesn't really list a timestamp but "Time (start)" and "Time (end)".

• clarify which timestamp is "relevant", e.g. when matching
• ensure mtime is used (or of not, documented)
• consider switching to start-time + duration instead of end time 'cause right now if --timestamp is used the start time = end time and duration is lost (as far as I can tell)

[ThomasWaldmann]

Giving a file (or directory) for the timestamp works for me (and it uses its mtime).

(borg-env) tw@MacBook-Pro borg % borg create --timestamp pyproject.toml arch docs

(borg-env) tw@MacBook-Pro borg % borg repo-list                                  
b5956440  Thu, 2026-02-19 22:21:25 +0100  arch                         tw          MacBook-Pro  

(borg-env) tw@MacBook-Pro borg % ls -l pyproject.toml 
-rw-r--r--  1 tw  staff  9295 Feb 19 22:21 pyproject.toml

(borg-env) tw@MacBook-Pro borg % borg info aid:b5956440
Archive name: arch
...
Time (start): Thu, 2026-02-19 22:21:25 +0100
Time (end): Thu, 2026-02-19 22:21:25 +0100
Duration: 0.042 seconds
...

That was borg2, current master branch.

[tve]

Re: duration. Here's what I see:

== running: borg create --show-rc --stats -v -x --files-cache ctime,size --numeric-ids --noflags --noacl
s --noxattrs -Cauto,zstd  --timestamp 2026-02-22T18:01:01+01:00 daily-full * 
Connected (version 2.0, client OpenSSH_10.0p2)                                                          
Authentication (publickey) successful!                                                                  
[chan 0] Opened sftp connection (server version 3)                                                      
Creating archive at "sftp://xxx@xxx/mnt/big/@borg200b20"                             
Repository: sftp://xxx@xxx/mnt/big/@borg200b20                                       
Archive name: daily-full                                                                                
Archive fingerprint: 00000000000000000000                   
Time (start): Sun, 2026-02-22 17:01:01 +0000                                                            
Time (end):   Sun, 2026-02-22 18:45:13 +0000                                                            
Duration: 1 hours 44 minutes 12.458 seconds                                                             
Number of files: 2200565                                                                                

The "Time (start)" corresponds to the --timestamp value given, but the "Time (end)" really is meaningless. There is nothing in this backup that happened at that time. IMHO an archive should have three timestamps:

• archive timestamp: this is the nominal time of the backup and is either the start time or set by --timestamp
• start timestamp: this is the local time when the borg run started
• end timestamp: this is the local time when the borg run ended (could store duration instead)

Conflating the archive timestamp with the time when borg started is fraught with issues.

The --timestamp option indeed works as intended, my mistake, sorry.

[ThomasWaldmann]

Currently, that is how it is expected to be (there are only 2 timestamps, start and end).

Usually they are the start and end of the borg operation, except when you use --timestamp to override the start with some value S. The end is then just computed as S + duration.

But I agree, having 3 timestamps as you described makes more sense.