[Feature] Full user control over the duplicate counter in the storage template

[bitbalancer]

I have searched the existing feature requests, both open and closed, to make sure this is not a duplicate request.

• Yes

The feature

The storage template exists so that administrators can impose their own filename convention instead of Immich's: path layout, date format, element order, separators, all user-defined. The duplicate counter is the single exception.

I would like it brought under the same user control as everything else in the template.

Current behaviour

server/src/services/storage-template.service.ts renders the template once, then appends the counter inside the existence loop:

duplicateCount++;
destination = `${fullPath}+${duplicateCount}.${extension}`;

Four decisions are taken on the user's behalf there, none of them changeable:

	currently hard-coded as
suffix indicator	+
padding	none — +9, +10
start value	1
position	always last, after everything the template produced

The request

Make all four user-definable, so the whole filename comes from the template.

A naming convention only helps if it is applied consistently. If a convention uses _ as its element separator, fixed-width counters, and a set element order, a counter in a different format leaves colliding files inconsistent with the rest of the archive.

The current behaviour is correct and collision-safe; this is about configurability rather than a defect.

Proposed mechanism

A {{dupe}} helper, usable anywhere in the filename portion of the template. Making the counter a template element rather than a settings field is what brings all four aspects under the user's control at once.

{{y}}/{{MM}}/{{y}}-{{MM}}-{{dd}}_{{HH}}-{{mm}}-{{ss}}{{dupe prefix="_" pad=2 start=1}}

Helper call	no collision	1st collision	2nd
{{dupe}}	(empty)	+1	+2
{{dupe prefix="_" pad=2}}	(empty)	_01	_02
{{dupe prefix="_" pad=3 start=0}}	(empty)	_000	_001
{{dupe prefix="-" start=2}}	(empty)	-2	-3

The suffix indicator belongs inside the helper rather than as literal template text. Were it literal — ..._{{dupe}} — every non-colliding file would render a dangling _. Indicator and number have to be suppressed as a unit.

Implementation sketch

Render per attempt with the helper bound to the current counter, rather than rendering once and appending:

const render = (n: number | null) =>
  compiled(context, { helpers: { dupe: dupeHelper(n) } });

let n: number | null = null;
let destination = render(n);

while (await this.storageRepository.checkFileExists(destination)) {
  n = n === null ? startFromHash : n + 1;
  destination = render(n);
}

Binding the helper per render rather than through handlebar.registerHelper keeps the counter out of global state. It is also required by the existing strict: true compile option, under which an unregistered {{dupe}} would throw at render time.

Templates are already compiled and cached in this._template, so re-rendering on collision is cheap, and collisions are rare.

Backward compatibility

If the template contains no {{dupe}}, keep today's append-+N behaviour exactly. Existing instances are unaffected, nothing migrates, and no new admin setting is required. The feature lives entirely in the template string users already edit.

The main implementation hazard

The +N format is hard-coded in a second place: the Storage Template Migration job uses it to detect files it has already moved.

const diff = source.replace(fullPath, '').replace(`.${extension}`, '');
const hasDuplicationAnnotation = /^\+\d+$/.test(diff);

That check assumes the counter is a trailing annotation, so two things follow:

1. It must keep accepting /^\+\d+$/ permanently, for libraries that already contain +N files.
2. The current check relies on the counter being trailing, so that the difference between the source path and the rendered template is the annotation itself. If the counter can appear elsewhere in the name, that difference is no longer a reliable indicator. Detection would instead render the template at each candidate counter value and compare the result against the source path.

Validation

• pad 0–9, prefix must not contain / or \

Out of scope

Only assets Immich owns via the storage template. External library assets keep their on-disk paths and are unaffected.

Prior art

• Does Immich overwrite files with similar filenames? #3324 explains the +N behaviour but does not propose changing it.
• Storage Template. Same named files. #12445 mentions +x in passing; the actual request there is to lowercase file extensions.
• [Feature] Expose more substitution variables in storage templates. #9905 asks for additional substitution variables, not for control over the counter.

There are currently no custom Handlebars helpers in the repository, so {{dupe}} would be the first. The mechanism is standard Handlebars, but it would be a new pattern here.

Platform

• Server
• Web
• Mobile

[bo0tzz]

#25411