NAME

     got-worktree — Game of Trees work tree format

DESCRIPTION

     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
     got(1).

     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 heeded.

     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 commit.

     Flags   This field contains the length, according to strlen(3), of path data which follows,
             and the following flags:

             STAGE   Reflects the added, modified, or deleted staged state of a path staged with
                     got stage.

             NOT_FLUSHED
                     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 checkout, got update, got cherrypick,
                     got backout, got rebase, and got histedit are in progress.  This flag is
                     always cleared before the entry is written to disk.

             NO_BLOB
                     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 got cherrypick,
                     got backout, got rebase, and got histedit.

             NO_COMMIT
                     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 cherrypick, got backout, got rebase, and got
                     histedit.

             NO_FILE_ON_DISK
                     The entry has no corresponding on-disk file in the work tree.  This happens
                     when files are removed with got remove.

     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 got stage.

     A corrupt or missing file index can be recreated on demand as follows:

           $ mv .got/file-index .got/file-index.bad
           $ got update # re-create .got/file-index
           $ find . -type f -exec touch {} + # update timestamp of all files
           $ got update # sync timestamps

     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 lockf(3).

     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 the Git garbage collector and gotadmin
     cleanup 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 got ref -d.

FILES

     .got         Meta-data directory where all files listed below reside.
     base-commit  SHA1 hex-string representation of the current base commit.
     file-index   File status information.
     format       Work tree format number.
     got.conf     Configuration file for got(1).  See got.conf(5).
     head-ref     Name of the reference to the current branch.
     lock         Lock file to obtain exclusive write access to meta data.
     path-prefix  Path inside repository the work tree was checked out from.
     repository   Path to the repository the work tree was checked out from.
     uuid         A universal unique identifier for the work tree.

SEE ALSO

     got(1), rename(2), stat(2), umask(2), lockf(3), git-repository(5), got.conf(5)