1GIT-LFS-FAQ(7) GIT-LFS-FAQ(7)
2
6 git-lfs-faq - FAQ for Git LFS
7
9 Does Git LFS provide a way to track files by size?
10 No, it doesn’t. Unfortunately, Git itself doesn’t specify a way to
11 make .gitattributes patterns apply to files of a certain size and
12 we rely on the .gitattributes file to specify which files are
13 tracked by Git LFS.
14 You can use the --above option to git lfs migrate import to migrate
16 all files that at the specified time are larger than a certain
17 size. However, if your files change to be smaller or larger in the
18 future, or you add more files in the future that are larger than
19 the limit you specified, you will have to track them manually.
20 For these reasons, we recommend using patterns rather than --above.
22 Why doesn’t Git LFS handle files larger than 4 GiB on Windows?
24 Git LFS itself handles these files just fine. However, Git LFS is
25 usually invoked by Git, and until Git 2.34, Git itself on Windows
26 didn’t handle files using smudge and clean filters (like Git LFS)
27 that are larger than 4 GiB. So you can update Git for Windows to
28 2.34 to natively support these file sizes.
29 On older versions, set GIT_LFS_SKIP_SMUDGE to 1 and run git lfs
31 pull to pull down the LFS files. This bypasses Git’s smudging
32 functionality and therefore avoids its limitations.
33 Why do I end up with small text files in my working tree instead of my
35 files?
36 Git LFS stores small text files called pointer files in the
37 repository instead of your large files, which it stores elsewhere.
38 These pointer files usually start with the line version
39 https://git-lfs.github.com/spec/v1.
40 Normally, if you’ve run git lfs install at least once for your user
42 account on the system, then Git LFS will be automatically invoked
43 by Git when you check out files or clone a repository and this
44 won’t happen. However, if you haven’t, or you’ve explicitly chosen
45 to skip that behaviour by using the --skip-smudge option of git lfs
46 install, then you may need to use git lfs pull to replace the
47 pointer files in your working tree with large files.
48 Why do I end up with some of my working tree files constantly showing
50 as modified?
51 This can happen if someone made a commit to a file that’s tracked
52 by Git LFS but didn’t have Git LFS properly set up on their system.
53 The objects that were checked into the repository are Git objects,
54 not the pointers to Git LFS objects, and when Git checks these
55 files out, it shows them as modified.
56 There are also several other possible ways to encounter this
58 problem, such as an incomplete migration of your repository. For
59 example, you should not use git lfs track to track patterns that
60 are already in your repository without running git add
61 --renormalize ., since that can lead to this problem.
62 Users frequently find that this cannot be changed by doing git
64 reset --hard or other techniques because Git then checks the files
65 out and marks them as modified again. The best way to solve this
66 problem is by fixing the files and the committing the change, which
67 you can do with the following on an otherwise clean tree:
68 $ git add --renormalize .
70 $ git commit -m "Fix broken LFS files"
71 This requires that every branch you want to fix have this done to
73 it.
74 To prevent this from reoccurring in the future, make sure that
76 everyone working with large files on a project has run git lfs
77 install at least once. The command git lfs fsck --pointers
78 BASE..HEAD (with suitable values of BASE and HEAD) may be used in
79 your CI system to verify that nobody is introducing such problems.
80 How do I track files that are already in a repository?
82 If you want to track files that already exist in a repository, you
83 need to do two things. First, you need to use git lfs track (or a
84 manual modification of .gitattributes) to mark the files as LFS
85 files. Then, you need to run git add --renormalize . and commit the
86 changes to the repository.
87 If you skip this second step, then you’ll end up with files that
89 are marked as LFS files but are stored as Git files, which can lead
90 to files which are always modified, as outlined in the FAQ entry
91 above. Note also that this doesn’t change large files in your
92 history. To do that, use git lfs migrate import --everything
93 instead, as specified in one of the entries below.
94 How do I enable git diff to work on LFS files?
96 You can run git config diff.lfs.textconv cat, which will produce
97 normal diffs if your files are text files.
98 How do I enable git diff to work on LFS files based on extension or
100 path?
101 If the above solution is too broad, each entry in the
102 .gitattributes file can be customized by creating a custom global
103 converter:
104 $ git config --global diff.lfstext.textconv cat
106 Any given .gitattributes entry for large text files can be
108 customized to use this global text converter (e.g., patch files),
109 whereas binary formats can continue to use the conventional lfs
110 diff tool, like so:
111 $ cat .gitattributes
113 ....
114 *.bin filter=lfs diff=lfs merge=lfs -text
115 *.patch filter=lfs diff=lfstext merge=lfs -text
116 ....
117 Be advised that all developers sharing this repo with such a
119 modified .gitattributes file must have similarly configured the
120 lfstext text converter, whether globally or on a per repository
121 basis.
122 How do I convert from using Git LFS to a plain Git repository?
124 If you’d like to stop using Git LFS and switch back to storing your
125 large files in the plain Git format, you can do so with git lfs
126 migrate export --everything. Note that you will need to provide an
127 appropriate --include option to match all the patterns that you
128 currently have tracked in any ref.
129 This also rewrites history, so the Git object IDs of many, if not
131 all, of your objects will change.
132 I’m using Git LFS, but I still see GitHub’s large file error. How do I
134 fix this?
135 GitHub rejects large files anywhere in the history of your
136 repository, not just in the latest commit. If you’re still seeing
137 this message, then you have some large files somewhere in your
138 history, even if in the latest commits you’ve moved them to Git
139 LFS.
140 To fix this, you can use git lfs migrate import --everything with
142 an appropriate --include argument. For example, if you wanted to
143 move your .jpg and .png files into Git LFS, you can do that with
144 git lfs migrate import --everything --include="*.jpg,*.png". More
145 complicated patterns are possible: run git help gitattributes for
146 more information on valid patterns. Note that if you’re specifying
147 directories, using slashes is mandatory: backslashes are not
148 allowed as path separators.
149 I’m using Jenkins and git lfs install fails due to an invalid hook
151 path. What do I do?
152 Recent versions of Jenkins have set core.hooksPath to various
153 values, notably NUL: on Windows, with the goal of disabling hooks.
154 This is not a valid path on Windows, nor a valid value for this
155 configuration option, so when git lfs install runs and Git LFS
156 attempts to install hooks, the operation fails.
157 The easiest way to solve this problem is by using the --skip-repo
159 option to git lfs install, which skips the installation of the
160 hooks. Despite the name, it can be successfully combined with
161 --local if you need that option.
162 Note that this prevents things like git push from pushing LFS
164 objects and locked files from being read only, since those are
165 implemented by hooks. If you need that functionality, you should
166 review the Jenkins documentation about how to properly configure
167 the environment in such a situation so that hooks can be used.
168 Why are LFS files not included when I archive a subdirectory?
170 When you run git archive with only a subdirectory, such as git
171 archive HEAD:src, Git resolves the revision (in this case,
172 HEAD:src) to a tree, and only processes items in that tree. Because
173 the .gitattributes file is typically only in the root of the
174 repository, Git doesn’t even see that file, which controls whether
175 files are considered LFS files, and hence doesn’t consider any of
176 the files in the directory as LFS files, and thus doesn’t invoke
177 Git LFS at all.
178 Since Git LFS doesn’t even get invoked in this case, there’s no way
180 to change how this works. If you just want to include the single
181 subdirectory without stripping the prefix, you can do this: git
182 archive -o archive.tar.gz --prefix=archive/ HEAD src. If you do
183 want to strip the subdirectory name (src) in this case, one option
184 if you have the libarchive tar (available on Windows and macOS as
185 tar, and usually on Linux as bsdtar) is to do something like this
186 script:
187 #!/bin/sh
189 # With trailing slash.
191 ARCHIVE_PREFIX="archive/"
192 # Without trailing slash.
193 SOURCE_PREFIX="src"
194 # Without directory or file components.
195 REVISION="HEAD"
196 temp=$(mktemp -d)
198 git archive --prefix="$ARCHIVE_PREFIX" "$REVISION" "$SOURCE_PREFIX" | bsdtar -C "$temp" -xf -
200 bsdtar -s "!^\./!$ARCHIVE_PREFIX!" --format=pax -czf archive.tar.gz -C "$temp/$ARCHIVE_PREFIX$SOURCE_PREFIX" .
201 rm -fr "$temp"
202
204 git-config(1), git-lfs-install(1), gitattributes(5), gitignore(5).
205 Part of the git-lfs(1) suite.
207 GIT-LFS-FAQ(7)