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.

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)].

       --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   --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"

       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.

				   May 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+12.1-RELEASE+and+Ports>

home | help