This topic describes usage notes for Git Large File Storage (LFS) and provides solutions for common issues.
Errors caused by outdated versions
Outdated versions of Git-related software can prevent Git LFS from working correctly. For example, the batch API might return an error, or you might encounter HTTP call exceptions. These issues often occur because the default versions of software installed on the Windows operating system are outdated. If you encounter such problems, upgrade your local git and git-lfs to the latest versions. This usually resolves the issue. The download links for these tools are listed below:
Failure to pull files completely because git-lfs is not installed
To pull a code repository that contains Git LFS files, you must install git-lfs in your environment. For more information, see Download and install Git LFS.
Examples:
Scenario 1: User A successfully pushes several Git LFS files to the remote repository. User B pulls the repository without having
git-lfsinstalled in their environment. As a result, the pulled files contain only Git LFS pointer information (version, oid, and size), not the actual file content.Scenario 2: User A successfully pushes several Git LFS files that are required for a CI/CD pipeline. The build or test fails because
git-lfsis not installed in the CI/CD runtime environment. As a result, the process pulls pointer files instead of the actual files.
In both scenarios, you must install git-lfs on the local or build machine. After installation, you can use standard Git commands to pull the complete files from the server.
How to migrate large files from historical commits to Git LFS
If a Git repository already contains large files in its commit history, the git lfs track command does not track them retroactively. This command applies only to new commits. To migrate large files from the commit history to Git LFS, you must use the git lfs migrate command.
To demonstrate how to migrate files with the `.bigfile` extension from historical commits, first untrack the pattern:
$git lfs untrack "*.bigfile"
Untracking "*.bigfile"Next, add several `.bigfile` files of different sizes. Then, run git add and git commit, and view the commit information:
$git log -p
commit 1ca6e34006c6c1206563e8900d17c1503d9b4dce (HEAD -> test, origin/test)
Author: dyroneteng <tenglong***@alibaba-inc.com>
Date: Thu Sep 17 14:09:24 2020 +0800
old non LFS files
diff --git a/.gitattributes b/.gitattributes
index c441ad2..e69de29 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1 +0,0 @@
-*.bigfile filter=lfs diff=lfs merge=lfs -text
diff --git a/10m.bigfile b/10m.bigfile
new file mode 100644
index 0000000..6c5d403
Binary files /dev/null and b/10m.bigfile differ
diff --git a/11m.bigfile b/11m.bigfile
new file mode 100644
index 0000000..15ae5f2
Binary files /dev/null and b/11m.bigfile differ
diff --git a/12m.bigfile b/12m.bigfile
new file mode 100644
index 0000000..202d95c
Binary files /dev/null and b/12m.bigfile differ
diff --git a/13m.bigfile b/13m.bigfile
new file mode 100644
index 0000000..5b02d1f
Binary files /dev/null and b/13m.bigfile differ
diff --git a/14m.bigfile b/14m.bigfile
new file mode 100644
index 0000000..ad3b355
Binary files /dev/null and b/14m.bigfile differ
diff --git a/15m.bigfile b/15m.bigfile
new file mode 100644
index 0000000..a8510df
Binary files /dev/null and b/15m.bigfile differIn commit 1ca6e34006c6c1206563e8900d17c1503d9b4dce, you can see that the file is no longer tracked by LFS. This is because the diff for bigfile is a binary file, not a pointer file.
Next, run git lfs migrate info and specify the branch name as a parameter to view the Git LFS information for that branch:
$git lfs migrate info --include-ref=refs/heads/test
migrate: Sorting commits: ..., done.
migrate: Examining commits: 100% (3/3), done.
*.bigfile 79 MB 7/7 files(s) 100%
*.gitattributes 46 B 1/2 files(s) 50%To perform the migration, run git lfs migrate import. Specify the branch name with the --include-ref parameter and the file pattern with the --include parameter:
$git lfs migrate import --include-ref=/refs/heads/test --include="*.bigfile"
migrate: Sorting commits: ..., done.
migrate: Rewriting commits: 100% (3/3), done.
master 8032589f47a748171e84da94ce6440fe139e99f9 -> 8032589f47a748171e84da94ce6440fe139e99f9
test 1ca6e34006c6c1206563e8900d17c1503d9b4dce -> 7b1fbac772434d084b4681538602cdf69bf3d8ac
migrate: Updating refs: ..., done.
migrate: checkout: ..., done.After you run the migration command, the standard output shows that the master branch has not changed because it was not specified for migration. The specified test branch has been updated to a new commit, 7b1fbac772434d084b4681538602cdf69bf3d8ac:
$git show 7b1fbac772434d084b4681538602cdf69bf3d8ac
commit 7b1fbac772434d084b4681538602cdf69bf3d8ac (HEAD -> test)
Author: dyroneteng <tenglong***@alibaba-inc.com>
Date: Thu Sep 17 14:09:24 2020 +0800
old non LFS files
diff --git a/10m.bigfile b/10m.bigfile
new file mode 100644
index 0000000..f252459
--- /dev/null
+++ b/10m.bigfile
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e5b844cc57f57094ea4585e235f36c78c1cd222262bb89d53c94dcb4d6b3e55d
+size 10485760
### ...
### ...
### ...
### Omitted outputIn the overwritten commit 7b1fbac772434d084b4681538602cdf69bf3d8ac, the large file is now a Git LFS pointer file. This is different from the original commit 1ca6e34006c6c1206563e8900d17c1503d9b4dce, which contained the binary file. Finally, to apply the changes to the remote repository, you must force push the changes. Run the following command:
git push --forceDo not migrate all objects in a repository to Git LFS at once. This can cause timeouts or other unexpected issues. We recommend migrating one branch at a time using the
--include-refparameter.Back up the Git repository locally before you migrate to Git LFS. If the migration fails, you can restore the repository from the backup.
For more information about how to use
git-lfs-migrate, see the git-lfs-migrate tool documentation.For detailed migration guides covering more scenarios, see LFS Migration Guide.