cli: Command-line interface to lfc

This module provides several functions that are the main user interface to LFC. There is a function main() that reads sys.argv (the command-line strings of the current command). Then main() dispatches one of several other functions, for example

These secondary commands read Python argumennts and keyword arguments rather than parsing sys.argv, so they are usable to Python API programmers as well.

class lfc.cli.LFCArgParser
lfc.cli.lfc_add(*a, **kw)

Calculate metadata for large file(s) and cache them

Call:
>>> lfc_add(*a, **kw)
>>> lfc_add(pat1, mode=1)
>>> lfc_add(pat1, pat2, ..., mode=1)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

mode: {1} | 2

LFC mode for each added file

lfc.cli.lfc_autopull(*a, **kw)

Pull most recent version of mode-2 (configurable) LFC files

Normally this will pull all mode-2 files, but that can be configured to all files or no files by setting core.autopull in .lfc/config. Users may also limit the pull to specific files, but that is not the primary use case.

Call:
>>> lfc_autopull()
>>> lfc_autopull(pat1, pat2, ..., quiet=True)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

quiet: {True} | False

Option to suppress STDOUT for files already up-to-date

lfc.cli.lfc_autopush(*a, **kw)

Push most recent version of mode-2 (configurable) LFC files

Normally this will push all mode-2 files, but that can be configured to all files or no files by setting core.autopull in .lfc/config. Users may also limit the push to specific files, but that is not the primary use case.

Call:
>>> lfc_autopush()
>>> lfc_autopush(pat1, pat2, ..., quiet=True)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

quiet: {True} | False

Option to suppress STDOUT for files already up-to-date

lfc.cli.lfc_checkout(*a, **kw)

Check out one or more large files (from local cache)

If no patterns are specified, the target will be all large files that are in the current folder or children thereof.

Call:
>>> lfc_checkout()
>>> lfc_checkout(pat1, pat2, ..., force=False)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

f, force: True | {False}

Delete uncached working file if present

lfc.cli.lfc_config(*a, **kw)

Print or set an LFC configuration variable

Call:
>>> lfc_config(cmdname, fullopt)
>>> lfc_config(cmdname, fullopt, val)
Inputs:
cmdname: "get" | "set"

LFC configuration operation to take

fullopt: str

Full option name, "{sec}.{opt}"

val: object

Value to set if cmdname is "set"

lfc.cli.lfc_init(*a, **kw)

Initialize a repo as an LFC repo

This will create (if necessary) the following folders:

  • .lfc/

  • .lfc/cache/

and the following files:

  • .lfc/config

  • .lfc/.gitignore

Call:
>>> lfc_init()
lfc.cli.lfc_install_hooks(*a, **kw)

Install git-hooks in current LFC repo

This creates the following files relative to the top-level folder of the working repository:

  • .git/hooks/post-merge

  • .git/hooks/pre-push

If the files exist, this will not overwrite them. After writing the file, it also makes the executable.

Call:
>>> lfc_install_hooks()
lfc.cli.lfc_ls_files(*a, **kw)

List files tracked by LFC

If called from a working repository, only files in the current folder or a subfolder thereof are listed.

Call:
>>> lfc_ls_files()
>>> lfc_ls_files(*pats)
Inputs:
pats: tuple[str]

(Optional) list of file name patterns to use

STDOUT:

Each matching *.lfc file is printed to a line in STDOUT

lfc.cli.lfc_pull(*a, **kw)

Pull (fetch and checkout) one or more large files

If no patterns are specified, the target will be all large files that are in the current folder or children thereof.

Call:
>>> lfc_pull()
>>> lfc_pull(pat1, pat2, ..., quiet=True)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

mode: {None} | 1 | 2

Optionally only pull files of a specified mode

quiet: {True} | False

Option to suppress STDOUT for files already up-to-date

f, force: True | {False}

Delete uncached working file if present

lfc.cli.lfc_push(*a, **kw)

Push one or more large files

If no patterns are specified, the target will be all large files that are in the current folder or children thereof.

Call:
>>> lfc_push()
>>> lfc_push(pat1, pat2, ..., quiet=True)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

mode: {None} | 1 | 2

Optionally only push files of a specified mode

quiet: {True} | False

Option to suppress STDOUT for files already up-to-date

lfc.cli.lfc_remote(*a, **kw)

Show or set URL to an LFC remote cache

Call:
>>> lfc_remote(cmdname)
>>> lfc_remote("list")
>>> lfc_remote("add", remote, url, **kw)
Inputs:
cmdname: "list" | "add" | "set-url"

Name of LFC action to take

remote: str

Name of LFC remote

url: str

Path to remote cache (local or SSH)

d, default: True | {False}

Set remote as the default LFC remote

lfc.cli.lfc_replace_dvc(*a, **kw)

Replace any DVC settings and file names

This will rename some files and folders:

  • .dvc/ -> .lfc/

  • *.dvc -> *.lfc

It will also delete some JSON files used by DVC if present.

The function is safe to call multiple times if DVC has been partially replaced. If there are no DVC artifacts, this function will take no action.

It does not recompute hashes. If any existing MD-5 hashes are present, LFC will continue to use them, but updating the file (using lfc add) will still use a SHA-256 hash.

Call:
>>> lfc_replace_dvc()
lfc.cli.lfc_set_mode(*a, **kw)

Set the mode of one or more LFC files

Call:
>>> lfc_set_mode(*pats, mode=None)
Inputs:
pat1: str

Name of large file or file name pattern

pat2: str

Second file name or file name pattern

mode: 1 | 2

Required LFC mode to set for each file matching any pat

lfc.cli.lfc_show(*a, **kw)

Print contents of a large file to STDOUT, even in bare repo

This function does not decode the bytes so that binary files can be piped from bare repos through STDOUT.

Call:
>>> lfc_show(fname, ref="HEAD")
Inputs:
fname: str

Name of original file or large file stub

ref: {None} | str

Optional git reference (default HEAD on bare repo)

lfc.cli.main() → int

Main command-line interface to lfc

The function works by reading the second word of sys.argv and dispatching a dedicated function for that purpose.

Call:
>>> ierr = main()
Inputs:

(read from sys.argv)

Outputs:
ierr: int

Return code