git-lfs/README.md

90 lines
3.4 KiB
Markdown
Raw Normal View History

2015-03-19 19:30:55 +00:00
Git Large File Storage
2015-01-30 17:10:41 +00:00
======
2013-09-22 22:00:52 +00:00
2015-03-24 16:27:18 +00:00
Git LFS is a command line extension and [specification](docs/spec.md) for managing large files with Git. The client is written in Go, with pre-compiled binaries available for Mac, Windows, Linux, and FreeBSD.
2015-03-24 16:27:18 +00:00
## Features
2015-03-24 19:09:06 +00:00
Inherent in the design of Git is the notion that every clone of a repository contains every version of every file. This is a core feature of a distributed version control system. But for some types of projects, this is not reasonable or even practical. Multiple revisions of a large file take up space quickly, slowing down repository operations and making clones, fetches, and pulls unwieldy. The Git LFS overcomes this limitation by storing the metadata for large files in Git and syncing the actual file contents to a configurable [Git LFS server](docs/api.md).
2015-03-24 16:27:18 +00:00
Some of the key features include:
* Tight integration with Git means you don't have to change your workflow after the initial configuration.
* Large files are synced separately to a configurable Git LFS server over HTTPS, so you are not limited in where you push your Git repository.
* Large files are only synced from the server when they are checked out, so your local repository doesn't carry the weight of every version of every file when it is not needed.
* The metatadata stored in Git is extensible for future use. It currently includes a hash of the contents of the file, and the file size so clients can display a progress bar while downloading or opt out of a large download.
* Clients and servers can make use of all the features of HTTPS, such as caching content locally on a CDN, resumable uploads and downloads, or performing requests in parallel for faster transfers.
## Getting Started
Download the [latest client][rel] and run the included install script. The
2015-03-19 19:30:55 +00:00
installer should run `git lfs init` for you, which sets up Git's global
configuration settings for Git LFS.
2015-03-19 19:30:55 +00:00
[rel]: https://github.com/github/git-lfs/releases
### Configuration
2015-03-19 19:30:55 +00:00
Git LFS uses `.gitattributes` files to configure which are managed by Git LFS.
2015-02-07 16:52:50 +00:00
Here is a sample one that saves zips and mp3s:
$ cat .gitattributes
2015-03-19 19:30:55 +00:00
*.mp3 filter=lfs -crlf
*.zip filter=lfs -crlf
2015-03-19 19:30:55 +00:00
Git LFS can help manage the paths:
2015-03-19 19:30:55 +00:00
$ git lfs add "*.mp3"
Adding path *.mp3
2015-03-19 19:30:55 +00:00
$ git lfs add "*.zip"
Adding path *.zip
2015-03-19 19:30:55 +00:00
$ git lfs path
Listing paths
*.mp3 (.gitattributes)
*.zip (.gitattributes)
2015-03-19 19:30:55 +00:00
$ git lfs remove "*.zip"
Removing path *.zip
2015-03-19 19:30:55 +00:00
$ git lfs path
Listing paths
*.mp3 (.gitattributes)
### Pushing commits
Once setup, you're ready to push some commits.
$ git add my.zip
$ git commit -m "add zip"
2015-03-19 19:30:55 +00:00
You can confirm that Git LFS is managing your zip file:
2015-03-19 19:30:55 +00:00
$ git lfs ls-files
my.zip
Once you've made your commits, push your files to the Git remote.
$ git push origin master
Sending my.zip
12.58 MB / 12.58 MB 100.00 %
Counting objects: 2, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 548 bytes | 0 bytes/s, done.
Total 5 (delta 1), reused 0 (delta 0)
2015-03-19 19:30:55 +00:00
To https://github.com/github/git-lfs-test
67fcf6a..47b2002 master -> master
2013-09-22 22:00:52 +00:00
2015-03-19 19:30:55 +00:00
See the [Git LFS overview](https://github.com/github/git-lfs/tree/master/docs) and [man pages](https://github.com/github/git-lfs/tree/master/docs/man).
2015-03-24 16:27:18 +00:00
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for info on working on Git LFS and
sending patches.