Commands¶

Dfetch is driven entirely from the command line. Each subcommand operates on the projects listed in the Manifest, which Dfetch searches for automatically from the current directory recursively downward.

This page is the complete CLI reference — flags, arguments, and behaviour for every subcommand. If you are new to Dfetch, start with Getting Started instead. For specific tasks the How-to Guides in the sidebar go further.

usage: dfetch [-h] [--verbose] [--no-color]
              {add,check,diff,environment,format-patch,freeze,import,init,remove,report,update,update-patch,validate} ...

positional arguments:
  {add,check,diff,environment,format-patch,freeze,import,init,remove,report,update,update-patch,validate}
                        commands
    add                 Add a new project to the manifest.
    check               Check all projects for updates.
    diff                Generate a diff of a project.
    environment         Get information about the environment dfetch is working in.
    format-patch        Format a patch to upstream any changes.
    freeze              Freeze your projects versions in the manifest as they are on disk.
    import              Generate manifest from existing submodules or externals.
    init                Initialize a manifest.
    remove              Remove a project from the manifest and delete its directory.
    report              Generate reports containing information about the projects components.
    update              Update all modules from the manifest.
    update-patch        Update a patch to reflect the last changes.
    validate            Validate a manifest.

options:
  -h, --help            show this help message and exit
  --verbose, -v         Increase verbosity
  --no-color            Disable colored output

Find the complete documentation online.

https://dfetch.rtfd.org

Init¶

Initialize a manifest.

usage: dfetch init [-h]

Generate a manifest that can be used as basis for a project.

Dfetch can generate a starting manifest.

Running dfetch init creates a dfetch.yaml file in the current directory. The file contains a minimal template that you can open and edit directly, or populate incrementally using dfetch add.

Once you have listed your dependencies, fetch them with dfetch update.

If a dfetch.yaml already exists in the current directory, Dfetch prints a warning and exits without overwriting it.

Import¶

Generate manifest from existing submodules or externals.

usage: dfetch import [-h]

Look for submodules in a git project or externals in a svn project and create a manifest based on that.

Dfetch can convert your Git submodules or SVN externals based project to Dfetch.

Dfetch will look for all submodules or externals in the current project and generate a manifest with the current versions of the repository.

After importing, you will need to remove the submodules or externals, and then you can let Dfetch update by running dfetch update.

For full step-by-step migration instructions see Migrate to Dfetch.

See also

Migrate to Dfetch — step-by-step guide for switching from Git submodules or SVN externals.

Add¶

Add a new project to the manifest.

usage: dfetch add [-h] [-i] [--name NAME] [--dst PATH] [--version VERSION]
                  [--src PATH] [--ignore PATH [PATH ...]]
                  <remote_url>

Positional Arguments¶

<remote_url>: Remote URL of the repository to add.

Named Arguments¶

-i, --interactive

Interactively guide through each manifest field. Dfetch fetches the remote branch/tag list and lets you pick or override every value.

Default: False

--name

Project name (skips the name prompt in interactive mode).

--dst

Local destination path (skips the destination prompt in interactive mode).

--version

Branch, tag, or revision (skips the version prompt in interactive mode).

--src

Sub-path or glob inside the remote repo (skips the source prompt in interactive mode).

--ignore

Paths to ignore (skips the ignore prompt in interactive mode).

Append a project entry to the manifest without fetching. Use -i/–interactive to be guided through each field.

Add a project to the manifest from the command line.

Use dfetch add <url> to append a project without prompts, or dfetch add -i <url> for the interactive wizard. See Add a project for the full guide.

Example: Adding a project appends it to the manifest

../features/add-project-through-cli.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: ext/existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add some-remote-server/MyLib.git"
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: MyLib
        url: some-remote-server/MyLib.git
        branch: master
        dst: ext/MyLib
    """

Example: Duplicate project name is auto-renamed in non-interactive mode

../features/add-project-through-cli.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: MyLib
          url: some-remote-server/MyLib.git
    """
When I run "dfetch add some-remote-server/MyLib.git"
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: MyLib-1
        url: some-remote-server/MyLib.git
        branch: master
    """

Example: Destination is guessed from common prefix of existing projects

../features/add-project-through-cli.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: ext/lib-a
          url: some-remote-server/lib-a.git
        - name: ext/lib-b
          url: some-remote-server/lib-b.git
    """
When I run "dfetch add some-remote-server/MyLib.git"
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: MyLib
        url: some-remote-server/MyLib.git
        branch: master
        dst: ext/MyLib
    """

Example: Non-interactive add with field overrides

../features/add-project-through-cli.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: ext/existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add some-remote-server/MyLib.git --name my-lib --dst libs/my-lib"
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: my-lib
        url: some-remote-server/MyLib.git
        branch: master
        dst: libs/my-lib
    """

Example: Interactive add guides through each field

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: ext/existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer  |
    | Project name              | my-lib  |
    | Destination path          | libs/my |
    | Version                   | master  |
    | Source path               |         |
    | Ignore paths              |         |
    | Add project to manifest?  | y       |
    | Run update                | n       |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: my-lib
        url: some-remote-server/MyLib.git
        branch: master
        dst: libs/my
    """

Example: Interactive add with tag version

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer |
    | Project name              | my-lib |
    | Destination path          | my-lib |
    | Version                   | v1     |
    | Source path               |        |
    | Ignore paths              |        |
    | Add project to manifest?  | y      |
    | Run update                | n      |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: my-lib
        url: some-remote-server/MyLib.git
        tag: v1
    """

Example: Interactive add with src subpath

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer     |
    | Project name              | my-lib     |
    | Destination path          | my-lib     |
    | Version                   | master     |
    | Source path               | docs/api   |
    | Ignore paths              |            |
    | Add project to manifest?  | y          |
    | Run update                | n          |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: my-lib
        url: some-remote-server/MyLib.git
        branch: master
        src: docs/api
    """

Example: Interactive add with ignore list

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer       |
    | Project name              | my-lib       |
    | Destination path          | my-lib       |
    | Version                   | master       |
    | Source path               |              |
    | Ignore paths              | docs, tests  |
    | Add project to manifest?  | y            |
    | Run update                | n            |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: my-lib
        url: some-remote-server/MyLib.git
        branch: master
        ignore:
        - docs
        - tests
    """

Example: Interactive add triggers immediate fetch when update is accepted

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
      - name: existing
        url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer |
    | Project name              | MyLib  |
    | Destination path          | MyLib  |
    | Version                   | master |
    | Source path               |        |
    | Ignore paths              |        |
    | Add project to manifest?  | y      |
    | Run update                | y      |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: MyLib
        url: some-remote-server/MyLib.git
        branch: master
    """
And 'MyLib/README.md' exists

Example: Interactive add with abort does not modify manifest

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer |
    | Project name              | MyLib  |
    | Destination path          | MyLib  |
    | Version                   | master |
    | Source path               |        |
    | Ignore paths              |        |
    | Add project to manifest?  | n      |
Then the manifest 'dfetch.yaml' is replaced with
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git

    """

Example: Interactive add with empty src (repo root) does not add src field

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git" with inputs
    | Question                  | Answer |
    | Project name              | MyLib  |
    | Destination path          | MyLib  |
    | Version                   | master |
    | Source path               |        |
    | Ignore paths              |        |
    | Add project to manifest?  | y      |
    | Run update                | n      |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: MyLib
        url: some-remote-server/MyLib.git
        branch: master
    """
And the manifest 'dfetch.yaml' does not contain 'src:'

Example: Interactive add with pre-filled fields skips those prompts

../features/interactive-add.feature¶

Given the manifest 'dfetch.yaml'
    """
    manifest:
      version: '0.0'
      projects:
        - name: existing
          url: some-remote-server/existing.git
    """
When I run "dfetch add -i some-remote-server/MyLib.git --name my-lib --dst libs/my" with inputs
    | Question                  | Answer  |
    | Version                   | master  |
    | Source path               |         |
    | Ignore paths              |         |
    | Add project to manifest?  | y       |
    | Run update                | n       |
Then the manifest 'dfetch.yaml' contains entry
    """
      - name: my-lib
        url: some-remote-server/MyLib.git
        branch: master
        dst: libs/my
    """

See also

Add a project — walks through adding a new dependency from start to finish.

Remove¶

Remove a project from the manifest and delete its directory.

usage: dfetch remove [-h] <project> [<project> ...]

Positional Arguments¶

<project>: Specific project(s) to remove

Edits the manifest in-place when the manifest lives inside a git or SVN superproject to preserve comments and layout. When the manifest is not inside version control, a .backup copy of the manifest is written before updating it.

Remove projects from the manifest and delete their directories.

Use dfetch remove <project> to remove one or more projects. See Remove a project for the full guide.

Example: Remove an existing project

../features/remove-project.feature¶

 Given the manifest 'dfetch.yaml'
        """
        manifest:
          version: '0.0'

          projects:
            - name: lib-alpha
              url: some-remote-server/LibAlpha.git
              dst: ext/lib-alpha

            - name: lib-beta
              url: some-remote-server/LibBeta.git
              dst: ext/lib-beta

        """
When I run "dfetch remove lib-alpha"
Then the manifest 'dfetch.yaml' is replaced with
        """
        manifest:
          version: '0.0'

          projects:
          - name: lib-beta
            url: some-remote-server/LibBeta.git
            dst: ext/lib-beta

        """
And the directory 'ext/lib-alpha' should be removed from disk
And the output shows
        """
        Dfetch (0.13.0)
          lib-alpha:
          > removed
        """

Example: Remove multiple projects atomically

../features/remove-project.feature¶

 Given the manifest 'dfetch.yaml'
        """
        manifest:
          version: '0.0'

          projects:
            - name: lib-alpha
              url: some-remote-server/LibAlpha.git
              dst: ext/lib-alpha

            - name: lib-beta
              url: some-remote-server/LibBeta.git
              dst: ext/lib-beta

        """
When I run "dfetch remove lib-alpha lib-beta"
Then the manifest 'dfetch.yaml' is replaced with
        """
        manifest:
          version: '0.0'

          projects: []

        """
And the directory 'ext/lib-alpha' should be removed from disk
And the directory 'ext/lib-beta' should be removed from disk
And the output shows
        """
        Dfetch (0.13.0)
          lib-alpha:
          > removed
          lib-beta:
          > removed
        """

Example: Removing a project that does not exist in the manifest is reported

../features/remove-project.feature¶

 Given the manifest 'dfetch.yaml'
        """
        manifest:
          version: '0.0'

          projects:
            - name: lib-alpha
              url: some-remote-server/LibAlpha.git
              dst: ext/lib-alpha

            - name: lib-beta
              url: some-remote-server/LibBeta.git
              dst: ext/lib-beta

        """
When I run "dfetch remove lib-alpha lib-unknown lib-beta"
Then the manifest 'dfetch.yaml' is replaced with
        """
        manifest:
          version: '0.0'

          projects: []

        """
And the directory 'ext/lib-alpha' should be removed from disk
And the directory 'ext/lib-beta' should be removed from disk
And the output shows
        """
        Dfetch (0.13.0)
          lib-unknown:
          > project 'lib-unknown' not found in manifest
          lib-alpha:
          > removed
          lib-beta:
          > removed
        """

Example: Removing a project that was never fetched still removes it from the manifest

../features/remove-project.feature¶

 Given the manifest 'dfetch.yaml'
        """
        manifest:
          version: '0.0'

          projects:
            - name: lib-gamma
              url: some-remote-server/LibBeta.git
              dst: ext/lib-gamma

            - name: lib-alpha
              url: some-remote-server/LibAlpha.git
              dst: ext/lib-alpha

        """
And the directory 'ext/lib-gamma' does not exist on disk
When I run "dfetch remove lib-gamma"
Then the manifest 'dfetch.yaml' is replaced with
        """
        manifest:
          version: '0.0'

          projects:
          - name: lib-alpha
            url: some-remote-server/LibAlpha.git
            dst: ext/lib-alpha

        """
And the output shows
        """
        Dfetch (0.13.0)
          lib-gamma:
          > removed
        """

See also

Remove a project — how to remove projects from your manifest.

Check¶

Check all projects for updates.

usage: dfetch check [-h] [--no-recommendations] [--jenkins-json outfile]
                    [--sarif outfile] [--code-climate outfile]
                    [<project> ...]

Positional Arguments¶

<project>: Specific project(s) to check (default: all projects in manifest)

Named Arguments¶

--no-recommendations, -N

Do not check sub-manifests found inside fetched projects. By default, dfetch.yaml files discovered in fetched dependencies are also checked for outdated entries.

Default: False

--jenkins-json

Write a Jenkins warnings-ng JSON report to <outfile>.

--sarif

Write a SARIF 2.1.0 report to <outfile> (GitHub Advanced Security).

--code-climate

Write a Code Climate JSON report to <outfile> (GitLab pipelines).

Check all projects to see if there are any new updates.

To check if your projects are up-to-date, you can let dfetch check it.

For each project the local version (based on tag or revision) will be compared against the available version. If there are new versions available this will be shown.