Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GIT-LFS-MIGRATE(1)					    GIT-LFS-MIGRATE(1)

NAME
       git-lfs-migrate - Migrate history to or from git-lfs

SYNOPSIS
       git lfs migrate mode [options] [--] [branch ...]

MODES
       o   info	Show information about repository size.

       o   import Convert large	Git objects to LFS pointers.

       o   export Convert LFS pointers to large	Git objects.

OPTIONS
       -I paths	--include=paths
	      See INCLUDE AND EXCLUDE.

       -X paths	--exclude=paths
	      See INCLUDE AND EXCLUDE.

       --include-ref=refname
	      See [INCLUDE AND EXCLUDE (REFS)].

       --exclude-ref=refname
	      See [INCLUDE AND EXCLUDE (REFS)].

       --skip-fetch
	      Assumes that the known set of remote references is complete, and
	      should not be refreshed when determining the set of  "un-pushed"
	      commits  to  migrate.  Has  no  effect  when combined with --in-
	      clude-ref	or --exclude-ref.

       --everything
	      See [INCLUDE AND EXCLUDE (REFS)].

	      Note: Git	refs are "case-sensitive" on all platforms in  "packed
	      from"  (see  git-pack-refs(1)).  On "case-insensitive" file sys-
	      tems, e.g. NTFS on Windows or default APFS on macOS, git-lfs-mi-
	      grate(1)	would  only  migrate the first ref if two or more refs
	      are equal	except for upper/lower case letters.

       --yes  Assume a yes answer to any  prompts,  permitting	noninteractive
	      use.  Currently,	the only such prompt is	the one	asking whether
	      to overwrite (destroy) any working copy changes. Thus,  specify-
	      ing this option may cause	data loss if you are not careful.

       [branch ...]
	      Migrate	only  the  set	of  branches  listed.  If  not	given,
	      git-lfs-migrate(1)  will	migrate	 the  currently	 checked   out
	      branch.

	      References beginning with	'^' will be excluded, whereas branches
	      that do not begin	with '^' will be included.

	      If any of	--include-ref or --exclude-ref are given, the  checked
	      out  branch  will	not be appended, but branches given explicitly
	      will be appended.

   INFO
       The 'info' mode has these additional options:

       o   --above=<size> Only count files whose individual filesize is	 above
	   the	given size. 'size' may be specified as a number	of bytes, or a
	   number followed by a	storage	unit, e.g., "1b", "20  MB",  "3	 TiB",
	   etc.

	   If  a  set of files sharing a common	extension has no files in that
	   set whose individual	size is	above the given	--above	 no  files  no
	   entry for that set will be shown.

       o   --top=<n> Only include the top 'n' entries, ordered by how many to-
	   tal files match the given pathspec. Default:	top 5 entries.

       o   --unit=<unit> Format	the number of bytes in each entry as  a	 quan-
	   tity	of the storage unit provided. Valid units include:

	   * b,	kib, mib, gib, tib, pib	- for IEC storage units
	   * b,	kb, mb,	gb, tb,	pb - for SI storage units

       If  a --unit is not specified, the largest unit that can	fit the	number
       of counted bytes	as a whole number quantity is chosen.

   IMPORT
       The 'import' mode migrates large	objects	present	in the Git history  to
       pointer files tracked and stored	with Git LFS. It supports all the core
       'migrate' options and these additional ones:

       o   --verbose Print the commit oid and filename of  migrated  files  to
	   STDOUT.

       o   --above=<size>  Only	 migrate  files	 whose	individual filesize is
	   above the given size. 'size'	may be specified as a number of	bytes,
	   or  a  number  followed  by a storage unit, e.g., "1b", "20 MB", "3
	   TiB", etc.

       o   --object-map=<path> Write to	'path' a file with the mapping of each
	   rewritten  commits.	The  file  format  is  CSV  with this pattern:
	   OLD-SHA,NEW-SHA

       o   --no-rewrite	Migrate	large objects to Git LFS in a new commit with-
	   out	rewriting  git	history.  Please note that when	this option is
	   used, the migrate import command will expect	a  different  argument
	   list,  specialized  options will become available, and the core mi-
	   grate options will be ignored. See [IMPORT (NO REWRITE)].

       o   --fixup Infer --include and --exclude filters on a per-commit basis
	   based  on  the  .gitattributes  files in a repository. In practice,
	   this	option imports any filepaths which should be  tracked  by  Git
	   LFS	according  to  the  repository's  .gitattributes  file(s), but
	   aren't already pointers. This option	is incompatible	 with  explic-
	   itly	given --include, --exclude filters.

       If --no-rewrite is not provided and --include or	--exclude (-I, -X, re-
       spectively) are given, the .gitattributes will be modified  to  include
       any new filepath	patterns as given by those flags.

       If  --no-rewrite	 is not	provided and neither of	those flags are	given,
       the  gitattributes  will	 be  incrementally  modified  to  include  new
       filepath	extensions as they are rewritten in history.

   IMPORT (NO REWRITE)
       The  import  mode  has  a  special sub-mode enabled by the --no-rewrite
       flag. This sub-mode will	migrate	large objects to pointers  as  in  the
       base  import mode, but will do so in a new commit without rewriting Git
       history.	When using this	sub-mode, the base migrate  options,  such  as
       --include-ref, will be ignored, as will those for the base import mode.
       The migrate command will	also take a different argument list. As	a  re-
       sult  of	 these	changes, --no-rewrite will only	operate	on the current
       branch -	any other interested branches must have	the  generated	commit
       merged in.

       The --no-rewrite	sub-mode supports the following	options	and arguments:

       o   -m <message>	--message=<message> Specifies a	commit message for the
	   newly created commit.

       o   [file ...] The list of files	to import. These files must be tracked
	   by patterns specified in the	gitattributes.

       If --message is given, the new commit will be created with the provided
       message.	If no message is given,	a commit  message  will	 be  generated
       based on	the file arguments.

   EXPORT
       The  'export'  mode  migrates  Git LFS pointer files present in the Git
       history out of Git LFS, converting them into their corresponding	object
       files.  It supports all the core	'migrate' options and these additional
       ones:

       o   --verbose Print the commit oid and filename of  migrated  files  to
	   STDOUT.

       o   --object-map=<path> Write to	'path' a file with the mapping of each
	   rewritten commit.  The  file	 format	 is  CSV  with	this  pattern:
	   OLD-SHA,NEW-SHA

       o   --remote=<git-remote>   Download  LFS  objects  from	 the  provided
	   'git-remote'	during the export. If not provided, defaults to	 'ori-
	   gin'.

       The 'export' mode requires at minimum a pattern provided	with the --in-
       clude argument to specify which files to	 export.  Files	 matching  the
       --include  patterns  will be removed from Git LFS, while	files matching
       the --exclude patterns will retain their	Git  LFS  status.  The	export
       command	will  modify the .gitattributes	to set/unset any filepath pat-
       terns as	given by those flags.

INCLUDE	AND EXCLUDE
       You can configure Git LFS to only migrate tree entries  whose  pathspec
       matches the include glob	and does not match the exclude glob, to	reduce
       total migration time or to only migrate part of your repo. Specify mul-
       tiple patterns using the	comma as the delimiter.

       Pattern matching	is done	as given to be functionally equivalent to pat-
       tern matching as	in .gitattributes.

INCLUDE	AND EXCLUDE (REFS)
       You can configure Git LFS to only migrate commits reachable  by	refer-
       ences include by	--include-ref and not reachable	by --exclude-ref.

		   D---E---F
		  /	    \
	     A---B------C    refs/heads/my-feature
	      \		 \
	       \	  refs/heads/master
		\
		 refs/remotes/origin/master

       In the above configuration, the following commits are reachable by each
       ref:

	   refs/heads/master:	      C, B, A
	   refs/heads/my-feature:     F, E, D, B, A
	   refs/remote/origin/master: A

       The following configuration:

	     --include-ref=refs/heads/my-feature
	     --include-ref=refs/heads/master
	     --exclude-ref=refs/remotes/origin/master

       Would, therefore, include commits: F, E,	D, C, B, but exclude commit A.

       The presence of flag --everything indicates that	all local  and	remote
       references should be migrated.

EXAMPLES
   Migrate unpushed commits
       The  migrate command's most common use case is to convert large git ob-
       jects to	LFS before pushing your	commits. By  default,  it  only	 scans
       commits	that  don't  exist on any remote, so long as the repository is
       non-bare.

       First, run git lfs migrate info to list the file	types  taking  up  the
       most space in your repository.

	   $ git lfs migrate info
	   migrate: Fetching remote refs: ..., done
	   migrate: Sorting commits: ..., done
	   migrate: Examining commits: 100% (1/1), done
	   *.mp3   284 MB    1/1 files(s)  100%
	   *.pdf   42 MB     8/8 files(s)  100%
	   *.psd   9.8 MB  15/15 files(s)  100%
	   *.ipynb 6.9 MB    6/6 files(s)  100%
	   *.csv   5.8 MB    2/2 files(s)  100%

       Now,  you  can run git lfs migrate import to convert some file types to
       LFS:

	   $ git lfs migrate import --include="*.mp3,*.psd"
	   migrate: Fetching remote refs: ..., done
	   migrate: Sorting commits: ..., done
	   migrate: Rewriting commits: 100% (1/1), done
	     master    d2b959babd099fe70da1c1512e2475e8a24de163	-> 136e706bf1ae79643915c134e17a6c933fd53c61
	   migrate: Updating refs: ...,	done

   Migrate local history
       You can also migrate the	entire history of your repository:

	   # Check for large files in your local master	branch
	   $ git lfs migrate info --include-ref=master

	   # Check for large files in every branch
	   $ git lfs migrate info --everything

       The same	flags will work	in import mode:

	   # Convert all zip files in your master branch
	   $ git lfs migrate import --include-ref=master --include="*.zip"

	   # Convert all zip files in every local branch
	   $ git lfs migrate import --everything --include="*.zip"

	   # Convert all files over 100K in every local	branch
	   $ git lfs migrate import --everything --above=100Kb

       Note: This will require a force push to any existing Git	remotes.

   Migrate without rewriting local history
       You can also migrate files without modifying the	 existing  history  of
       your  repository. Note that in the examples below, files	in subdirecto-
       ries are	not included because they are not explicitly specified.

       Without a specified commit message:

	   $ git lfs migrate import --no-rewrite test.zip *.mp3	*.psd

       With a specified	commit message:

	   $ git lfs migrate import --no-rewrite \
	     -m	"Import	test.zip, .mp3,	.psd files in root of repo" \
	     test.zip *.mp3 *.psd

SEE ALSO
       Part of the git-lfs(1) suite.

				 December 2020		    GIT-LFS-MIGRATE(1)

NAME | SYNOPSIS | MODES | OPTIONS | INCLUDE AND EXCLUDE | INCLUDE AND EXCLUDE (REFS) | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=git-lfs-migrate&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help