2016-10-11 20:53:58 +00:00
|
|
|
|
# Git Large File Storage
|
|
|
|
|
|
2019-12-20 06:57:05 +00:00
|
|
|
|
[![CI status][ci_badge]][ci_url]
|
2019-09-23 16:22:33 +00:00
|
|
|
|
|
2019-12-20 06:57:05 +00:00
|
|
|
|
[ci_badge]: https://github.com/git-lfs/git-lfs/workflows/CI/badge.svg
|
|
|
|
|
[ci_url]: https://github.com/git-lfs/git-lfs/actions?query=workflow%3ACI
|
2013-09-22 22:00:52 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
[Git LFS](https://git-lfs.github.com) is a command line extension and
|
|
|
|
|
[specification](docs/spec.md) for managing large files with Git.
|
2015-04-08 16:10:26 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
The client is written in Go, with pre-compiled binaries available for Mac,
|
|
|
|
|
Windows, Linux, and FreeBSD. Check out the [website](http://git-lfs.github.com)
|
|
|
|
|
for an overview of features.
|
2015-04-08 16:10:26 +00:00
|
|
|
|
|
2015-02-07 16:51:55 +00:00
|
|
|
|
## Getting Started
|
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
### Downloading
|
2017-07-20 14:09:14 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
You can install the Git LFS client in several different ways, depending on your
|
|
|
|
|
setup and preferences.
|
2015-09-25 19:37:07 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
* **Linux users**. Debian and RPM packages are available from
|
2018-04-09 21:49:54 +00:00
|
|
|
|
[PackageCloud](https://packagecloud.io/github/git-lfs/install).
|
2018-03-23 17:04:10 +00:00
|
|
|
|
* **macOS users**. [Homebrew](https://brew.sh) bottles are distributed, and can
|
|
|
|
|
be installed via `brew install git-lfs`.
|
2018-08-31 16:30:26 +00:00
|
|
|
|
* **Windows users**. Git LFS is included in the distribution of
|
|
|
|
|
[Git for Windows](https://gitforwindows.org/). Alternatively, you can
|
2018-08-21 21:53:24 +00:00
|
|
|
|
install a recent version of Git LFS from the [Chocolatey](https://chocolatey.org/) package manager.
|
|
|
|
|
* **Binary packages**. In addition, [binary packages](https://github.com/git-lfs/git-lfs/releases) are
|
|
|
|
|
available for Linux, macOS, Windows, and FreeBSD.
|
|
|
|
|
* **Building from source**. [This repository](https://github.com/git-lfs/git-lfs.git) can also be
|
2018-06-18 23:52:36 +00:00
|
|
|
|
built from source using the latest version of [Go](https://golang.org), and the
|
|
|
|
|
available instructions in our
|
|
|
|
|
[Wiki](https://github.com/git-lfs/git-lfs/wiki/Installation#source).
|
2015-12-03 03:09:19 +00:00
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
### Installing
|
|
|
|
|
|
|
|
|
|
#### From binary
|
|
|
|
|
|
|
|
|
|
The [binary packages](https://github.com/git-lfs/git-lfs/releases) include a script which will:
|
2015-12-03 03:09:19 +00:00
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
- Install Git LFS binaries onto the system `$PATH`
|
|
|
|
|
- Run `git lfs install` to
|
2018-08-21 17:53:14 +00:00
|
|
|
|
perform required global configuration changes.
|
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
```ShellSession
|
2018-08-21 17:53:14 +00:00
|
|
|
|
$ ./install.sh
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
#### From source
|
2018-08-21 17:53:14 +00:00
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
- Place the `git-lfs` binary on your system’s executable `$PATH` or equivalent.
|
2018-08-21 17:53:14 +00:00
|
|
|
|
- Git LFS requires global configuration changes once per-machine. This can be done by
|
2018-03-23 17:04:10 +00:00
|
|
|
|
running:
|
2015-09-25 19:37:07 +00:00
|
|
|
|
|
2018-08-21 21:53:24 +00:00
|
|
|
|
```ShellSession
|
2015-12-03 03:09:19 +00:00
|
|
|
|
$ git lfs install
|
2015-09-25 19:37:07 +00:00
|
|
|
|
```
|
|
|
|
|
|
2020-02-11 20:41:50 +00:00
|
|
|
|
#### Verifying releases
|
|
|
|
|
|
|
|
|
|
Releases are signed with the OpenPGP key of one of the core team members. To
|
|
|
|
|
get these keys, you can run the following command, which will print them to
|
|
|
|
|
standard output:
|
|
|
|
|
|
|
|
|
|
```ShellSession
|
|
|
|
|
$ curl -L https://api.github.com/repos/git-lfs/git-lfs/tarball/core-gpg-keys | tar -Ozxf -
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Once you have the keys, you can download the `sha256sums.asc` file and verify
|
|
|
|
|
the file you want like so:
|
|
|
|
|
|
|
|
|
|
```ShellSession
|
|
|
|
|
$ gpg -d sha256sums.asc | grep git-lfs-linux-amd64-v2.10.0.tar.gz | shasum -a 256 -c
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-21 17:53:14 +00:00
|
|
|
|
## Example Usage
|
|
|
|
|
|
|
|
|
|
To begin using Git LFS within a Git repository that is not already configured
|
|
|
|
|
for Git LFS, you can indicate which files you would like Git LFS to manage.
|
2018-08-21 21:53:24 +00:00
|
|
|
|
This can be done by running the following _from within a Git repository_:
|
2015-06-18 13:59:50 +00:00
|
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```bash
|
2018-03-23 17:04:10 +00:00
|
|
|
|
$ git lfs track "*.psd"
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
(Where `*.psd` is the pattern of filenames that you wish to track. You can read
|
|
|
|
|
more about this pattern syntax
|
2018-04-27 03:19:39 +00:00
|
|
|
|
[here](https://git-scm.com/docs/gitattributes)).
|
2018-03-23 17:04:10 +00:00
|
|
|
|
|
2019-06-06 21:01:56 +00:00
|
|
|
|
> *Note:* the quotation marks surrounding the pattern are important to
|
|
|
|
|
> prevent the glob pattern from being expanded by the shell.
|
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
After any invocation of `git-lfs-track(1)` or `git-lfs-untrack(1)`, you _must
|
|
|
|
|
commit changes to your `.gitattributes` file_. This can be done by running:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```bash
|
2016-04-08 16:33:20 +00:00
|
|
|
|
$ git add .gitattributes
|
2018-03-23 17:04:10 +00:00
|
|
|
|
$ git commit -m "track *.psd files using Git LFS"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You can now interact with your Git repository as usual, and Git LFS will take
|
|
|
|
|
care of managing your large files. For example, changing a file named `my.psd`
|
|
|
|
|
(tracked above via `*.psd`):
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ git add my.psd
|
|
|
|
|
$ git commit -m "add psd"
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2018-03-27 02:13:00 +00:00
|
|
|
|
> _Tip:_ if you have large files already in your repository's history, `git lfs
|
|
|
|
|
> track` will _not_ track them retroactively. To migrate existing large files
|
|
|
|
|
> in your history to use Git LFS, use `git lfs migrate`. For example:
|
|
|
|
|
>
|
|
|
|
|
> ```
|
2019-11-07 22:51:00 +00:00
|
|
|
|
> $ git lfs migrate import --include="*.psd" --everything
|
2018-03-27 02:13:00 +00:00
|
|
|
|
> ```
|
|
|
|
|
>
|
2021-02-01 21:44:22 +00:00
|
|
|
|
> For more information, read [`git-lfs-migrate(1)`](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.1.ronn).
|
2018-03-27 02:13:00 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
You can confirm that Git LFS is managing your PSD file:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```bash
|
|
|
|
|
$ git lfs ls-files
|
2018-03-23 17:04:10 +00:00
|
|
|
|
3c2f7aedfb * my.psd
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```
|
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
|
2021-02-01 21:41:17 +00:00
|
|
|
|
$ git push origin main
|
2018-03-23 17:04:10 +00:00
|
|
|
|
Uploading LFS objects: 100% (1/1), 810 B, 1.2 KB/s
|
|
|
|
|
# ...
|
2016-11-15 17:07:11 +00:00
|
|
|
|
To https://github.com/git-lfs/git-lfs-test
|
2021-02-01 21:41:17 +00:00
|
|
|
|
67fcf6a..47b2002 main -> main
|
2015-12-03 03:09:19 +00:00
|
|
|
|
```
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2018-10-17 19:24:39 +00:00
|
|
|
|
Note: Git LFS requires at least Git 1.8.2 on Linux or 1.8.5 on macOS.
|
2018-03-23 17:04:10 +00:00
|
|
|
|
|
2021-03-08 21:11:57 +00:00
|
|
|
|
### Uninstalling
|
|
|
|
|
|
|
|
|
|
If you've decided that Git LFS isn't right for you, you can convert your
|
|
|
|
|
repository back to a plain Git repository with `git lfs migrate` as well. For
|
|
|
|
|
example:
|
|
|
|
|
|
|
|
|
|
```ShellSession
|
|
|
|
|
$ git lfs migrate export --include="*.psd" --everything
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Note that this will rewrite history and change all of the Git object IDs in your
|
|
|
|
|
repository, just like the import version of this command.
|
|
|
|
|
|
|
|
|
|
If there's some reason that things aren't working out for you, please let us
|
|
|
|
|
know in an issue, and we'll definitely try to help or get it fixed.
|
|
|
|
|
|
2018-02-28 23:38:44 +00:00
|
|
|
|
## Limitations
|
|
|
|
|
|
|
|
|
|
Git LFS maintains a list of currently known limitations, which you can find and
|
|
|
|
|
edit [here](https://github.com/git-lfs/git-lfs/wiki/Limitations).
|
|
|
|
|
|
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
|
2020-09-14 21:30:08 +00:00
|
|
|
|
the tool. There's also a [FAQ](https://github.com/git-lfs/git-lfs/wiki/FAQ) on
|
|
|
|
|
the wiki which answers some common questions.
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2021-03-08 21:28:44 +00:00
|
|
|
|
If you have a question on how to use Git LFS, aren't sure about something, or
|
|
|
|
|
are looking for input from others on tips about best practices or use cases,
|
|
|
|
|
feel free to
|
|
|
|
|
[start a discussion](https://github.com/git-lfs/git-lfs/discussions).
|
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
You can always [open an issue](https://github.com/git-lfs/git-lfs/issues), and
|
|
|
|
|
one of the Core Team members will respond to you. Please be sure to include:
|
2015-02-07 16:51:55 +00:00
|
|
|
|
|
2018-03-23 17:04:10 +00:00
|
|
|
|
1. The output of `git lfs env`, which displays helpful information about your
|
|
|
|
|
Git repository useful in debugging.
|
|
|
|
|
2. Any failed commands re-run with `GIT_TRACE=1` in the environment, which
|
|
|
|
|
displays additional information pertaining to why a command crashed.
|
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
|
2018-03-23 17:04:10 +00:00
|
|
|
|
page](https://github.com/git-lfs/git-lfs/wiki/Implementations).
|
2016-05-18 10:43:42 +00:00
|
|
|
|
|
2020-09-11 22:25:07 +00:00
|
|
|
|
See also [SECURITY.md](SECURITY.md) for info on how to submit reports
|
|
|
|
|
of security vulnerabilities.
|
|
|
|
|
|
2016-02-25 18:01:35 +00:00
|
|
|
|
## Core Team
|
|
|
|
|
|
|
|
|
|
These are the humans that form the Git LFS core team, which runs the project.
|
|
|
|
|
|
|
|
|
|
In alphabetical order:
|
|
|
|
|
|
2020-06-12 16:40:51 +00:00
|
|
|
|
| [@bk2204][bk2204-user] | [@chrisd8088][chrisd8088-user] | [@larsxschneider][larsxschneider-user] |
|
2020-09-11 22:25:07 +00:00
|
|
|
|
| :---: | :---: | :---: |
|
2020-06-12 16:40:51 +00:00
|
|
|
|
| [![][bk2204-img]][bk2204-user] | [![][chrisd8088-img]][chrisd8088-user] | [![][larsxschneider-img]][larsxschneider-user] |
|
2020-09-11 22:25:07 +00:00
|
|
|
|
| [PGP 0223B187][bk2204-pgp] | [PGP 088335A9][chrisd8088-pgp] | [PGP A5795889][larsxschneider-pgp] |
|
2018-03-01 16:50:30 +00:00
|
|
|
|
|
2018-08-31 16:28:22 +00:00
|
|
|
|
[bk2204-img]: https://avatars1.githubusercontent.com/u/497054?s=100&v=4
|
2020-06-12 16:40:51 +00:00
|
|
|
|
[chrisd8088-img]: https://avatars1.githubusercontent.com/u/28857117?s=100&v=4
|
2018-03-01 16:50:30 +00:00
|
|
|
|
[larsxschneider-img]: https://avatars1.githubusercontent.com/u/477434?s=100&v=4
|
2018-08-31 16:28:22 +00:00
|
|
|
|
[bk2204-user]: https://github.com/bk2204
|
2020-06-12 16:40:51 +00:00
|
|
|
|
[chrisd8088-user]: https://github.com/chrisd8088
|
2018-03-01 16:50:30 +00:00
|
|
|
|
[larsxschneider-user]: https://github.com/larsxschneider
|
2020-09-11 22:25:07 +00:00
|
|
|
|
[bk2204-pgp]: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x88ace9b29196305ba9947552f1ba225c0223b187
|
|
|
|
|
[chrisd8088-pgp]: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x09b4bf756670b76d63515717506c7945088335a9
|
|
|
|
|
[larsxschneider-pgp]: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xaa3b3450295830d2de6db90caba67be5a5795889
|
2018-03-01 16:50:30 +00:00
|
|
|
|
|
|
|
|
|
### Alumni
|
|
|
|
|
|
|
|
|
|
These are the humans that have in the past formed the Git LFS core team, or
|
|
|
|
|
have otherwise contributed a significant amount to the project. Git LFS would
|
|
|
|
|
not be possible without them.
|
|
|
|
|
|
|
|
|
|
In alphabetical order:
|
|
|
|
|
|
2019-10-28 21:15:34 +00:00
|
|
|
|
| [@andyneff][andyneff-user] | [@PastelMobileSuit][PastelMobileSuit-user] | [@rubyist][rubyist-user] | [@sinbad][sinbad-user] | [@technoweenie][technoweenie-user] | [@ttaylorr][ttaylorr-user] |
|
2020-09-11 22:25:07 +00:00
|
|
|
|
| :---: | :---: | :---: | :---: | :---: | :---: |
|
2019-10-28 21:15:34 +00:00
|
|
|
|
| [![][andyneff-img]][andyneff-user] | [![][PastelMobileSuit-img]][PastelMobileSuit-user] | [![][rubyist-img]][rubyist-user] | [![][sinbad-img]][sinbad-user] | [![][technoweenie-img]][technoweenie-user] | [![][ttaylorr-img]][ttaylorr-user] |
|
2018-03-01 16:50:30 +00:00
|
|
|
|
|
|
|
|
|
[andyneff-img]: https://avatars1.githubusercontent.com/u/7596961?v=3&s=100
|
2019-10-28 21:15:34 +00:00
|
|
|
|
[PastelMobileSuit-img]: https://avatars2.githubusercontent.com/u/37254014?s=100&v=4
|
2018-03-01 16:50:30 +00:00
|
|
|
|
[rubyist-img]: https://avatars1.githubusercontent.com/u/143?v=3&s=100
|
|
|
|
|
[sinbad-img]: https://avatars1.githubusercontent.com/u/142735?v=3&s=100
|
|
|
|
|
[technoweenie-img]: https://avatars3.githubusercontent.com/u/21?v=3&s=100
|
2019-07-26 17:52:30 +00:00
|
|
|
|
[ttaylorr-img]: https://avatars2.githubusercontent.com/u/443245?s=100&v=4
|
2018-03-01 16:50:30 +00:00
|
|
|
|
[andyneff-user]: https://github.com/andyneff
|
2019-10-28 21:15:34 +00:00
|
|
|
|
[PastelMobileSuit-user]: https://github.com/PastelMobileSuit
|
2018-03-01 16:50:30 +00:00
|
|
|
|
[sinbad-user]: https://github.com/sinbad
|
|
|
|
|
[rubyist-user]: https://github.com/rubyist
|
|
|
|
|
[technoweenie-user]: https://github.com/technoweenie
|
2019-07-26 17:52:30 +00:00
|
|
|
|
[ttaylorr-user]: https://github.com/ttaylorr
|