Understanding Subversion .svn/entries Files

Learn what the historical Subversion .svn/entries file stored, how legacy and modern working-copy metadata differ, and how to inspect or repair working copies safely.

Subversion stores more than project files in a working copy. A working copy is a local checkout managed by Subversion, and it includes administrative metadata that lets the client compare local files with repository content, detect changes, perform updates, and prepare commits.

In older Subversion working-copy formats, much of this metadata was stored below hidden .svn directories. One important historical file was .svn/entries. The file described a working-copy directory and its immediate versioned children. It was an internal implementation detail, not a normal project configuration file.

Key idea: The .svn/entries file belonged to the local working copy. It was not the repository itself, and it was not intended for routine manual editing.

Working-copy metadata and the .svn directory

The repository is Subversion's central versioned data store. It contains repository history, revisions, paths, and stored file content. A working copy is a local representation of part of that repository, plus local edits and administrative data.

Working-copy metadata connects local paths to repository paths and records the state needed by Subversion commands. It is different from:

Repository data: history and versioned content stored by the repository server or repository service.
User project files: source code, documentation, build files, and other files in the project.
Working-copy metadata: local administrative information used to manage the relationship between project files and the repository.

In older layouts, each versioned directory commonly had its own hidden .svn administrative directory. The historical path was therefore relative to a working-copy directory, for example project/src/.svn/entries. The exact file presence and format depended on the Subversion client and working-copy format.

What the entries file represented

An entries file historically described the directory containing it and the directory's immediate children. Its records helped Subversion identify versioned items and understand their current working-copy state.

A record could represent a file or directory and could include information such as its name, node kind, repository location, revision-related values, and pending local operations. The node kind is the type of item, commonly a file or directory.

The file also supported decisions made during everyday operations. For example, Subversion needed local metadata to determine whether a file was modified, whether an item was scheduled for addition or deletion, whether a directory had copied ancestry, or whether a conflict required user attention.

The information was implementation-specific. Early clients used version-dependent text-based formats, and later formats changed how working-copy state was represented. A particular entries-file layout must not be treated as a portable schema for every Subversion release.

Historical location and scope

project/
├── .svn/
│   └── entries
├── README.txt
├── src/
│   ├── .svn/
│   │   └── entries
│   └── main.c
└── tests/
    ├── .svn/
    │   └── entries
    └── test-main.c

In this historical example, the top-level project/.svn/entries described the top-level directory and children such as README.txt, src, and tests. The src/.svn/entries file described src and its immediate children. It was not necessarily a complete recursive index of the entire checkout.

Before Subversion 1.7, many working copies used this per-directory metadata arrangement. Subversion 1.7 and later introduced a centralized working-copy layout in which the principal metadata store is an SQLite database at .svn/wc.db, normally in the working-copy root. Modern clients may therefore expose no per-directory entries files.

Information historically represented by entries

Category	Representative information	Why Subversion needs it
Item identity	Directory and file names; node kind such as file or directory	Identifies versioned children and determines which operations apply
Repository location	Repository URL and repository identity	Associates a local path with the correct repository and branch location
Revision state	Working and base revision-related information	Supports comparisons, updates, commits, and repository queries
Local schedule	Normal state, addition, deletion, or replacement	Records pending operations that affect the next commit
Modification tracking	Timestamps, local-change indicators, and sometimes stored pristine text	Helps detect local edits and compare files with their base content
Properties and locks	Versioned properties and applicable lock state	Preserves property changes and supports lock-aware operations
Copy and conflict state	Copied-from ancestry and conflict-related information where applicable	Supports branching, merging, conflict handling, and resolution

Pristine text means a stored base version of content used to compare local changes and support operations. The way pristine content and related metadata were stored varied by working-copy format.

Relationship to common Subversion commands

Subversion commands use working-copy metadata rather than treating the project files alone as sufficient. The following commands provide supported views of information that older entries records helped maintain.

# Show repository URL, revision, repository root, and working-copy details
svn info

# Show local modifications, unversioned items, schedules, and conflicts
svn status

# Include available repository changes when network access is available
svn status -u

svn status uses working-copy state to report modified, added, deleted, missing, unversioned, and conflicted items.
svn info displays supported repository and working-copy details such as the URL and revision.
svn update uses metadata to apply incoming changes to the correct working-copy paths and identify conflicts.
svn switch changes the repository location associated with paths while preserving the working-copy relationship.
svn merge tracks source paths, revisions, local state, and conflicts while applying changes.
svn commit determines which scheduled and modified items are eligible to be sent to the repository.
svn add and svn delete record pending schedules rather than immediately changing repository history.
svn revert uses the base state and metadata to discard selected local changes.
svn resolve records that a conflict has been handled after the user chooses the desired content.

Deleting, editing, or copying administrative files by hand can make metadata disagree with the working files, repository location, or base content. That can produce missing, locked, inconsistent, or otherwise unusable working copies.

Legacy and modern working-copy layouts

Subversion working-copy era	Administrative layout	Primary metadata location	Operational guidance
Older per-directory metadata layouts	Many versioned directories contain hidden administrative directories	Each directory may contain `.svn/entries` and related metadata	Do not assume one exact entries-file syntax; use a compatible client and supported commands
Subversion 1.7 and later centralized metadata layouts	Metadata is centralized for the working copy	Typically the root `.svn/wc.db` SQLite database, with related administrative data	Use modern Subversion commands; per-directory entries files may not exist or be used

Upgrading an old working copy with a newer client can migrate its administrative layout. The project files may look unchanged while the metadata structure changes. A current checkout that lacks .svn/entries is not necessarily damaged.

Inspecting a legacy working copy safely

For normal administration, prefer supported commands over parsing internal files:

svn info
svn status
svn cleanup

On a Unix-like system, a read-only layout check can show whether administrative directories occur throughout a tree:

find . -type d -name .svn

This command is useful for recognizing a legacy per-directory layout, but it is not a repair method. Direct inspection can be appropriate for forensic, migration, or compatibility work when a legacy client or tool requires it. Even then, treat the files as read-only and interpret them with the matching Subversion client version.

Do not assume that a file copied from another working copy is valid. Repository identity, URLs, revisions, paths, schedules, and local state may all differ.

Supported commands versus direct metadata handling

Task	Recommended command or action	Why it is safer than editing metadata
View repository and revision information	`svn info`	The client interprets its own working-copy format and reports supported fields
View local changes	`svn status` or `svn diff`	The client compares working files with the correct base state
Clean up interrupted operations	`svn cleanup`	Performs supported cleanup without arbitrarily removing administrative state
Resolve conflicts	`svn resolve` after reviewing the files	Records resolution using the client's conflict and working-copy rules
Recover from corruption	Preserve changes, create a fresh checkout, and reapply validated work	A new checkout creates internally consistent metadata instead of requiring manual reconstruction

Recovering from suspected metadata damage

Common warning signs include a deleted or hand-edited .svn/entries file, errors about inconsistent working-copy metadata, unexpected repository URLs, or status results that do not match the files on disk.

Stop modifying the damaged working copy until local changes are preserved.
Review the changes with svn status and save text changes with svn diff > local-changes.patch.
Make a separate copy of important unversioned files and any local binary changes.
Run svn cleanup from the relevant working-copy root if an operation was interrupted or the working copy is reported as locked.
If the working copy remains unusable, create a clean checkout and reapply only reviewed changes.

# Preserve local text changes
svn diff > local-changes.patch

# Create a clean replacement working copy
svn checkout REPOSITORY_URL target-directory

Troubleshooting common questions

There is no .svn/entries file in my current checkout

The checkout may use the centralized format introduced in Subversion 1.7 or a later format. Use svn info and svn status. If diagnostic access is necessary, inspect the top-level .svn directory, where wc.db is the principal modern metadata store. Do not create an entries file manually.

Subversion says the working copy is locked

An update, switch, merge, or another operation may have been interrupted. Run svn cleanup from the relevant working-copy root and follow any reported instructions. Do not delete administrative files to remove the lock.

An entries file was deleted, edited, or copied from another checkout

The metadata may no longer agree with the files and repository. Preserve local work, then create a fresh checkout and move or reapply changes using supported tools.

A script stopped working after a client upgrade

The script may depend on an internal format that changed between working-copy versions. Replace direct metadata parsing with supported Subversion commands, language bindings, or APIs that provide the required information.

Copying a working copy produced metadata errors

The copy may have been incomplete, may contain altered metadata paths, or may combine administrative data with unrelated files. Prefer a new checkout and reapply only intentional local modifications.

Exam-relevant summary

.svn is a hidden administrative directory used by Subversion working copies.
.svn/entries was a historical file describing a directory and its immediate versioned children.
Entries metadata could represent names, node kinds, repository URLs, repository identity, revisions, schedules, timestamps, properties, locks, copied-from ancestry, pristine content, and conflict state.
Older working copies commonly used per-directory administrative metadata.
Subversion 1.7 and later primarily use centralized metadata in .svn/wc.db.
The entries format is version-dependent and should not be treated as a portable public API.
Use svn info, svn status, svn cleanup, and fresh checkouts instead of hand-editing metadata.

For the historical file itself, see Subversion .svn/entries. The safe operational principle remains the same: let the matching Subversion client interpret and maintain working-copy metadata.