docs/spec.md

   1 # Git LFS Specification
   2
   3 This is a general guide for Git LFS clients.  Typically it should be
   4 implemented by a command line `git-lfs` tool, but the details may be useful
   5 for other tools.
   6
   7 ## The Pointer
   8
   9 The core Git LFS idea is that instead of writing large blobs to a Git repository,
  10 only a pointer file is written.
  11
  12 * Pointer files are text files which MUST contain only UTF-8 characters.
  13 * Each line MUST be of the format `{key} {value}\n` (trailing unix newline).
  14 * Only a single space character between `{key}` and `{value}`.
  15 * Keys MUST only use the characters `[a-z] [0-9] . -`.
  16 * The first key is _always_ `version`.
  17 * Lines of key/value pairs MUST be sorted alphabetically in ascending order
  18 (with the exception of `version`, which is always first).
  19 * Values MUST NOT contain return or newline characters.
  20 * Pointer files MUST be stored in Git with their executable bit matching that
  21 of the replaced file.
  22
  23 An empty file is the pointer for an empty file. That is, empty files are
  24 passed through LFS without any change.
  25
  26 The required keys are:
  27
  28 * `version` is a URL that identifies the pointer file spec.  Parsers MUST use
  29 simple string comparison on the version, without any URL parsing or
  30 normalization.  It is case sensitive, and %-encoding is discouraged.
  31 * `oid` tracks the unique object id for the file, prefixed by its hashing
  32 method: `{hash-method}:{hash}`.  Currently, only `sha256` is supported.
  33 * `size` is in bytes.
  34
  35 Example of a v1 text pointer:
  36
  37 ```
  38 version https://git-lfs.github.com/spec/v1
  39 oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
  40 size 12345
  41 (ending \n)
  42 ```
  43
  44 Blobs created with the pre-release version of the tool generated files with
  45 a different version URL.  Git LFS can read these files, but writes them using
  46 the version URL above.
  47
  48 ```
  49 version https://hawser.github.com/spec/v1
  50 oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
  51 size 12345
  52 (ending \n)
  53 ```
  54
  55 For testing compliance of any tool generating its own pointer files, the
  56 reference is this official Git LFS tool:
  57
  58 **NOTE:** exact pointer command behavior TBD!
  59
  60 * Tools that parse and regenerate pointer files MUST preserve keys that they
  61 don't know or care about.
  62 * Run the `pointer` command to generate a pointer file for the given local
  63 file:
  64
  65     ```
  66     $ git lfs pointer --file=path/to/file
  67     Git LFS pointer for path/to/file:
  68
  69     version https://git-lfs.github.com/spec/v1
  70     oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
  71     size 12345
  72     ```
  73
  74 * Run `pointer` to compare the blob OID of a pointer file built by Git LFS with
  75 a pointer built by another tool.
  76
  77   * Write the other implementation's pointer to "other/pointer/file":
  78
  79     ```
  80     $ git lfs pointer --file=path/to/file --pointer=other/pointer/file
  81     Git LFS pointer for path/to/file:
  82
  83     version https://git-lfs.github.com/spec/v1
  84     oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
  85     size 12345
  86
  87     Blob OID: 60c8d8ab2adcf57a391163a7eeb0cdb8bf348e44
  88
  89     Pointer from other/pointer/file
  90     version https://git-lfs.github.com/spec/v1
  91     oid sha256 4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
  92     size 12345
  93
  94     Blob OID: 08e593eeaa1b6032e971684825b4b60517e0638d
  95
  96     Pointers do not match
  97     ```
  98
  99   * It can also read STDIN to get the other implementation's pointer:
 100
 101     ```
 102     $ cat other/pointer/file | git lfs pointer --file=path/to/file --stdin
 103     Git LFS pointer for path/to/file:
 104
 105     version https://git-lfs.github.com/spec/v1
 106     oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
 107     size 12345
 108
 109     Blob OID: 60c8d8ab2adcf57a391163a7eeb0cdb8bf348e44
 110
 111     Pointer from STDIN
 112     version https://git-lfs.github.com/spec/v1
 113     oid sha256 4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
 114     size 12345
 115
 116     Blob OID: 08e593eeaa1b6032e971684825b4b60517e0638d
 117
 118     Pointers do not match
 119     ```
 120
 121 ## Intercepting Git
 122
 123 Git LFS uses the `clean` and `smudge` filters to decide which files use it.  The
 124 global filters can be set up with `git lfs install`:
 125
 126 ```
 127 $ git lfs install
 128 ```
 129
 130 These filters ensure that large files aren't written into the repository proper,
 131 instead being stored locally at `.git/lfs/objects/{OID-PATH}` (where `{OID-PATH}`
 132 is a sharded filepath of the form `OID[0:2]/OID[2:4]/OID`), synchronized with
 133 the Git LFS server as necessary.  Here is a sample path to a file:
 134
 135     .git/lfs/objects/4d/7a/4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
 136
 137 The `clean` filter runs as files are added to repositories.  Git sends the
 138 content of the file being added as STDIN, and expects the content to write
 139 to Git as STDOUT.
 140
 141 * Stream binary content from STDIN to a temp file, while calculating its SHA-256
 142 signature.
 143 * Atomically move the temp file to `.git/lfs/objects/{OID-PATH}` if it does not
 144 exist, and the sha-256 signature of the contents matches the given OID.
 145 * Delete the temp file.
 146 * Write the pointer file to STDOUT.
 147
 148 Note that the `clean` filter does not push the file to the server.  Use the
 149 `git push` command to do that (lfs files are pushed before commits in a pre-push hook).
 150
 151 The `smudge` filter runs as files are being checked out from the Git repository
 152 to the working directory.  Git sends the content of the Git blob as STDIN, and
 153 expects the content to write to the working directory as STDOUT.
 154
 155 * Read 100 bytes.
 156 * If the content is ASCII and matches the pointer file format:
 157   * Look for the file in `.git/lfs/objects/{OID-PATH}`.
 158   * If it's not there, download it from the server.
 159   * Write its contents to STDOUT
 160 * Otherwise, simply pass the STDIN out through STDOUT.
 161
 162 The `.gitattributes` file controls when the filters run.  Here's a sample file that
 163 runs all mp3 and zip files through Git LFS:
 164
 165 ```
 166 $ cat .gitattributes
 167 *.mp3 filter=lfs -text
 168 *.zip filter=lfs -text
 169 ```
 170
 171 Use the `git lfs track` command to view and add to `.gitattributes`.