skip to content

With Git LFS, what do `git lfs install` and `git lfs track "*.psd"` each set up, and what does the resulting .gitattributes line mean?

level: juniorimportance: should knowfreq 42%

answer

  1. once per user, once per repository
  2. global config against committed file
  3. four attributes on one line
  4. filter, diff, merge, minus text
  5. commit the .gitattributes file

basics

~20 s

git lfs install configures the lfs clean, smudge and process filters (globally by default) and installs Git LFS's hooks; git lfs track writes a filter=lfs diff=lfs merge=lfs -text line into .gitattributes, which must be committed.

solid answer

~40 s

`git lfs install` is per user: it sets `filter.lfs.clean`, `filter.lfs.smudge` and `filter.lfs.process` in the global Git config (only if they are not already set; `--force` overwrites, `--local` or `--system` change the scope) and, inside a repository, installs the `pre-push` hook plus the hooks that keep lockable files read-only. `git lfs track "*.psd"` is per repository: it appends `*.psd filter=lfs diff=lfs merge=lfs -text` to `.gitattributes`. `filter=lfs` routes matching paths through the clean and smudge filters, `diff=lfs` and `merge=lfs` name Git LFS's diff and merge drivers, and `-text` stops Git from treating the content as text for line-ending conversion. The line only takes effect for teammates once `.gitattributes` is committed and pushed.

code

bash · 10 lines
bash
$ git lfs install
Git LFS initialized.
$ git lfs track "*.psd" "*.fbx"
Tracking "*.psd"
Tracking "*.fbx"
$ cat .gitattributes
*.psd filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
$ git add .gitattributes
$ git commit -m "Track PSD and FBX with Git LFS"

go deeper

for a junior

Recall the split: install once per user for the filters and hooks, track per repository for the pattern, then commit .gitattributes.

for a middle

Explain each attribute on the tracked line, which config keys install writes and at which scope, and what --lockable and --filename add.

for a senior

Spot setup failures: an uncommitted .gitattributes, a teammate without the filters, a hooks path that blocked hook installation, or a case mismatch in the pattern.

for a principal

Decide where tracking rules live and how they are reviewed, so a repository's .gitattributes stays the single, agreed source of what goes to LFS.

## Two commands, two scopes Getting Git LFS working on a team takes two different setup steps, and confusing them is the most common reason a repository ends up half-converted. | Command | Scope | What it writes | Shared with the team? | |---|---|---|---| | `git lfs install` | Once per user (or system, or repository) | The `lfs` filter settings in Git config, and Git LFS's hooks in the current repository | No — every person and machine runs it | | `git lfs track "<pattern>"` | Once per repository, per pattern | A line in `.gitattributes` | Yes — once `.gitattributes` is committed | ## What `git lfs install` sets up Run without options, `git lfs install` does two things: 1. It sets up the **clean and smudge filters under the name `lfs`** in the global Git config (`~/.gitconfig`): the keys `filter.lfs.clean`, `filter.lfs.smudge` and `filter.lfs.process`. It only writes them if they are not already set; `--force` overwrites existing values. `--local` writes them to the repository's own config, `--worktree` to the current working tree's config, `--system` to the system config, and `--file=<file>` to a file you name. 2. If run inside a repository, it installs Git LFS's **hooks** there: the `pre-push` hook that uploads LFS objects before Git pushes commits, and the post-checkout, post-commit and post-merge hooks that keep **lockable** files read-only unless you hold their lock. If `core.hooksPath` is configured, the hooks go to that directory. Options worth recognising: - `--skip-smudge` configures the filters so that clones and pulls leave pointers in place; files are then fetched with `git lfs pull`. - `--skip-repo` installs the filters but no hooks — useful when a tool has set an unusable hooks path, at the cost of pushes not uploading objects and lockable files not being made read-only. - `--manual` prints instructions for adding Git LFS to existing hooks by hand, for when those hooks make `install` fail. Install prints `Git LFS initialized.` when it succeeds. ## What `git lfs track` writes `git lfs track "*.psd"` appends one line to `.gitattributes` and prints `Tracking "*.psd"`: ```bash $ cat .gitattributes *.psd filter=lfs diff=lfs merge=lfs -text *.fbx filter=lfs diff=lfs merge=lfs -text ``` Each attribute has a separate job: - **`filter=lfs`** — the one that matters most. It tells Git to run the filter configured as `filter.lfs.*` for matching paths: clean on add, smudge on checkout. - **`diff=lfs`** — names a diff driver called `lfs` for these paths, so diff behaviour can be configured separately for LFS content. - **`merge=lfs`** — names a merge driver called `lfs`. Git LFS ships a `git lfs merge-driver` command but does **not** enable it by default, because LFS holds both text and binary files; teams with text files in LFS configure it deliberately. - **`-text`** — unsets the `text` attribute so Git applies no line-ending conversion to the content. Run with no arguments, `git lfs track` lists the patterns currently tracked; `git lfs untrack "<pattern>"` removes one. ## Options on `track` - `--lockable` appends the `lockable` attribute: matching files should be locked before editing and are read-only in the working copy when not locked. `--not-lockable` removes it. - `--filename` treats the argument as a literal file name, escaping `*`, `?`, `[` and `]`, so `git lfs track --filename "project [1].psd"` matches exactly that file. - `--dry-run` logs what would change without writing; `--json` prints the tracked patterns for tools. - `--no-modify-attrs` writes nothing to `.gitattributes`; it only makes matching files stat-dirty so Git re-indexes them. ## Pitfalls that show up on real teams - **Forgetting to commit `.gitattributes`.** Tracking lives in that file. Until it is committed and pushed, teammates' Git has no reason to call Git LFS and their PSDs go into history as plain blobs. - **A teammate who never ran `install`.** The attribute names a filter their config does not define, so Git writes and reads blobs unfiltered: they check out pointer text, and anything they add goes in as a plain blob. - **Case.** Attribute patterns are case-sensitive, so `*.psd` does not match `Hero.PSD` on a case-sensitive file system. The Git LFS FAQ recommends bracket globs such as `*.[pP][sS][dD]` for repositories shared across operating systems. - **Expecting `track` to fix the past.** It only affects content added from now on; files committed earlier remain full blobs in history until they are migrated.

  • What do `git lfs track --lockable` and `git lfs track --filename` change in the line that is written?
    `--lockable` appends the `lockable` attribute, marking matching files as ones to lock before editing; Git LFS keeps them read-only in the working copy when you do not hold the lock. `--filename` treats the argument as a literal file name, escaping glob characters, so `git lfs track --filename "project [1].psd"` matches that one file rather than a bracket pattern.
  • Why might `*.psd` in .gitattributes miss a file called `Hero.PSD`?
    Git's attribute pattern matching is case-sensitive. A file committed with an uppercase extension does not match `*.psd` on a case-sensitive file system, so Git LFS is never invoked for it there. The Git LFS FAQ recommends bracket globs such as `*.[pP][sS][dD]` for repositories shared across operating systems.
  • When would you run `git lfs install --skip-repo` or `--skip-smudge`?
    `--skip-repo` installs the filters but no hooks, for environments where the hooks path is unusable; without the hooks, pushes do not upload LFS objects and lockable files are not made read-only. `--skip-smudge` configures the filters so checkouts leave pointers in place, and files are fetched later with `git lfs pull`.

  • git lfs track uploads the matching files to the LFS server immediately.
  • git lfs install is committed to the repository, so teammates get it automatically.
  • Teammates get LFS tracking even if .gitattributes is never committed.
  • The -text attribute marks the file as binary for every Git operation.
  • git lfs track by itself converts files already committed to pointers in history.