= git-lfs-checkout(1)

== NAME

git-lfs-checkout - Update working copy with file content if available

== SYNOPSIS

`git lfs checkout` [<glob-pattern>...] +
`git lfs checkout` --to <file> {--base|--ours|--theirs} <conflict-obj-path>

== DESCRIPTION

Try to ensure that the working copy contains file content for Git LFS
objects for the current ref, if the object data is available. Does not
download any content; see git-lfs-fetch(1) for that.

Checkout scans the current ref for all LFS objects that would be
required, then where a file is either missing in the working copy, or
contains placeholder pointer content with the same SHA, the real file
content is written, provided we have it in the local store. Modified
files are never overwritten.

One or more s may be provided as arguments to restrict the set of files
that are updated. Glob patterns are matched as per the format described
in gitignore(5).

When used with `--to` and the working tree is in a conflicted state due
to a merge, this option checks out one of the three stages a conflicting
Git LFS object into a separate file (which can be outside of the work
tree). This can make using diff tools to inspect and resolve merges
easier. A single Git LFS object's file path must be provided in
`<conflict-obj-path>`. If `<file>` already exists, whether as a regular
file, symbolic link, or directory, it will be removed and replaced, unless
it is a non-empty directory or otherwise cannot be deleted.

If the installed Git version is at least 2.42.0,
this command will by default check out Git LFS objects for files
only if they are present in the Git index and if they match a Git LFS
filter attribute from a `.gitattributes` file that is present in either
the index or the current working tree (or, as is always the case, if
they match a Git LFS filter attribute in a local `gitattributes` file
such as `$GIT_DIR/info/attributes`). These constraints do not apply
with prior versions of Git.

In a repository with a partial clone or sparse checkout, it is therefore
advisable to check out all `.gitattributes` files from `HEAD` before
using this command, if Git v2.42.0 or later is installed. Alternatively,
the `GIT_ATTR_SOURCE` environment variable may be set to `HEAD`, which
will cause Git to only read attributes from `.gitattributes` files in
`HEAD` and ignore those in the index or working tree.

In a bare repository, this command has no effect.  In a future version,
this command may exit with an error if it is run in a bare repository.

== OPTIONS

`--base`::
  Check out the merge base of the specified file.
`--ours`::
  Check out our side (that of the current branch) of the
  conflict for the specified file.
`--theirs`::
  Check out their side (that of the other branch) of the
conflict for the specified file.
`--to <path>`::
  If the working tree is in a conflicted state, check out the
  portion of the conflict specified by `--base`, `--ours`, or `--theirs`
  to the given path.

== EXAMPLES

* Checkout all files that are missing or placeholders:

....
$ git lfs checkout
....

* Checkout a specific couple of files:

....
$ git lfs checkout path/to/file1.png path/to.file2.png
....

* Checkout a path with a merge conflict into separate files:

....
# Attempt merge with a branch that has a merge conflict
$ git merge conflicting-branch
CONFLICT (content): Merge conflict in path/to/conflicting/file.dat

# Checkout versions of the conflicting file into temp files
$ git lfs checkout --to ours.dat --ours path/to/conflicting/file.dat
$ git lfs checkout --to theirs.dat --theirs path/to/conflicting/file.dat

# Compare conflicting versions in ours.dat and theirs.dat,
# then resolve conflict (e.g., by choosing one version over
# the other, or creating a new version)

# Cleanup and continue with merge
$ rm ours.dat theirs.dat
$ git add path/to/conflicting/file.dat
$ git merge --continue
....

== SEE ALSO

git-lfs-fetch(1), git-lfs-pull(1), gitattributes(5), gitignore(5).

Part of the git-lfs(1) suite.
