What do the `tmutil startbackup` options really mean?

Question

Once you configured your Time Machine setup, you can manually start a backup by running

tmutil startbackup

in Terminal. According to man page, those are the options:

Options:
--auto Run the backup in a mode similar to system-scheduled backups.
--block Wait (block) until the backup is finished before exiting.
--rotation Allow automatic destination rotation during the backup.
--destination Perform the backup to the destination corresponding to the specified ID.

And as explanation it says:

The --auto option provides a supported mechanism with which to trigger "automatic-like" backups, similar to automatic backups that are scheduled by the system. While this is not identical to true system-scheduled backups, it provides custom schedulers the ability to achieve some (but not all) behavior normally exhibited when operating in automatic mode.

But what does that mean? How would a backup with and without --auto behave differently? Is there anything special about an automatic backup?

In the UI, you can select to make backups automatically, in that case Time Machine will try to make one backup an hour. Or you can disable it, in that case Time Machine will make only an backup when I request it, e.g. through the menu item or via the context menu of the disk time in the system preferences. But in case of a command line and with auto backup disabled, the backup only happens when I call that command, so it is always a manual backup, yet there is an auto option and the explanation doesn't tell me what is different about it.

Also what about --rotation? An automatic backup will also automatically rotate, so doesn't --auto imply --rotation? What happens if I don't use rotation? Will it keep all backups until the disk is full and then fail to make any new backups? And if only --auto --rotation behaves like automatic backups, how would only --rotation behave? The man page says nothing about that.

Answer 1

I still have no clue about the --auto parameter but I figured out what --rotation means. The --rotation parameter does nothing unless you have multiple Time Machine destinations configured.

If you have multiple destinations configured and automatic Time Machine backups enabled in UI, Time Machine will rotate the destinations with every backup. E.g. if you have destinations A, B, C, it will make the first backup on A, the second one on B, the third one on C, and then go back to A. If a destination is missing when a backup is scheduled (drive not connected, network drive not reachable), it will skip that destination and rotate to the next one in the list.

In the UI there is no way to disable that kind of rotation. If you have multiple destinations, they are always rotated like this. Yet when making a backups from command line, it's up to you, to either enabled that behavior or not. The parameter --auto will not enabled rotation, despite claiming it is behaving pretty much like automatic backups do.

If you don't use --rotation, the backup will be done to the same destination as the last backup, unless that destination is unavailable, in which case it will be done to whatever destination is available (no idea how Time Machine would choose among multiple options in that case. Order they were added? Local drive wins over network?). Time Machine will then stick to that single destination again for as long as it stays available, even if other destinations become available over time. It will not rotate between them unless is has to, whereas with --rotation it will rotate after every single backup.

If you want to use a specific destination for your next backup, you need to provide the parameter --destination. If you use both, --destination and --rotate, the backup is scheduled for the provided destination and --rotate does not seem to have any effect as far as I can tell. If the manual selected destination is currently unavailable, a backup is scheduled for that destination and performed as soon as it becomes available, there is no fallback to an alternative destination in that case as you forced Time Machine to only use that destination for the next backup.