From 69ecff6369c3991221a7c35292330fd9771e0c19 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 18:19:25 +0000 Subject: [PATCH 1/9] Use dymaic version for docs --- doc/conf.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index e295ab66..c28e3e7e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -12,8 +12,12 @@ # import os import sys +from importlib.metadata import PackageNotFoundError, version -from dfetch import __version__ +try: + __version__ = version("dfetch") +except PackageNotFoundError: + __version__ = "0.0.0" # Prevent ANSI color codes in command output captured by sphinxcontrib.programoutput. # Python 3.13+ argparse emits colors when FORCE_COLOR is set; NO_COLOR suppresses @@ -250,7 +254,13 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, f"dfetch-{__version__}.tex", "Dfetch Documentation", "Dfetch", "manual"), + ( + master_doc, + f"dfetch-{__version__}.tex", + "Dfetch Documentation", + "Dfetch", + "manual", + ), ] From c2d03ba19aa968f6b8d751e73978e0f7d212aee5 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 18:24:54 +0000 Subject: [PATCH 2/9] Add $ before terminal commands --- doc/howto/adding-a-project.rst | 8 ++++---- doc/howto/sbom.rst | 2 +- doc/howto/troubleshooting.rst | 4 ++-- doc/howto/updating-projects.rst | 10 +++++----- doc/tutorials/getting_started.rst | 16 ++++++++-------- doc/tutorials/installation.rst | 16 ++++++++-------- 6 files changed, 28 insertions(+), 28 deletions(-) diff --git a/doc/howto/adding-a-project.rst b/doc/howto/adding-a-project.rst index d956ae88..35ec856a 100644 --- a/doc/howto/adding-a-project.rst +++ b/doc/howto/adding-a-project.rst @@ -59,7 +59,7 @@ path based on your existing projects. .. code-block:: sh - dfetch add https://github.com/some-org/some-repo.git + $ dfetch add https://github.com/some-org/some-repo.git .. asciinema:: ../asciicasts/add.cast @@ -67,7 +67,7 @@ Override individual fields with flags: .. code-block:: sh - dfetch add \ + $ dfetch add \ --name mylib \ --dst ext/mylib \ --version v2.0 \ @@ -88,7 +88,7 @@ inside the remote repository, or configure which paths to ignore. .. code-block:: sh - dfetch add -i https://github.com/some-org/some-repo.git + $ dfetch add -i https://github.com/some-org/some-repo.git .. asciinema:: ../asciicasts/interactive-add.cast @@ -108,7 +108,7 @@ You can pre-fill any field to skip its prompt: .. code-block:: sh - dfetch add -i --version main \ + $ dfetch add -i --version main \ --src lib/core \ https://github.com/some-org/some-repo.git diff --git a/doc/howto/sbom.rst b/doc/howto/sbom.rst index f6116401..9b2bad55 100644 --- a/doc/howto/sbom.rst +++ b/doc/howto/sbom.rst @@ -13,7 +13,7 @@ license policy across an organisation. .. code-block:: sh - dfetch report -t sbom -o dfetch.cdx.json + $ dfetch report -t sbom -o dfetch.cdx.json *Dfetch* parses each project's license at fetch time and stores it in the ``.dfetch_data.yaml`` metadata file, so reports stay accurate without diff --git a/doc/howto/troubleshooting.rst b/doc/howto/troubleshooting.rst index 4c272b54..657bee5a 100644 --- a/doc/howto/troubleshooting.rst +++ b/doc/howto/troubleshooting.rst @@ -15,7 +15,7 @@ This shows missing or incompatible dependencies. Run: .. code-block:: bash - dfetch environment + $ dfetch environment Compare the output to the expected tools your commands require. @@ -29,7 +29,7 @@ to see exactly what *Dfetch* is doing: .. code-block:: bash - dfetch -v import + $ dfetch -v import Verbose output shows each command *Dfetch* executes and its result, making it easier to spot errors, missing tools, or other issues. diff --git a/doc/howto/updating-projects.rst b/doc/howto/updating-projects.rst index ba319cfc..92c613f6 100644 --- a/doc/howto/updating-projects.rst +++ b/doc/howto/updating-projects.rst @@ -23,7 +23,7 @@ Run without arguments to fetch every project in the manifest: .. code-block:: sh - dfetch update + $ dfetch update .. asciinema:: ../asciicasts/update.cast @@ -55,9 +55,9 @@ Pass one or more project names to limit which entries are updated: .. code-block:: sh - dfetch update mylib + $ dfetch update mylib - dfetch update mylib myother + $ dfetch update mylib myother .. _updating-force: @@ -70,7 +70,7 @@ overwrite regardless: .. code-block:: sh - dfetch update --force mylib + $ dfetch update --force mylib .. warning:: @@ -91,7 +91,7 @@ To skip this check entirely: .. code-block:: sh - dfetch update --no-recommendations + $ dfetch update --no-recommendations .. scenario-include:: ../features/updated-project-has-dependencies.feature diff --git a/doc/tutorials/getting_started.rst b/doc/tutorials/getting_started.rst index 8e3e6e1f..a4280c1c 100644 --- a/doc/tutorials/getting_started.rst +++ b/doc/tutorials/getting_started.rst @@ -81,7 +81,7 @@ During development of your project you can periodically check for updates with: .. code-block:: console - dfetch check + $ dfetch check *Dfetch* will check for each project if a newer version is available. @@ -109,7 +109,7 @@ And after that rerunning `update`: .. code-block:: console - dfetch update + $ dfetch update Now you can review the changes and commit them once again if you are happy. @@ -163,8 +163,8 @@ First commit the fetched version to your version control system. This provides .. code-block:: console - git add ext/test-repo-tag - git commit -m "Add test-repo-tag v2.0" + $ git add ext/test-repo-tag + $ git commit -m "Add test-repo-tag v2.0" Then you can work on the files inside ``ext/test-repo-tag``, once you are happy you can run ``dfetch diff`` to create a patch file with respect to the committed @@ -172,7 +172,7 @@ version. .. code-block:: console - dfetch diff + $ dfetch diff A patch file ``ext-test-repo-tag.patch`` is created in the current folder. You can place it anywhere you want, as long as it is reachable when running *Dfetch*. @@ -202,14 +202,14 @@ be applied. .. code-block:: console - dfetch update -f ext/test-repo-tag + $ dfetch update -f ext/test-repo-tag Now amend the last commit to include the fetched project and the patch file: .. code-block:: console - git add ext/test-repo-tag ext-test-repo-tag.patch - git commit --amend --no-edit + $ git add ext/test-repo-tag ext-test-repo-tag.patch + $ git commit --amend --no-edit For more details on working with patches see :ref:`Diff` and :ref:`Patch`. diff --git a/doc/tutorials/installation.rst b/doc/tutorials/installation.rst index 2e9e68cb..46682269 100644 --- a/doc/tutorials/installation.rst +++ b/doc/tutorials/installation.rst @@ -8,13 +8,13 @@ If you are using python you can install the latest release with: .. code-block:: bash - pip install dfetch + $ pip install dfetch Or install the latest version from the main branch: .. code-block:: bash - pip install git+https://github.com/dfetch-org/dfetch.git@main#egg=dfetch + $ pip install git+https://github.com/dfetch-org/dfetch.git@main#egg=dfetch Binary distributions -------------------- @@ -43,15 +43,15 @@ The version is automatically determined from the project and used to name the in .. code-block:: bash - sudo dpkg -i dfetch--nix.deb + $ sudo dpkg -i dfetch--nix.deb RPM-based distributions (``.rpm``): .. code-block:: bash - sudo dnf install dfetch--nix.rpm + $ sudo dnf install dfetch--nix.rpm # or - sudo rpm -i dfetch--nix.rpm + $ sudo rpm -i dfetch--nix.rpm .. tab:: macOS @@ -59,7 +59,7 @@ The version is automatically determined from the project and used to name the in .. code-block:: bash - sudo installer -pkg dfetch--osx.pkg -target / + $ sudo installer -pkg dfetch--osx.pkg -target / .. tab:: Windows @@ -67,7 +67,7 @@ The version is automatically determined from the project and used to name the in .. code-block:: powershell - msiexec /i dfetch--win.msi + $ msiexec /i dfetch--win.msi Uninstalling can be done through the regular Add/Remove programs section. @@ -78,6 +78,6 @@ Run the following command to verify the installation .. code-block:: bash - dfetch environment + $ dfetch environment .. asciinema:: ../asciicasts/environment.cast From 1db60511507a85685fac030b02d079f31001603e Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 18:28:04 +0000 Subject: [PATCH 3/9] Make doc more accurate about license --- doc/howto/sbom.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/howto/sbom.rst b/doc/howto/sbom.rst index 9b2bad55..377a994a 100644 --- a/doc/howto/sbom.rst +++ b/doc/howto/sbom.rst @@ -15,9 +15,10 @@ license policy across an organisation. $ dfetch report -t sbom -o dfetch.cdx.json -*Dfetch* parses each project's license at fetch time and stores it in the -``.dfetch_data.yaml`` metadata file, so reports stay accurate without -re-fetching. +*Dfetch* parses each project's license at report time, it can recognise common +license files and detect the license type with high accuracy. If a project doesn't +include a license file or has an unknown license, *Dfetch* keeps the license field +empty in the SBOM. Archive dependencies (``tar.gz``, ``zip``, …) are recorded with a ``distribution`` external reference. When an ``integrity.hash:`` field is set From 68ab7b0cb7fb1815281e427da506691bdbea0029 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 18:34:38 +0000 Subject: [PATCH 4/9] Add winget to docs --- doc/tutorials/installation.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/tutorials/installation.rst b/doc/tutorials/installation.rst index 46682269..ab52c05c 100644 --- a/doc/tutorials/installation.rst +++ b/doc/tutorials/installation.rst @@ -63,11 +63,17 @@ The version is automatically determined from the project and used to name the in .. tab:: Windows - Download the ``.msi`` installer and install by double-clicking or use: + Install dfetch directly through winget: .. code-block:: powershell - $ msiexec /i dfetch--win.msi + > winget install dfetch + + Or download the ``.msi`` installer from the releases page and install by double-clicking or use: + + .. code-block:: powershell + + > msiexec /i dfetch--win.msi Uninstalling can be done through the regular Add/Remove programs section. From 97a602f67fbe3bef9fbec89a586400a79953024a Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 18:39:29 +0000 Subject: [PATCH 5/9] Add reference to architecture docs --- pyproject.toml | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 7764936f..d8ca05f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -230,18 +230,7 @@ file-description = "A vendoring tool for fetching and managing external dependen root_packages = ["dfetch"] # Enforce C4 architecture: higher layers may import from lower layers, not vice versa. -# See doc/internal.rst for the architecture documentation. -# -# dfetch.commands (top — orchestrates everything) -# ↓ -# dfetch.reporting (formats output, knows about project & manifest) -# ↓ -# dfetch.project (core domain — knows about manifest & vcs) -# ↓ -# dfetch.manifest | dfetch.vcs (independent domain services) -# ↓ -# dfetch.util | dfetch.log | dfetch.terminal (foundational — siblings cannot import each other) - +# See Architecture.rst for more details on the architecture of dfetch. [[tool.importlinter.contracts]] name = "C4 architecture layers" type = "layers" From 1b4b528691b8383616d3c1095e777da9fdb381e7 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 19:32:52 +0000 Subject: [PATCH 6/9] Ensure git history is present for docs --- .github/workflows/docs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 31cfa6c5..a4239a38 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,6 +22,8 @@ jobs: egress-policy: audit - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + fetch-depth: 0 - name: Install Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 @@ -79,6 +81,8 @@ jobs: egress-policy: audit - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + fetch-depth: 0 - name: Setup Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 From 4c59dacd4ddb43fb72900cebc33dead03da61bc5 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 19:42:31 +0000 Subject: [PATCH 7/9] Make winget command more precise --- doc/tutorials/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorials/installation.rst b/doc/tutorials/installation.rst index ab52c05c..ac15b96b 100644 --- a/doc/tutorials/installation.rst +++ b/doc/tutorials/installation.rst @@ -67,7 +67,7 @@ The version is automatically determined from the project and used to name the in .. code-block:: powershell - > winget install dfetch + > winget install -e --id DFetch-org.DFetch Or download the ``.msi`` installer from the releases page and install by double-clicking or use: From 85be36bd009a97901722a2b841d72457cb1ed938 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 19:52:35 +0000 Subject: [PATCH 8/9] Cleanup console examples in docs --- dfetch/commands/diff.py | 12 ++++++------ dfetch/commands/format_patch.py | 4 ++-- dfetch/commands/update_patch.py | 4 ++-- dfetch/manifest/project.py | 8 ++++---- doc/howto/adding-a-project.rst | 8 ++++---- doc/howto/check-ci.rst | 4 ++-- doc/howto/patching.rst | 20 ++++++++++---------- doc/howto/sbom.rst | 2 +- doc/howto/updating-projects.rst | 16 +++++++++++----- doc/tutorials/getting_started.rst | 4 +++- 10 files changed, 45 insertions(+), 37 deletions(-) diff --git a/dfetch/commands/diff.py b/dfetch/commands/diff.py index 3f226ac4..2e529ef2 100644 --- a/dfetch/commands/diff.py +++ b/dfetch/commands/diff.py @@ -15,9 +15,9 @@ The below statement will generate a patch for ``some-project`` from your manifest. -.. code-block:: sh +.. code-block:: console - dfetch diff some-project + $ dfetch diff some-project .. tabs:: @@ -41,15 +41,15 @@ .. tab:: Git - .. code-block:: sh + .. code-block:: console - git apply --check formatted-some-project.patch + $ git apply --check formatted-some-project.patch .. tab:: SVN - .. code-block:: sh + .. code-block:: console - svn patch formatted-some-project.patch + $ svn patch formatted-some-project.patch """ diff --git a/dfetch/commands/format_patch.py b/dfetch/commands/format_patch.py index 253eeb0a..4bc34148 100644 --- a/dfetch/commands/format_patch.py +++ b/dfetch/commands/format_patch.py @@ -8,9 +8,9 @@ root directory. The ``format-patch`` command reformats all patches of a project to make them usable for the upstream project. -.. code-block:: sh +.. code-block:: console - dfetch format-patch some-project + $ dfetch format-patch some-project .. tabs:: diff --git a/dfetch/commands/update_patch.py b/dfetch/commands/update_patch.py index c0117180..5eca48bc 100644 --- a/dfetch/commands/update_patch.py +++ b/dfetch/commands/update_patch.py @@ -15,9 +15,9 @@ The below statement will update the patch for ``some-project`` from your manifest. -.. code-block:: sh +.. code-block:: console - dfetch update-patch some-project + $ dfetch update-patch some-project .. tabs:: diff --git a/dfetch/manifest/project.py b/dfetch/manifest/project.py index e4be2510..00c570f1 100644 --- a/dfetch/manifest/project.py +++ b/dfetch/manifest/project.py @@ -295,9 +295,9 @@ .. tab:: Git - .. code-block:: sh + .. code-block:: console - git diff --relative=path/to/project HEAD > my_patch.patch + $ git diff --relative=path/to/project HEAD > my_patch.patch For more details see the `git-diff `_ documentation. @@ -307,9 +307,9 @@ .. tab:: SVN - .. code-block:: sh + .. code-block:: console - svn diff -r HEAD path/to/my_project > my_patch.patch + $ svn diff -r HEAD path/to/my_project > my_patch.patch For more details see the `svn-diff `_ documentation. diff --git a/doc/howto/adding-a-project.rst b/doc/howto/adding-a-project.rst index 35ec856a..15503a1d 100644 --- a/doc/howto/adding-a-project.rst +++ b/doc/howto/adding-a-project.rst @@ -57,7 +57,7 @@ Pass the repository URL to ``dfetch add`` and it will append a new entry to (branches and tags), selects the default branch, and guesses a destination path based on your existing projects. -.. code-block:: sh +.. code-block:: console $ dfetch add https://github.com/some-org/some-repo.git @@ -65,7 +65,7 @@ path based on your existing projects. Override individual fields with flags: -.. code-block:: sh +.. code-block:: console $ dfetch add \ --name mylib \ @@ -86,7 +86,7 @@ The ``--interactive`` (``-i``) flag starts a step-by-step wizard. Use it when you want to browse available branches and tags, choose a sub-directory inside the remote repository, or configure which paths to ignore. -.. code-block:: sh +.. code-block:: console $ dfetch add -i https://github.com/some-org/some-repo.git @@ -106,7 +106,7 @@ The wizard walks through each field in turn: You can pre-fill any field to skip its prompt: -.. code-block:: sh +.. code-block:: console $ dfetch add -i --version main \ --src lib/core \ diff --git a/doc/howto/check-ci.rst b/doc/howto/check-ci.rst index b60cb05f..69aece50 100644 --- a/doc/howto/check-ci.rst +++ b/doc/howto/check-ci.rst @@ -25,9 +25,9 @@ Running dfetch check in CI Without extra flags the results are printed to stdout and the build fails if any issue is found: -.. code-block:: sh +.. code-block:: console - dfetch check + $ dfetch check Pass a ``--*-json`` flag to write a machine-readable report *and* continue collecting results before deciding the build outcome (each section below shows diff --git a/doc/howto/patching.rst b/doc/howto/patching.rst index 8eccceda..f83a52de 100644 --- a/doc/howto/patching.rst +++ b/doc/howto/patching.rst @@ -27,9 +27,9 @@ After fetching a project with :ref:`dfetch update `, make your edits directly in the vendored source tree. Once you are happy with the changes, run: -.. code-block:: sh +.. code-block:: console - dfetch diff some-project + $ dfetch diff some-project *Dfetch* compares the working tree against the revision recorded in the metadata file and writes a patch file named ``some-project.patch`` (or @@ -86,9 +86,9 @@ As your local edits evolve — or when the upstream version changes — the existing patch file may no longer apply cleanly. Instead of manually regenerating it, run: -.. code-block:: sh +.. code-block:: console - dfetch update-patch some-project + $ dfetch update-patch some-project This regenerates the last patch for ``some-project`` from the current working tree, keeping the upstream revision unchanged. It is safe to run repeatedly @@ -116,9 +116,9 @@ directory inside your repository. Most upstream projects expect patches to be relative to their own root, which is a different path. To reformat all patches for a project: -.. code-block:: sh +.. code-block:: console - dfetch format-patch some-project + $ dfetch format-patch some-project This writes a ``formatted-some-project.patch`` file (or one file per patch if there are several) that is ready to attach to a pull request or send by email. @@ -130,15 +130,15 @@ You can verify the formatted patch applies cleanly before submitting: .. tab:: Git - .. code-block:: sh + .. code-block:: console - git apply --check formatted-some-project.patch + $ git apply --check formatted-some-project.patch .. tab:: SVN - .. code-block:: sh + .. code-block:: console - svn patch formatted-some-project.patch + $ svn patch formatted-some-project.patch .. asciinema:: ../asciicasts/format-patch.cast diff --git a/doc/howto/sbom.rst b/doc/howto/sbom.rst index 377a994a..180f9671 100644 --- a/doc/howto/sbom.rst +++ b/doc/howto/sbom.rst @@ -11,7 +11,7 @@ license policy across an organisation. .. asciinema:: ../asciicasts/sbom.cast -.. code-block:: sh +.. code-block:: console $ dfetch report -t sbom -o dfetch.cdx.json diff --git a/doc/howto/updating-projects.rst b/doc/howto/updating-projects.rst index 92c613f6..b2e4affb 100644 --- a/doc/howto/updating-projects.rst +++ b/doc/howto/updating-projects.rst @@ -21,7 +21,7 @@ Fetching all projects Run without arguments to fetch every project in the manifest: -.. code-block:: sh +.. code-block:: console $ dfetch update @@ -53,10 +53,12 @@ Updating a single project Pass one or more project names to limit which entries are updated: -.. code-block:: sh +.. code-block:: console $ dfetch update mylib +.. code-block:: console + $ dfetch update mylib myother .. _updating-force: @@ -68,7 +70,7 @@ By default *Dfetch* skips a project that is already at the requested version or that has local modifications. Use ``--force`` (``-f``) to re-fetch and overwrite regardless: -.. code-block:: sh +.. code-block:: console $ dfetch update --force mylib @@ -89,7 +91,7 @@ decide whether to vendor those as well. To skip this check entirely: -.. code-block:: sh +.. code-block:: console $ dfetch update --no-recommendations @@ -105,7 +107,11 @@ automatically — no extra manifest entries or ``git submodule`` commands are needed. Each submodule is checked out at the exact revision pinned by the parent repository:: - Dfetch (0.12.1) +.. code-block:: console + + $ dfetch update + + Dfetch (0.13.0) my-project: > Found & fetched submodule "./ext/vendor-lib" (https://github.com/example/vendor-lib @ master - 79698c9…) > Fetched master - e1fda19… diff --git a/doc/tutorials/getting_started.rst b/doc/tutorials/getting_started.rst index a4280c1c..1a3d44d7 100644 --- a/doc/tutorials/getting_started.rst +++ b/doc/tutorials/getting_started.rst @@ -62,7 +62,9 @@ Make sure that you have installed *Dfetch* as described in :ref:`Installation`. From a command-line perform the following command:: - dfetch update +.. code-block:: console + + $ dfetch update *Dfetch* will search through all directories down until it finds the ``dfetch.yaml`` manifest and it will perform the update. From 5c36f35278cfc762703a006c6fbc4cc34a5931e9 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 3 Apr 2026 20:08:38 +0000 Subject: [PATCH 9/9] Fixup docs --- doc/howto/migration.rst | 49 ++++++++++++++++--------------- doc/howto/updating-projects.rst | 12 ++++---- doc/tutorials/getting_started.rst | 6 ++-- 3 files changed, 34 insertions(+), 33 deletions(-) diff --git a/doc/howto/migration.rst b/doc/howto/migration.rst index 928fd1d8..b3aecac4 100644 --- a/doc/howto/migration.rst +++ b/doc/howto/migration.rst @@ -20,60 +20,61 @@ Choose the guide that matches your current setup: From Git submodules ------------------- -**Before you start**, make sure: +.. note:: -- Your repository is fully up-to-date (``git pull``). -- All submodules are initialised and checked out: + Before you start, make sure your repository is fully up-to-date and + all submodules are initialised and checked out: - .. code-block:: console + .. code-block:: console - $ git submodule update --init --recursive + $ git pull + $ git submodule update --init --recursive **Steps** 1. Generate a manifest from the existing submodules: - .. code-block:: console + .. code-block:: console - $ dfetch import + $ dfetch import - This writes a ``dfetch.yaml`` file in the current directory listing each - submodule as a *Dfetch* project entry, pinned to the commit that is - currently checked out. + This writes a ``dfetch.yaml`` file in the current directory listing each + submodule as a *Dfetch* project entry, pinned to the commit that is + currently checked out. 2. Remove all Git submodules. For each submodule (replace ```` with the submodule path, e.g. ``ext/mylib``): - .. code-block:: console + .. code-block:: console - $ git submodule deinit -f - $ git rm -f - $ rm -rf .git/modules/ + $ git submodule deinit -f + $ git rm -f + $ rm -rf .git/modules/ - Repeat until ``git submodule status`` returns nothing. Commit the - result: + Repeat until ``git submodule status`` returns nothing. Commit the + result: - .. code-block:: console + .. code-block:: console - $ git commit -m "chore: remove git submodules (switching to Dfetch)" + $ git commit -m "chore: remove git submodules (switching to Dfetch)" - .. seealso:: + .. seealso:: `How do I remove a submodule? `_ 3. Fetch all projects into your repository: - .. code-block:: console + .. code-block:: console - $ dfetch update + $ dfetch update 4. Commit the fetched files: - .. code-block:: console + .. code-block:: console - $ git add . - $ git commit -m "chore: vendor dependencies with Dfetch" + $ git add . + $ git commit -m "chore: vendor dependencies with Dfetch" .. scenario-include:: ../features/import-from-git.feature diff --git a/doc/howto/updating-projects.rst b/doc/howto/updating-projects.rst index b2e4affb..a89b7ac4 100644 --- a/doc/howto/updating-projects.rst +++ b/doc/howto/updating-projects.rst @@ -105,16 +105,16 @@ Git submodules When a Git dependency contains submodules, *Dfetch* fetches and resolves them automatically — no extra manifest entries or ``git submodule`` commands are needed. Each submodule is checked out at the exact revision pinned by the -parent repository:: +parent repository. .. code-block:: console - $ dfetch update + $ dfetch update - Dfetch (0.13.0) - my-project: - > Found & fetched submodule "./ext/vendor-lib" (https://github.com/example/vendor-lib @ master - 79698c9…) - > Fetched master - e1fda19… + Dfetch (0.13.0) + my-project: + > Found & fetched submodule "./ext/vendor-lib" (https://github.com/example/vendor-lib @ master - 79698c9…) + > Fetched master - e1fda19… Nested submodules are resolved recursively. Pinned details for each submodule are recorded in ``.dfetch_data.yaml`` and are visible in diff --git a/doc/tutorials/getting_started.rst b/doc/tutorials/getting_started.rst index 1a3d44d7..4af7076b 100644 --- a/doc/tutorials/getting_started.rst +++ b/doc/tutorials/getting_started.rst @@ -60,7 +60,7 @@ My first update After creating the manifest we can let *Dfetch* perform an update. Make sure that you have installed *Dfetch* as described in :ref:`Installation`. -From a command-line perform the following command:: +From a command-line perform the following command .. code-block:: console @@ -210,8 +210,8 @@ Now amend the last commit to include the fetched project and the patch file: .. code-block:: console - $ git add ext/test-repo-tag ext-test-repo-tag.patch - $ git commit --amend --no-edit + $ git add ext/test-repo-tag ext-test-repo-tag.patch + $ git commit --amend --no-edit For more details on working with patches see :ref:`Diff` and :ref:`Patch`.