2015-04-09 22:45:18 +00:00
|
|
|
# Git Large File Storage [![Build Status](https://travis-ci.org/github/git-lfs.svg?branch=master)](https://travis-ci.org/github/git-lfs)
|
2013-09-22 22:00:52 +00:00
|
|
|
|
2015-04-02 21:13:27 +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
|
2015-06-18 13:59:50 +00:00
|
|
|
binaries available for Mac, Windows, Linux, and FreeBSD. Check out the
|
2015-12-03 03:09:19 +00:00
|
|
|
[Git LFS website][page] for an overview of features.
|
2015-04-08 16:10:26 +00:00
|
|
|
|
2015-06-18 13:59:50 +00:00
|
|
|
[page]: https://git-lfs.github.com/
|
2015-04-08 16:10:26 +00:00
|
|
|
|
2015-02-07 16:51:55 +00:00
|
|
|
## Getting Started
|
|
|
|
|
2015-12-01 23:26:36 +00:00
|
|
|
You can install Git LFS in several different ways, depending on your setup and
|
2015-09-25 19:37:07 +00:00
|
|
|
preferences.
|
|
|
|
|
|
|
|
* Linux users can install Debian or RPM packages from [PackageCloud](https://packagecloud.io/github/git-lfs).
|
|
|
|
* Mac users can install from [Homebrew](https://github.com/Homebrew/homebrew) with `brew install git-lfs`.
|
2015-12-16 00:21:27 +00:00
|
|
|
* Windows users can install from [Chocolatey](https://chocolatey.org/) with `choco install git-lfs.install`.
|
2015-09-25 19:37:07 +00:00
|
|
|
* [Binary packages are available][rel] for Windows, Mac, Linux, and FreeBSD.
|
2015-10-21 15:38:21 +00:00
|
|
|
* You can build it with Go 1.5+. See the [Contributing Guide](./CONTRIBUTING.md) for instructions.
|
2015-09-25 19:37:07 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
[rel]: https://github.com/github/git-lfs/releases
|
|
|
|
|
|
|
|
Note: Git LFS requires Git v1.8.2 or higher.
|
|
|
|
|
|
|
|
One installed, you need to setup the global Git hooks for Git LFS. This only
|
|
|
|
needs to be run once per machine.
|
2015-09-25 19:37:07 +00:00
|
|
|
|
|
|
|
```bash
|
2015-12-03 03:09:19 +00:00
|
|
|
$ git lfs install
|
2015-09-25 19:37:07 +00:00
|
|
|
```
|
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
Now, it's time to add some large files to a repository. The first step is to
|
2015-12-03 03:14:42 +00:00
|
|
|
specify file patterns to store with Git LFS. These file patterns are stored in
|
|
|
|
`.gitattributes`.
|
2015-06-18 13:59:50 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
```bash
|
|
|
|
$ mkdir large-repo
|
|
|
|
$ cd large-repo
|
|
|
|
$ git init
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
# Add all zip files through Git LFS
|
|
|
|
$ git lfs track "*.zip"
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
Now you're ready to push some commits:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
```bash
|
|
|
|
$ git add my.zip
|
|
|
|
$ git commit -m "add zip"
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
You can confirm that Git LFS is managing your zip file:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
```bash
|
|
|
|
$ git lfs ls-files
|
|
|
|
my.zip
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
Once you've made your commits, push your files to the Git remote:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
```bash
|
|
|
|
$ git push origin master
|
|
|
|
Sending my.zip
|
|
|
|
LFS: 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)
|
|
|
|
To https://github.com/github/git-lfs-test
|
|
|
|
67fcf6a..47b2002 master -> master
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
## Need Help?
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
You can get help on specific commands directly:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
```bash
|
|
|
|
$ git lfs help <subcommand>
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
The [official documentation](docs) has command references and specifications for
|
|
|
|
the tool. You can ask questions in the [Git LFS chat room][chat], or [file a new
|
|
|
|
issue][ish]. Be sure to include details about the problem so we can
|
|
|
|
troubleshoot it.
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
1. Include the output of `git lfs env`, which shows how your Git environment
|
|
|
|
is setup.
|
|
|
|
2. Include `GIT_TRACE=1` in any bad Git commands to enable debug messages.
|
|
|
|
3. If the output includes a message like `Errors logged to /path/to/.git/lfs/objects/logs/*.log`,
|
|
|
|
throw the contents in the issue, or as a link to a Gist or paste site.
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
[chat]: https://gitter.im/github/git-lfs
|
|
|
|
[ish]: https://github.com/github/git-lfs/issues
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
## Contributing
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for info on working on Git LFS and
|
|
|
|
sending patches. Related projects are listed on the [Implementations wiki
|
|
|
|
page][impl]. You can also join [the project's chat room][chat].
|
2015-02-07 16:51:55 +00:00
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
[impl]: https://github.com/github/git-lfs/wiki/Implementations
|