Comparison

A · Copilot instructions · photoprism/photoprism B · AGENTS.md · photoprism/photoprism

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	14	4	0%
Commands	24	0	0%
Section tags	9	0	0%

What each file covers

Sections

0 shared · 14 only in A · 4 only in B

− Instructions for GitHub Copilot
− Purpose
− Single Sources of Truth (SOT)
− Build & Run (local dev; use Makefile first)
− Tests & Lint
− Project Structure & Languages
− Code Review Instructions (for Copilot)
− Style & Patterns
− Commits & Pull Requests
− Performance & Reliability
− When Unsure
− References To Help Copilot Answer Questions
− Output Expectations
− Safety Checklist Before Proposing a CLI Command
+ PhotoPrism Core Import & Index Guidelines
+ Import & Index Behavior
+ File I/O Overwrite Policy
+ Tests

Commands

0 shared · 24 only in A · 0 only in B

− make help
− make list
− make docker-build
− docker compose up
− docker compose logs -f --tail=100 photoprism
− make dep
− make build-js
− make build-go
− make watch-js
− make test
− make test-js
− make vitest-watch
− make vitest-coverage
− make test-go
− make test-short
− go test ./internal/<pkg> -run '<TestName>' -count=1
− make fmt-go
− make lint-go
− make fmt-js
− make lint-js
− make fmt-go swag-fmt swag
− go.mod
− go.sum
− make notice

Section tags

0 shared · 9 only in A · 0 only in B

− build
− test
− lint-format
− code-style
− architecture
− git-pr
− performance
− do-not
− agent-behaviour

Line diff

+17 added−102 removed9 unchanged8.1% identical

photoprism/photoprism · .github/copilot-instructions.md

@@ −1 @@

1# Instructions for GitHub Copilot

3**Last Updated:** July 28, 2026

5## Purpose

7- Provide Copilot with the single sources of truth for building, testing, and contributing to PhotoPrism.

8- Improve PR reviews and code suggestions by aligning them with our documented workflows and style.

9- Path-specific rules that apply on top of this file live in `.github/instructions/*.instructions.md`.

11## Single Sources of Truth (SOT)

13- Makefile targets (always prefer existing targets): https://github.com/photoprism/photoprism/blob/develop/Makefile

14- Developer Guide – Setup: https://docs.photoprism.app/developer-guide/setup/

15- Developer Guide – Tests: https://docs.photoprism.app/developer-guide/tests/

16- Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md

17- Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md

18- REST API (Swagger): https://docs.photoprism.dev/

19- REST API Guide: https://docs.photoprism.app/developer-guide/api/

20- Agents reference for tools/commands: https://github.com/photoprism/photoprism/blob/develop/AGENTS.md

21- Code maps: https://github.com/photoprism/photoprism/blob/develop/CODEMAP.md (backend) and https://github.com/photoprism/photoprism/blob/develop/frontend/CODEMAP.md (frontend)

22- Terminology: https://github.com/photoprism/photoprism/blob/develop/GLOSSARY.md

24## Build & Run (local dev; use Makefile first)

26- Show common tasks: `make help` (`make list` shows all targets)

27- Build local image: `make docker-build`

28- Start dev env: `docker compose up` (add `-d` for detached, or run `make up`)

29- Logs: `docker compose logs -f --tail=100 photoprism`

30- Open app: http://localhost:2342/ (HTTP) / https://app.localssl.dev/ (TLS via Traefik when enabled)

31- From the dev container:

32 - Install deps: `make dep`

33 - Build frontend: `make build-js` (or `cd frontend && npm run build`)

34 - Build backend: `make build-go`

35 - Watch frontend: `make watch-js` (stop with Ctrl+C)

36 - Run server binary: `./photoprism start`

38## Tests & Lint

40- Full tests: `make test`

41- Frontend tests (Vitest): `make test-js` (watch: `make vitest-watch`, coverage: `make vitest-coverage`)

42- Backend tests: `make test-go` (slow); `make test-short` for a fast parallel run

43- Targeted Go tests: `go test ./internal/<pkg> -run '<TestName>' -count=1`

44- Formatting and linting:

45 - Go: `make fmt-go` (gofmt + goimports) and `make lint-go` (golangci-lint)

46 - JS/Vue: `make fmt-js` and `make lint-js`. ESLint owns JS and Vue; Prettier owns CSS/SCSS/SASS only. ESLint does not run Prettier, so do not propose reflowing JS to satisfy Prettier.

47- Swagger: after changing API handlers or annotations, run `make fmt-go swag-fmt swag`; never edit `internal/api/swagger.json` by hand.

48- Dependencies: when `go.mod`, `go.sum`, or `package-lock.json` change, regenerate the license reports with `make notice`; never edit `NOTICE` or `frontend/NOTICE` manually.

50## Project Structure & Languages

52- Backend: Go (`internal/`, `pkg/`, `cmd/`) + MariaDB/SQLite

53- Frontend: Vue 3 + Vuetify 3 (`frontend/`)

54- Docker/compose for dev/CI; Traefik used for local TLS in dev profile when enabled.

55- A maintainer's working copy may contain private subdirectories (`plus/`, `pro/`, `portal/`, `specs/`) that are not part of this repository. Never reference their paths from public artifacts such as pull request descriptions, issue comments, or code comments — external readers only see a broken link.

57## Code Review Instructions (for Copilot)

59- Respect SOT above; do not invent flags, env vars, or Compose options. If a command/env var is not in the docs/Makefile/CLI help, say "not documented" and suggest checking the SOT.

60- Prefer minimal, surgical diffs. Propose changes as concrete patches and reference the relevant Makefile target or doc section.

61- Before suggesting refactors, check tests and build tasks exist and can pass with the change. If tests are missing, suggest specific Vitest/Go test snippets.

62- Security: never suggest committing secrets; prefer env vars and `.env` in dev only. Point to SECURITY.md for disclosures.

63- Data safety: never run or recommend destructive CLI operations in examples without explicit backups and `--yes`. Avoid `photoprism reset`, `photoprism users reset`, `photoprism auth reset`, or `photoprism audit reset` in PR comments unless the change is specifically about those commands; if unavoidable, add bold warnings and backup steps.

64- Database/schema: if a change touches persistence, check for migrations and mention `photoprism migrate` / `migrations` commands.

65- API changes: align with the REST API docs/spec; include curl examples only if they match current endpoints and auth notes.

66- UX/i18n: keep UI strings concise, translatable, and consistent; avoid hard-coded language constructs; prefer existing patterns/components.

68## Style & Patterns

70- Go: idiomatic Go, clear error handling, small functions, packages with focused responsibilities. Keep the public surface minimal.

71 - Every added function, including unexported helpers and helpers extracted by a refactor, needs focused coverage in a sibling `*_test.go`.

72 - Code in `pkg/*` must not import from `internal/*`; new code that needs config, entity, or DB access belongs under `internal/`.

73 - Use the permission constants in `pkg/fs` (`fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`) instead of literal file modes.

74 - Doc comments start with the name and stay compact — one line for the "what", plus a line or two only when the "why" cannot be inferred from the code. No issue numbers or change history in comments.

75- Vue/JS: Options API only. Do not introduce TypeScript (no `.ts` files, no `<script lang="ts">`), Composition API, or `<script setup>`.

76 - Shared state lives in reactive singleton modules under `src/common/` and `src/app/`. Do not propose Vuex or Pinia.

77 - Every user-visible string must go through `$gettext`, so it reaches `frontend/src/locales/translations.pot`. Standardized technical identifiers (`Client ID`, `OIDC`, `UUID`) stay literal.

78 - Prefer existing components and model methods over raw `$api` calls in components.

79- Config & flags: suggest `photoprism --help`, `photoprism show config-options` or `photoprism show config-yaml` to verify names before using them.

81## Commits & Pull Requests

83- Commit subjects use the imperative mood with a one-word scope prefix, for example `Config: Add tests for "darktable-cli" path detection`, and must not exceed 80 characters.

84- Reference related issue or PR IDs in the message when applicable, for example `Docker: Use two stage build to reduce image size #123 #5632`.

85- Do not add AI-authorship trailers such as `Co-Authored-By: Copilot` — this repository uses no commit trailers.

86- Issue titles follow the same prefix style; descriptions open with a bold user story (`**As a <role>, I want <goal>, so that <outcome>.**`) and close with a checklist of acceptance criteria using MUST, SHOULD, or MAY.

87- Commit messages, code comments, and public issue or PR text must not describe exploitable details of a security fix; present such changes as general hardening.

89## Performance & Reliability

91- Prefer using existing caches, workers, and batching strategies referenced in code and Makefile. Consider memory/CPU impact; suggest benchmarks or profiling only when justified.

93## When Unsure

95- Ask for the exact Makefile target or doc link you need, then proceed. Defer to SOT if any conflict arises.

97## References To Help Copilot Answer Questions

99- Show supported formats/filters: run `photoprism show file-formats` and `photoprism show search-filters` (use results rather than guessing).

100- For CI/dev containers, assume a Linux/Unix shell on amd64 or arm64 by default; for Windows specifics, link https://docs.photoprism.app/developer-guide/faq/

101

102## Output Expectations

103

104- Prefer short, actionable comments with code blocks that pass tests locally: `make test-js` (frontend) / `make test-go` (backend)

105- If a suggestion requires additional context (e.g., DB access, external service), call it out explicitly.

106

107## Safety Checklist Before Proposing a CLI Command

108

109- Include a dry-run or non-destructive variant if possible.

110- Recommend creating/using backups before any reset/migrate.

111

photoprism/photoprism · internal/photoprism/AGENTS.md

@@ +1 @@

1# PhotoPrism Core Import & Index Guidelines

3**Last Updated:** April 9, 2026

5## Import & Index Behavior

7- `ImportWorker` may skip a file when an identical file already exists. Use unique copies or assert DB rows only after ensuring the destination is not a duplicate.

8- Keep `SamplesPath()`, `ImportPath()`, and `OriginalsPath()` consistent when testing related files so `RelatedFiles` and `AllowExt` behave correctly.

9- `IndexOptions*` helpers now require a `*config.Config`; pass the active config, or `config.NewMinimalTestConfig(t.TempDir())` in unit tests, so face, label, and NSFW scheduling matches the current run.

10- Vision scheduling is controlled by `VisionSchedule`, `VisionFilter`, and the `Run` property in `vision.yml`. Use helpers such as `vision.FilterModels` and `entity.Photo.ShouldGenerateLabels` or `ShouldGenerateCaption` before loading media.

11- Folder albums use path-first lookup and update via `album_path` to avoid slug collisions for emoji child paths; re-indexing may repair stale collision titles while preserving user-custom titles.

12- Reuse `entity.FindLabels(...)`, `entity.FindLabelIDs(...)`, and `entity.LabelSlugs(...)` for label lookup so homophone-aware exact-name matching stays aligned across entity and search packages.

14## File I/O Overwrite Policy

16- Default to safety: callers must not overwrite non-empty destination files unless they opt in with `force=true`.

17- Replacing an empty destination file is allowed without `force=true`.

18- Open overwriting destinations with `O_WRONLY|O_CREATE|O_TRUNC` so stale trailing bytes cannot survive; use `O_EXCL` when the caller must detect collisions.

19- App-level overwrite helpers live in `internal/photoprism/mediafile.go`; reusable helpers live in `pkg/fs/copy.go` and `pkg/fs/move.go`.

20- Set `force=true` only for explicit replace flows or admin tools with confirmed overwrite, not for import or index flows that touch Originals.

22## Tests

24- In `internal/photoprism` tests, rely on `photoprism.Config()` for runtime-accurate behavior; only build a new config if you replace it with `photoprism.SetConfig`.

@@ −1 +1 @@

1−# Instructions for GitHub Copilot

1+# PhotoPrism Core Import & Index Guidelines

3−**Last Updated:** July 28, 2026

3+**Last Updated:** April 9, 2026

5−## Purpose

5+## Import & Index Behavior

7−- Provide Copilot with the single sources of truth for building, testing, and contributing to PhotoPrism.

8−- Improve PR reviews and code suggestions by aligning them with our documented workflows and style.

9−- Path-specific rules that apply on top of this file live in `.github/instructions/*.instructions.md`.

7+- `ImportWorker` may skip a file when an identical file already exists. Use unique copies or assert DB rows only after ensuring the destination is not a duplicate.

8+- Keep `SamplesPath()`, `ImportPath()`, and `OriginalsPath()` consistent when testing related files so `RelatedFiles` and `AllowExt` behave correctly.

9+- `IndexOptions*` helpers now require a `*config.Config`; pass the active config, or `config.NewMinimalTestConfig(t.TempDir())` in unit tests, so face, label, and NSFW scheduling matches the current run.

10+- Vision scheduling is controlled by `VisionSchedule`, `VisionFilter`, and the `Run` property in `vision.yml`. Use helpers such as `vision.FilterModels` and `entity.Photo.ShouldGenerateLabels` or `ShouldGenerateCaption` before loading media.

11+- Folder albums use path-first lookup and update via `album_path` to avoid slug collisions for emoji child paths; re-indexing may repair stale collision titles while preserving user-custom titles.

12+- Reuse `entity.FindLabels(...)`, `entity.FindLabelIDs(...)`, and `entity.LabelSlugs(...)` for label lookup so homophone-aware exact-name matching stays aligned across entity and search packages.

1013

11−## Single Sources of Truth (SOT)

14+## File I/O Overwrite Policy

1215

13−- Makefile targets (always prefer existing targets): https://github.com/photoprism/photoprism/blob/develop/Makefile

14−- Developer Guide – Setup: https://docs.photoprism.app/developer-guide/setup/

15−- Developer Guide – Tests: https://docs.photoprism.app/developer-guide/tests/

16−- Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md

17−- Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md

18−- REST API (Swagger): https://docs.photoprism.dev/

19−- REST API Guide: https://docs.photoprism.app/developer-guide/api/

20−- Agents reference for tools/commands: https://github.com/photoprism/photoprism/blob/develop/AGENTS.md

21−- Code maps: https://github.com/photoprism/photoprism/blob/develop/CODEMAP.md (backend) and https://github.com/photoprism/photoprism/blob/develop/frontend/CODEMAP.md (frontend)

22−- Terminology: https://github.com/photoprism/photoprism/blob/develop/GLOSSARY.md

16+- Default to safety: callers must not overwrite non-empty destination files unless they opt in with `force=true`.

17+- Replacing an empty destination file is allowed without `force=true`.

18+- Open overwriting destinations with `O_WRONLY|O_CREATE|O_TRUNC` so stale trailing bytes cannot survive; use `O_EXCL` when the caller must detect collisions.

19+- App-level overwrite helpers live in `internal/photoprism/mediafile.go`; reusable helpers live in `pkg/fs/copy.go` and `pkg/fs/move.go`.

20+- Set `force=true` only for explicit replace flows or admin tools with confirmed overwrite, not for import or index flows that touch Originals.

2321

24−## Build & Run (local dev; use Makefile first)

22+## Tests

2523

26−- Show common tasks: `make help` (`make list` shows all targets)

27−- Build local image: `make docker-build`

28−- Start dev env: `docker compose up` (add `-d` for detached, or run `make up`)

29−- Logs: `docker compose logs -f --tail=100 photoprism`

30−- Open app: http://localhost:2342/ (HTTP) / https://app.localssl.dev/ (TLS via Traefik when enabled)

31−- From the dev container:

32− - Install deps: `make dep`

33− - Build frontend: `make build-js` (or `cd frontend && npm run build`)

34− - Build backend: `make build-go`

35− - Watch frontend: `make watch-js` (stop with Ctrl+C)

36− - Run server binary: `./photoprism start`

24+- In `internal/photoprism` tests, rely on `photoprism.Config()` for runtime-accurate behavior; only build a new config if you replace it with `photoprism.SetConfig`.

3725

38−## Tests & Lint

39−

40−- Full tests: `make test`

41−- Frontend tests (Vitest): `make test-js` (watch: `make vitest-watch`, coverage: `make vitest-coverage`)

42−- Backend tests: `make test-go` (slow); `make test-short` for a fast parallel run

43−- Targeted Go tests: `go test ./internal/<pkg> -run '<TestName>' -count=1`

44−- Formatting and linting:

45− - Go: `make fmt-go` (gofmt + goimports) and `make lint-go` (golangci-lint)

46− - JS/Vue: `make fmt-js` and `make lint-js`. ESLint owns JS and Vue; Prettier owns CSS/SCSS/SASS only. ESLint does not run Prettier, so do not propose reflowing JS to satisfy Prettier.

47−- Swagger: after changing API handlers or annotations, run `make fmt-go swag-fmt swag`; never edit `internal/api/swagger.json` by hand.

48−- Dependencies: when `go.mod`, `go.sum`, or `package-lock.json` change, regenerate the license reports with `make notice`; never edit `NOTICE` or `frontend/NOTICE` manually.

49−

50−## Project Structure & Languages

51−

52−- Backend: Go (`internal/`, `pkg/`, `cmd/`) + MariaDB/SQLite

53−- Frontend: Vue 3 + Vuetify 3 (`frontend/`)

54−- Docker/compose for dev/CI; Traefik used for local TLS in dev profile when enabled.

55−- A maintainer's working copy may contain private subdirectories (`plus/`, `pro/`, `portal/`, `specs/`) that are not part of this repository. Never reference their paths from public artifacts such as pull request descriptions, issue comments, or code comments — external readers only see a broken link.

56−

57−## Code Review Instructions (for Copilot)

58−

59−- Respect SOT above; do not invent flags, env vars, or Compose options. If a command/env var is not in the docs/Makefile/CLI help, say "not documented" and suggest checking the SOT.

60−- Prefer minimal, surgical diffs. Propose changes as concrete patches and reference the relevant Makefile target or doc section.

61−- Before suggesting refactors, check tests and build tasks exist and can pass with the change. If tests are missing, suggest specific Vitest/Go test snippets.

62−- Security: never suggest committing secrets; prefer env vars and `.env` in dev only. Point to SECURITY.md for disclosures.

63−- Data safety: never run or recommend destructive CLI operations in examples without explicit backups and `--yes`. Avoid `photoprism reset`, `photoprism users reset`, `photoprism auth reset`, or `photoprism audit reset` in PR comments unless the change is specifically about those commands; if unavoidable, add bold warnings and backup steps.

64−- Database/schema: if a change touches persistence, check for migrations and mention `photoprism migrate` / `migrations` commands.

65−- API changes: align with the REST API docs/spec; include curl examples only if they match current endpoints and auth notes.

66−- UX/i18n: keep UI strings concise, translatable, and consistent; avoid hard-coded language constructs; prefer existing patterns/components.

67−

68−## Style & Patterns

69−

70−- Go: idiomatic Go, clear error handling, small functions, packages with focused responsibilities. Keep the public surface minimal.

71− - Every added function, including unexported helpers and helpers extracted by a refactor, needs focused coverage in a sibling `*_test.go`.

72− - Code in `pkg/*` must not import from `internal/*`; new code that needs config, entity, or DB access belongs under `internal/`.

73− - Use the permission constants in `pkg/fs` (`fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`) instead of literal file modes.

74− - Doc comments start with the name and stay compact — one line for the "what", plus a line or two only when the "why" cannot be inferred from the code. No issue numbers or change history in comments.

75−- Vue/JS: Options API only. Do not introduce TypeScript (no `.ts` files, no `<script lang="ts">`), Composition API, or `<script setup>`.

76− - Shared state lives in reactive singleton modules under `src/common/` and `src/app/`. Do not propose Vuex or Pinia.

77− - Every user-visible string must go through `$gettext`, so it reaches `frontend/src/locales/translations.pot`. Standardized technical identifiers (`Client ID`, `OIDC`, `UUID`) stay literal.

78− - Prefer existing components and model methods over raw `$api` calls in components.

79−- Config & flags: suggest `photoprism --help`, `photoprism show config-options` or `photoprism show config-yaml` to verify names before using them.

80−

81−## Commits & Pull Requests

82−

83−- Commit subjects use the imperative mood with a one-word scope prefix, for example `Config: Add tests for "darktable-cli" path detection`, and must not exceed 80 characters.

84−- Reference related issue or PR IDs in the message when applicable, for example `Docker: Use two stage build to reduce image size #123 #5632`.

85−- Do not add AI-authorship trailers such as `Co-Authored-By: Copilot` — this repository uses no commit trailers.

86−- Issue titles follow the same prefix style; descriptions open with a bold user story (`**As a <role>, I want <goal>, so that <outcome>.**`) and close with a checklist of acceptance criteria using MUST, SHOULD, or MAY.

87−- Commit messages, code comments, and public issue or PR text must not describe exploitable details of a security fix; present such changes as general hardening.

88−

89−## Performance & Reliability

90−

91−- Prefer using existing caches, workers, and batching strategies referenced in code and Makefile. Consider memory/CPU impact; suggest benchmarks or profiling only when justified.

92−

93−## When Unsure

94−

95−- Ask for the exact Makefile target or doc link you need, then proceed. Defer to SOT if any conflict arises.

96−

97−## References To Help Copilot Answer Questions

98−

99−- Show supported formats/filters: run `photoprism show file-formats` and `photoprism show search-filters` (use results rather than guessing).

100−- For CI/dev containers, assume a Linux/Unix shell on amd64 or arm64 by default; for Windows specifics, link https://docs.photoprism.app/developer-guide/faq/

101−

102−## Output Expectations

103−

104−- Prefer short, actionable comments with code blocks that pass tests locally: `make test-js` (frontend) / `make test-go` (backend)

105−- If a suggestion requires additional context (e.g., DB access, external service), call it out explicitly.

106−

107−## Safety Checklist Before Proposing a CLI Command

108−

109−- Include a dry-run or non-destructive variant if possible.

110−- Recommend creating/using backups before any reset/migrate.

11126