Hi all,

I would like to propose a 'linked files' mechanism for Git: a file can be declared to mirror another file in the same repository, so the two are always byte-identical. The tooling would enforce identity and keep the copies in sync automatically — no manual copy, no symlink, no commit hook.

== Motivation ==

Many projects need the same source file available from multiple paths:

- a library core reused by an example folder
  (examples/demo/core.js must equal the root core.js);
- a shared header copied into submodules;
- documentation snippets embedded in several places.

Today the only ways to keep them identical are:

- Copy — drifts whenever one side is edited;
- Symlink — breaks on some archive downloads and cross-filesystem;
- Hardlink — lost by every git checkout / git reset;
- Commit hook — a workaround, not a platform guarantee, and runs only
  at commit time.

None of these guarantees that the files are identical at any moment, which is what a maintainer actually wants.

== Proposed mechanism ==

Add a declarative file (e.g. .gitlinks, similar to .gitignore) mapping a linked path to its source:

  .gitlinks
  # linked path            source path
  examples/demo/core.js   core.js

The tooling would then:

- On commit — reject the commit if a linked file differs from its source
  (or auto-overwrite it from the source);
- On checkout / clone — materialise the linked file from the source
  (hardlink when the filesystem allows, otherwise an identical copy);
- On archive / ZIP download — keep the link so the downloaded tree
  stays correct;
- On edit — editing either path updates both, so divergence is
  impossible.

== Why this belongs at the tooling level ==

Git already stores content-addressed blobs, so two identical files share one blob internally. The missing piece is a working-tree guarantee that the paths stay identical.

== Concrete first step (smaller scope) ==

Even without full 'linked files', a valuable first deliverable would be: git archive should preserve hardlinks between identical files, the way it already preserves symlinks. That alone would let a maintainer hardlink a file locally and have the archive keep the two entries pointing at one object.

== Alternatives considered ==

- Submodules / subtrees — heavier, separate history or full copy, not
  'same file'.
- Symlinks — already preserved by git archive, but break on some download
  tools and cross-filesystem.
- Commit hooks — work only at commit time, easy to forget, not enforced.

I would appreciate feedback on this proposal.

Thanks, sporteka