github.com/q2/git-lfs@v0.5.1-0.20150410234700-03a0d4cec40e/docs/spec.md (about)

     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  ```
    13  version https://git-lfs.github.com/spec/v1
    14  oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
    15  size 12345
    16  (ending \n)
    17  ```
    18  
    19  The pointer file should be small (less than 200 bytes), and consist of only
    20  ASCII characters.  Libraries that generate this should write the file
    21  identically, so that different implementations write consistent pointers that
    22  translate to the same Git blob OID.  This means:
    23  
    24  * Use properties "version", "oid", and "size" in that order.
    25  * Separate the property from its value with a single space.
    26  * Oid has a "sha256:" prefix.  No other hashing methods are currently supported
    27  for Git LFS oids.
    28  * Size is in bytes.
    29  
    30  Note: Earlier versions only contained the OID, with a `# comment` above it.
    31  Here's some ruby code to parse older pointer files.
    32  
    33  ```
    34  # data is a string of the content
    35  # last full line contains the oid
    36  return nil unless data.size < 100
    37  lines = data.
    38    strip.      # strip ending whitespace
    39    split("\n") # split by line breaks
    40  
    41  # We look for a comment line, and the phrase `git-media` somewhere
    42  lines[0] =~ /# (.*git-media|external)/ && lines.last
    43  ```
    44  
    45  That code returns the OID, which should be on the last line.  The OID is
    46  generated from the SHA-256 signature of the file's contents.
    47  
    48  ## The Server
    49  
    50  Git LFS needs a URL endpoint to talk to a remote server.  A Git repository
    51  can have different Git LFS endpoints for different remotes.  Here is the list
    52  of rules that Git LFS uses to determine a repository's Git LFS server:
    53  
    54  1. The `lfs.url` string.
    55  2. The `remote.{name}.lfs_url` string.
    56  3. Append `/info/lfs` to the remote URL.  Only works with HTTPS URLs.
    57  
    58  Here's a sample Git config file with the optional remote and Git LFS
    59  configuration options:
    60  
    61  ```
    62  [core]
    63    repositoryformatversion = 0
    64  [lfs]
    65    endpoint = "https://github.com/github/git-lfs.git/info/lfs"
    66  [remote "origin"]
    67    url = https://github.com/github/git-lfs
    68    fetch = +refs/heads/*:refs/remotes/origin/*
    69    lfs = "https://github.com/github/git-lfs.git/info/lfs"
    70  ```
    71  
    72  Git LFS uses `git credential` to fetch credentials for HTTPS requests.  Setup
    73  a credential cache helper to save passwords for future users.
    74  
    75  ## Intercepting Git
    76  
    77  Git LFS uses the `clean` and `smudge` filters to decide which files use it.  The
    78  global filters can be set up with `git lfs init`:
    79  
    80  ```
    81  $ git lfs init
    82  ```
    83  
    84  The `clean` filter runs as files are added to repositories.  Git sends the
    85  content of the file being added as STDIN, and expects the content to write
    86  to Git as STDOUT.
    87  
    88  * Stream binary content from STDIN to a temp file, while calculating its SHA-256
    89  signature.
    90  * Check for the file at `.git/lfs/objects/{OID}`.
    91  * If it does not exist:
    92    * Queue the OID to be uploaded.
    93    * Move the temp file to `.git/lfs/objects/{OID}`.
    94  * Delete the temp file.
    95  * Write the pointer file to STDOUT.
    96  
    97  Note that the `clean` filter does not push the file to the server.  Use the
    98  `git lfs sync` command to do that.
    99  
   100  The `smudge` filter runs as files are being checked out from the Git repository
   101  to the working directory.  Git sends the content of the Git blob as STDIN, and
   102  expects the content to write to the working directory as STDOUT.
   103  
   104  * Read 100 bytes.
   105  * If the content is ASCII and matches the pointer file format:
   106    * Look for the file in `.git/lfs/objects/{OID}`.
   107    * If it's not there, download it from the server.
   108    * Read its contents to STDOUT
   109  * Otherwise, simply pass the STDIN out through STDOUT.
   110  
   111  The `.gitattributes` file controls when the filters run.  Here's a sample file
   112  runs all mp3 and zip files through Git LFS:
   113  
   114  ```
   115  $ cat .gitattributes
   116  *.mp3 filter=lfs -crlf
   117  *.zip filter=lfs -crlf
   118  ```
   119  
   120  Use the `git lfs path` command to view and add to `.gitattributes`.