got/got-worktree.5

   1 .\"
   2 .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GOT-WORKTREE 5
  18 .Os
  19 .Sh NAME
  20 .Nm got-worktree
  21 .Nd Game of Trees work tree format
  22 .Sh DESCRIPTION
  23 A Got
  24 .Em work tree
  25 stores a file hierarchy which corresponds to a versioned
  26 snapshot stored in a Git repository.
  27 The work tree's meta data is stored in the
  28 .Pa .got
  29 directory.
  30 A work tree is created with
  31 .Cm got checkout
  32 and is required to make changes to a Git repository with
  33 .Xr got 1 .
  34 .Pp
  35 A work tree stores the path to its Git repository, the name of a reference
  36 to the branch which files were checked out from, and the ID of a commit on
  37 this branch known as the
  38 .Em base commit .
  39 .Pp
  40 File meta-data is stored in a structured file called the
  41 .Em file index
  42 which tracks the status of file modifications, additions, and deletions,
  43 relative to the base commit in the repository.
  44 The file index contains a series of records, and each such record contains
  45 the following status information for a particular file:
  46 .Bl -tag -width Ds
  47 .It Copy of filesystem meta-data
  48 Timestamp, file size, and file ownership information from
  49 .Xr stat 2 .
  50 This is only used to detect file modifications and is never applied
  51 back to the filesystem.
  52 File permissions are not tracked, except for the executable bit.
  53 When versioned files are checked out into the work tree, the current
  54 .Xr umask 2
  55 is heeded.
  56 .It Blob object ID
  57 The hash of the blob object which corresponds to the contents
  58 of this file in the repository.
  59 The hash is stored as binary data.
  60 The size of the hash depends on the hashing algorithm used in the
  61 repository.
  62 .It Commit object ID
  63 The hash of the commit object the file was checked out from.
  64 The hash is stored as binary data.
  65 This data is used to detect past incomplete update operations.
  66 Entries which do not match the work tree's base commit may still need
  67 to be updated to match file content stored in the base commit.
  68 .It Flags
  69 This field contains the length, according to
  70 .Xr strlen 3 ,
  71 of path data which follows, and the following flags:
  72 .Bl -tag -width Ds
  73 .It STAGE
  74 Reflects the added, modified, or deleted staged state of a path staged with
  75 .Cm got stage .
  76 .It NOT_FLUSHED
  77 The entry was added to the file index in memory and does not exist in file
  78 index data read from disk.
  79 This happens to files which are added to the work tree while operations
  80 such as
  81 .Cm got checkout ,
  82 .Cm got update ,
  83 .Cm got cherrypick ,
  84 .Cm got backout ,
  85 .Cm got rebase ,
  86 and
  87 .Cm got histedit
  88 are in progress.
  89 This flag is always cleared before the entry is written to disk.
  90 .It NO_BLOB
  91 The entry's on-disk file content in the work tree is not based on
  92 a blob in the repository.
  93 The blob object ID of this entry must be considered invalid.
  94 This happens when unversioned files are added with
  95 .Cm got add
  96 and when files are added to the work tree by operations such as
  97 .Cm got cherrypick ,
  98 .Cm got backout ,
  99 .Cm got rebase ,
 100 and
 101 .Cm got histedit .
 102 .It NO_COMMIT
 103 The entry is not based on a commit in the repository.
 104 The commit object ID of this entry must be considered invalid.
 105 This happens when unversioned files are added with
 106 .Cm got add
 107 and when files are added to the work tree by operations such as
 108 .Cm got cherrypick ,
 109 .Cm got backout ,
 110 .Cm got rebase ,
 111 and
 112 .Cm got histedit .
 113 .It NO_FILE_ON_DISK
 114 The entry has no corresponding on-disk file in the work tree.
 115 This happens when files are removed with
 116 .Cm got remove .
 117 .El
 118 .It Path data
 119 The path of the entry, relative to the work tree root.
 120 Path data is of variable length and NUL-padded to a multiple of 8 bytes.
 121 .It Staged blob object ID
 122 The hash of a blob object containing file content which has been
 123 staged for commit.
 124 The hash is stored as binary data.
 125 Only present if a file addition or modification has been staged with
 126 .Cm got stage .
 127 .El
 128 .Pp
 129 A corrupt or missing file index can be recreated on demand as follows:
 130 .Pp
 131 .Dl $ mv .got/file-index .got/file-index.bad
 132 .Dl $ got update # re-create .got/file-index
 133 .Dl $ find\ . -type f -exec touch {}\ + # update timestamp of all files
 134 .Dl $ got update # sync timestamps
 135 .Pp
 136 When the file index is modified, it is read into memory in its entirety,
 137 modified in place, and written to a temporary file.
 138 This temporary file is then moved on top of the old file index with
 139 .Xr rename 2 .
 140 This ensures that no other processes see an inconsistent file index
 141 which is in the process of being written.
 142 .Pp
 143 Work tree meta data must only be modified while the work tree's
 144 .Pa lock
 145 file has been exclusively locked with
 146 .Xr lockf 3 .
 147 .Pp
 148 Each work tree has a universal unique identifier.
 149 When a work tree is checked out or updated, this identifier is used to
 150 create a reference to the current base commit in the Git repository.
 151 The presence of this reference prevents the Git garbage collector and
 152 .Cm gotadmin cleanup
 153 from discarding the base commit and any objects it refers to.
 154 When a work tree is no longer needed, its reference can be deleted from
 155 the Git repository with
 156 .Cm got ref -d .
 157 .Sh FILES
 158 .Bl -tag -width path-prefix -compact
 159 .It Pa .got
 160 Meta-data directory where all files listed below reside.
 161 .It Pa base-commit
 162 hash digest hex-string representation of the current base commit.
 163 .It Pa file-index
 164 File status information.
 165 .It Pa format
 166 Work tree format number.
 167 .It Pa got.conf
 168 Configuration file for
 169 .Xr got 1 .
 170 See
 171 .Xr got.conf 5 .
 172 .It Pa head-ref
 173 Name of the reference to the current branch.
 174 .It Pa lock
 175 Lock file to obtain exclusive write access to meta data.
 176 .It Pa path-prefix
 177 Path inside repository the work tree was checked out from.
 178 .It Pa repository
 179 Path to the repository the work tree was checked out from.
 180 .It Pa uuid
 181 A universal unique identifier for the work tree.
 182 .El
 183 .Sh SEE ALSO
 184 .Xr got 1 ,
 185 .Xr rename 2 ,
 186 .Xr stat 2 ,
 187 .Xr umask 2 ,
 188 .Xr flock 3 ,
 189 .Xr git-repository 5 ,
 190 .Xr got.conf 5