got-worktree — Got
A Got work tree stores a file hierarchy which
corresponds to a versioned snapshot stored in a Git repository. The work
tree's meta data is stored in the .got directory. A
work tree is created with
got checkout and is
required to make changes to a Git repository with
A work tree stores the path to its Git repository, the name of a
reference to the branch which files were checked out from, and the ID of a
commit on this branch known as the base commit.
File meta-data is stored in a structured file called the
file index which tracks the status of file modifications,
additions, and deletions, relative to the base commit in the repository. The
file index contains a series of records, and each such record contains the
following status information for a particular file:
- Copy of filesystem meta-data
- Timestamp, file size, and file ownership information from
stat(2). This is only used to detect file modifications
and is never applied back to the filesystem. File permissions are not
tracked, except for the executable bit. When versioned files are checked
out into the work tree, the current umask(2) is
- Blob object ID
- The SHA1 hash of the blob object which corresponds to the contents of this
file in the repository. The hash is stored as binary data.
- Commit object ID
- The SHA1 hash of the commit object the file was checked out from. The hash
is stored as binary data. This data is used to detect past incomplete
update operations. Entries which do not match the work tree's base commit
may still need to be updated to match file content stored in the base
- This field contains the length, according to strlen(3),
of path data which follows, and the following flags:
- Reflects the added, modified, or deleted staged state of a path staged
- The entry was added to the file index in memory and does not exist in
file index data read from disk. This happens to files which are added
to the work tree while operations such as
got rebase, and
got histedit are in progress. This flag is
always cleared before the entry is written to disk.
- The entry's on-disk file content in the work tree is not based on a
blob in the repository. The blob object ID of this entry must be
considered invalid. This happens when unversioned files are added with
got add and when files are added to the work
tree by operations such as
- The entry is not based on a commit in the repository. The commit
object ID of this entry must be considered invalid. This happens when
unversioned files are added with
got add and
when files are added to the work tree by operations such as
got rebase, and
- The entry has no corresponding on-disk file in the work tree. This
happens when files are removed with
- Path data
- The path of the entry, relative to the work tree root. Path data is of
variable length and NUL-padded to a multiple of 8 bytes.
- Staged blob object ID
- The SHA1 hash of a blob object containing file content which has been
staged for commit. The hash is stored as binary data. Only present if a
file addition or modification has been staged with
A corrupt or missing file index can be recreated on demand with
got update. When the file index is modified, it is
read into memory in its entirety, modified in place, and written to a
temporary file. This temporary file is then moved on top of the old file
index with rename(2). This ensures that no other processes
see an inconsistent file index which is in the process of being written.
Work tree meta data must only be modified while the work tree's
lock file has been exclusively locked with
Each work tree has a universal unique identifier. When a work tree
is checked out or updated, this identifier is used to create a reference to
the current base commit in the Git repository. The presence of this
reference prevents Git garbage collectors from discarding the base commit
and any objects it refers to. When a work tree is no longer needed its
reference can be deleted from the Git repository with
- Meta-data directory where all files listed below reside.
- SHA1 hex-string representation of the current base commit.
- File status information.
- Work tree format number.
- Name of the reference to the current branch.
- Lock file to obtain exclusive write access to meta data.
- Path inside repository the work tree was checked out from.
- Path to the repository the work tree was checked out from.
- A universal unique identifier for the work tree.