From 68e7551eb0cd8f14be44085eca2c577168ad6ecb Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 10:11:15 +0000 Subject: [PATCH 01/13] Refer directly to our own vendoring article --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index f7320850..388263f3 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,7 @@ problem, but not in a VCS-agnostic way or completely user-friendly way. We want self-contained code repositories without any hassle for end-users. Dfetch must promote upstreaming changes, but allow for local customizations. The problem is described thoroughly in [managing external dependencies](https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/) and sometimes -is also known as [*vendoring*](https://stackoverflow.com/questions/26217488/what-is-vendoring). -See [vendoring](https://dfetch.readthedocs.io/en/latest/vendoring.html) for more information about vendoring. +is also known as [*vendoring*](https://dfetch.readthedocs.io/en/latest/vendoring.html). Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools. See [alternatives](https://dfetch.readthedocs.io/en/latest/alternatives.html) for a complete list. From a7fd675aad9e965c78406f4a01c85df3ff74c052 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 10:12:23 +0000 Subject: [PATCH 02/13] Merge examples into vendoring article --- doc/examples.rst | 14 -------------- doc/index.rst | 1 - doc/vendoring.rst | 10 ++++++++++ 3 files changed, 10 insertions(+), 15 deletions(-) delete mode 100644 doc/examples.rst diff --git a/doc/examples.rst b/doc/examples.rst deleted file mode 100644 index f7d74cda..00000000 --- a/doc/examples.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. Dfetch documentation master file - -Examples -============ - -Real world projects -------------------- - -Here are some links to example projects using *Dfetch*. - -- `Dfetch`: https://github.com/dfetch-org/dfetch -- `ModbusScope`: https://github.com/ModbusScope/ModbusScope - -Internally we use *Dfetch* for various projects and uses. diff --git a/doc/index.rst b/doc/index.rst index d8c12e1d..162b8849 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,7 +35,6 @@ contributing changelog alternatives - examples vendoring legal internal diff --git a/doc/vendoring.rst b/doc/vendoring.rst index 98ec399b..d3c0c353 100644 --- a/doc/vendoring.rst +++ b/doc/vendoring.rst @@ -322,6 +322,16 @@ Real-world projects using vendoring - `Kubernetes - (Go) `_ - `Cargo - (Rust) `_ +Real world projects using Dfetch +-------------------------------- + +Here are some links to example projects using *Dfetch*. + +- `Dfetch`: https://github.com/dfetch-org/dfetch +- `ModbusScope`: https://github.com/ModbusScope/ModbusScope + +Internally we use *Dfetch* for various projects and uses. + Further Reading --------------- From 468bf999fa3b05f4570e55f462d7c9028f70641c Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 10:37:58 +0000 Subject: [PATCH 03/13] Move installation to a separate page --- doc/index.rst | 23 +------------- doc/installation.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 22 deletions(-) create mode 100644 doc/installation.rst diff --git a/doc/index.rst b/doc/index.rst index 162b8849..53417c0c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -28,6 +28,7 @@ .. toctree:: :maxdepth: 2 + installation getting_started manifest manual @@ -54,28 +55,6 @@ Dfetch must promote upstreaming changes, but allow for local customizations. Other tools that do similar things are `Zephyr's West`, `CMake ExternalProject` and other meta tools. See :ref:`alternatives` for a complete list. -Installation ------------- -`Dfetch` is a python based cross-platform cli tool. - -Install the latest release with: - -.. code-block:: - - pip install dfetch - -Or install the latest version from the main branch: - -.. code-block:: - - pip install https://github.com/dfetch-org/dfetch/archive/main.zip - -Once installed dfetch output can be seen. - -.. code-block:: - - dfetch --version - Basic usage ----------- diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 00000000..895d8927 --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,75 @@ + +.. Dfetch documentation master file + +Installation +============ + +From pip +-------- + +If you are using python you can install the latest release with: + +.. code-block:: bash + + 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#egg=dfetch + +Binary distributions +-------------------- + +Each release on the `releases page `_ +provides pre-built installers for all major platforms, so no compilation is required. + +.. tabs:: + + .. tab:: Linux + + Download the ``.deb`` or ``.rpm`` package from the releases page and install it. + + Debian / Ubuntu (``.deb``): + + .. code-block:: bash + + sudo dpkg -i dfetch--nix.deb + + RPM-based distributions (``.rpm``): + + .. code-block:: bash + + sudo dnf install dfetch--nix.rpm + # or + sudo rpm -i dfetch--nix.rpm + + .. tab:: macOS + + Download the ``.pkg`` package from the releases page and install it. + + .. code-block:: bash + + sudo installer -pkg dfetch--osx.pkg -target / + + .. tab:: Windows + + Download the ``.msi`` installer 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. + +Validating Installation +----------------------- + +Run the following command to verify the installation + +.. code-block:: bash + + dfetch environment + +.. asciinema:: asciicasts/environment.cast From 9fbadca16a3d3719ca8e03602218f3937eb9abf1 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 11:05:47 +0000 Subject: [PATCH 04/13] Sync index.rst with README --- doc/index.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 53417c0c..e4eacc5c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -46,13 +46,17 @@ Dfetch - *a source-only no-hassle project-dependency aggregator* What is Dfetch? --------------- -We needed a dependency manager that was flexible enough to retrieve dependencies as plain text +We make products that can last 15+ years; because of this we want to be able to have all sources available +to build the entire project from source without depending on external resources. +For this, we needed a dependency manager that was flexible enough to retrieve dependencies as plain text from various sources. `svn externals`, `git submodules` and `git subtrees` solve a similar -problem, but not in a vcs agnostic way or completely user friendly way. +problem, but not in a VCS-agnostic way or completely user-friendly way. We want self-contained code repositories without any hassle for end-users. Dfetch must promote upstreaming changes, but allow for local customizations. +The problem is described thoroughly in `managing external dependencies `_ and sometimes +is also known as :ref:`vendoring`. -Other tools that do similar things are `Zephyr's West`, `CMake ExternalProject` and other meta tools. +Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools. See :ref:`alternatives` for a complete list. Basic usage From 826eb6256434787e00cc3b08ed0d58afd8683518 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 11:16:06 +0000 Subject: [PATCH 05/13] Make troubleshooting more clear --- doc/troubleshooting.rst | 57 +++++++++++++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 2f130808..cd55542c 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -3,23 +3,58 @@ Troubleshooting =============== -Although we do our best, *Dfetch* can always do something unexpected. -A great deal of *Dfetch* functionality is dependent on plain-old command line commands. +Sometimes *Dfetch* may not behave as expected. This is could be because it relies on +standard command-line tools such as ``git`` to be available on your system. This section will help you +diagnose problems and understand what is happening behind the scenes. -First of all, it is important to see what tools the system has. -This can be seen with :ref:`dfetch environment`. +Step 1: Check your environment +------------------------------ -Each command *Dfetch* performs and its result can be shown with increasing the verbosity -with the `-v` flag. For example, if an :ref:`dfetch import` is giving strange results, re-run it with:: +Before anything else, it's helpful to see which tools *Dfetch* can detect on your system. +This shows missing or incompatible dependencies. Run: + +.. code-block:: bash + + dfetch environment + +Compare the output to the expected tools your commands require. + +.. asciinema:: asciicasts/environment.cast + +Step 2: Use verbose mode +----------------------- + +If a specific *Dfetch* command gives unexpected results, run it with the ``-v`` flag +to see exactly what *Dfetch* is doing: + +.. code-block:: bash dfetch -v import -Reporting issues ----------------- -We are glad to help, if you you are stuck, either create an issue_ on github or contact us through gitter_! +Verbose output shows each command *Dfetch* executes and its result, making it easier +to spot errors, missing tools, or other issues. +There can be various issues with for instance contacting or authenticating with the remote +repository or with local settings. By running the ``git`` or ``svn`` command in isolation +the issue can be shown more clearly. + +Step 3: Reporting issues +------------------------ + +If you cannot resolve a problem, we're happy to help! Check for any existing `GitHub Issues`_. +When reporting an issue, please include: + +1. The output of ``dfetch environment`` +2. The verbose output of the failing command (``dfetch -v ``) +3. Your operating system and shell information + +You can report issues via: + +- `GitHub Issues`_ +- `Gitter`_ community chat + +.. _`GitHub Issues`: https://github.com/dfetch-org/dfetch/issues +.. _`Gitter`: https://gitter.im/dfetch-org/community -.. _issue: https://github.com/dfetch-org/dfetch/issues -.. _gitter: https://gitter.im/dfetch-org/community Security issues ---------------- From e7e7d4d3f8c515fe8d75650f2aa8bd97741ee001 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 11:27:17 +0000 Subject: [PATCH 06/13] fix link --- doc/troubleshooting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index cd55542c..a929fcfd 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -64,5 +64,5 @@ You can report issues by opening a confidential issue via `GitHub Security Advis `GitHub's private vulnerability reporting`_ for more info. If you have no contact please contact us through the mail listed in the pyproject.toml. -.. _`GitHub Security Advisories`: https://github.com/dfetch/dfetch/security/advisories +.. _`GitHub Security Advisories`: https://github.com/dfetch-org/dfetch/security/advisories .. _`GitHub's private vulnerability reporting`: https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) From cc1e124532453fece42f4a5a7901ac9fe24d13e1 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 11:34:57 +0000 Subject: [PATCH 07/13] Rename vendoring --- doc/vendoring.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/vendoring.rst b/doc/vendoring.rst index d3c0c353..14fb5743 100644 --- a/doc/vendoring.rst +++ b/doc/vendoring.rst @@ -1,7 +1,7 @@ .. Dfetch documentation master file -Vendoring Dependencies -====================== +Vendoring +========= Vendoring is the practice of copying the source code of another project directly into your own project's repository. Instead of relying on a package manager to From 3efd288cdcd9bbc3812746e6d312ae1e2c632d65 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 11:35:07 +0000 Subject: [PATCH 08/13] Make underline long enough --- doc/troubleshooting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index a929fcfd..44164c77 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -22,7 +22,7 @@ Compare the output to the expected tools your commands require. .. asciinema:: asciicasts/environment.cast Step 2: Use verbose mode ------------------------ +------------------------ If a specific *Dfetch* command gives unexpected results, run it with the ``-v`` flag to see exactly what *Dfetch* is doing: From 30769fc66703963c2333d2f97961aa6aa69b718b Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 11:37:13 +0000 Subject: [PATCH 09/13] Explain placeholder --- doc/installation.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/installation.rst b/doc/installation.rst index 895d8927..46a61989 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -25,6 +25,17 @@ Binary distributions Each release on the `releases page `_ provides pre-built installers for all major platforms, so no compilation is required. +Each installer package has a name in the format ``-``. + +- ```` shows the software version: + + - If it includes ``dev``, it is a development release (for testing). + - If it is only numbers (e.g. ``0.11.0``), it is an official release. + +- ```` indicates the system the installer is for: ``nix`` (Linux), ``osx`` (Mac), or ``win`` (Windows). + +The version is automatically determined from the project and used to name the installer files. + .. tabs:: .. tab:: Linux From 6384813e4d7d8d47e7a19924f5a3224f45e29aba Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 12:33:16 +0000 Subject: [PATCH 10/13] Remove comments --- doc/alternatives.rst | 2 +- doc/contributing.rst | 2 +- doc/getting_started.rst | 2 +- doc/index.rst | 2 +- doc/installation.rst | 2 +- doc/legal.rst | 2 +- doc/manifest.rst | 2 +- doc/manual.rst | 2 +- doc/troubleshooting.rst | 2 +- doc/vendoring.rst | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/alternatives.rst b/doc/alternatives.rst index 18284524..beb51776 100644 --- a/doc/alternatives.rst +++ b/doc/alternatives.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Alternatives ============ diff --git a/doc/contributing.rst b/doc/contributing.rst index 8b9fbb75..c01580e8 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Contributing ============ diff --git a/doc/getting_started.rst b/doc/getting_started.rst index 85827a5a..5620abe6 100644 --- a/doc/getting_started.rst +++ b/doc/getting_started.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Getting Started =============== diff --git a/doc/index.rst b/doc/index.rst index e4eacc5c..7715f5f5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + .. meta:: :description: Dfetch is a VCS-agnostic tool that simplifies dependency management by retrieving diff --git a/doc/installation.rst b/doc/installation.rst index 46a61989..4f7df598 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,5 +1,5 @@ -.. Dfetch documentation master file + Installation ============ diff --git a/doc/legal.rst b/doc/legal.rst index 70cafc9f..5e36a740 100644 --- a/doc/legal.rst +++ b/doc/legal.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Legal ===== diff --git a/doc/manifest.rst b/doc/manifest.rst index 811c1867..cde2426e 100644 --- a/doc/manifest.rst +++ b/doc/manifest.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Manifest ======== diff --git a/doc/manual.rst b/doc/manual.rst index 43571841..d3332349 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Manual ====== diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 44164c77..0d26c3d2 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Troubleshooting =============== diff --git a/doc/vendoring.rst b/doc/vendoring.rst index 14fb5743..9e709590 100644 --- a/doc/vendoring.rst +++ b/doc/vendoring.rst @@ -1,4 +1,4 @@ -.. Dfetch documentation master file + Vendoring ========= From 45ef3a93cab6f366bc367299deb29e802ba1e697 Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 12:36:54 +0000 Subject: [PATCH 11/13] Make introduction in alternatives more clear --- doc/alternatives.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/alternatives.rst b/doc/alternatives.rst index beb51776..9cab3385 100644 --- a/doc/alternatives.rst +++ b/doc/alternatives.rst @@ -5,8 +5,11 @@ Alternatives The problem *Dfetch* tries to solve isn't new. There are other tools doing the same. In making a proper choice, see the below alternatives. -These alternatives could all be used to use *source* code from another project as part -of your project. +There are many alternatives, each with slightly different approaches or focuses: some are designed to manage +multiple repositories together, some are specialized in :ref:`vendoring` code into your project, and others provide +build-system or version-control-specific helpers. + +Below is a list of notable tools along with their supported version control systems, platforms, and compatibility. ========================= ===== ===== ========= ======= =================== ======================= Name Git SVN Windows Linux Language Agnostic Build System Agnostic From 6bfcd8026d2ac1108943bafec9001a25b300056d Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 12:43:41 +0000 Subject: [PATCH 12/13] Link issues in documentation auotmatically --- CHANGELOG.rst | 2 +- doc/conf.py | 5 +++++ pyproject.toml | 1 + 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 65f9f309..2c31e1d8 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -22,7 +22,7 @@ Release 0.11.0 (unreleased) * Don't make metadata file part of diff (#267) * Fix unneeded project prefix in SVN diffs (#888) * Add more tests and documentation for patching (#888) -* Restrict ``src`` to string only in schema (#889) +* Restrict ``src`` to string only in schema (#888) * Don't consider ignored files for determining local changes (#350) Release 0.10.0 (released 2025-03-12) diff --git a/doc/conf.py b/doc/conf.py index f2834181..651071c7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,6 +40,7 @@ "sphinx-jsonschema", "sphinxcontrib.programoutput", "sphinx_tabs.tabs", + "sphinx_autoissues", ] # Add any paths that contain templates here, relative to this directory. @@ -92,6 +93,10 @@ # Suppress warnings about duplicate labels from argparse directive suppress_warnings = ["autosectionlabel.manual"] +# Options for sphinx-autoissues +issuetracker = "github" +issuetracker_project = "dfetch-org/dfetch" + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/pyproject.toml b/pyproject.toml index 38afeeef..c250c0e6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -98,6 +98,7 @@ docs = [ 'sphinx-jsonschema==1.19.2', 'sphinxcontrib-programoutput==0.18', 'sphinx-tabs==3.4.7', + 'sphix-autoissues==0.0.1', ] test = ['pytest==8.4.2', 'pytest-cov==7.0.0', 'behave==1.3.3'] casts = ['asciinema==2.4.0'] From e27dff18ea6ccd36f6506a03f1319c8290b25c7e Mon Sep 17 00:00:00 2001 From: Ben Date: Sat, 3 Jan 2026 13:00:40 +0000 Subject: [PATCH 13/13] Review comments --- doc/alternatives.rst | 2 +- pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/alternatives.rst b/doc/alternatives.rst index 9cab3385..e0b03d8f 100644 --- a/doc/alternatives.rst +++ b/doc/alternatives.rst @@ -68,7 +68,7 @@ Dfetch_ ✔ ✔ ✔ ✔ ✔ .. _`Braid`: https://github.com/cristibalan/braid .. _`CGet`: https://github.com/pfultz2/cget -.. _`CMAke ExternalProject`: https://cmake.org/cmake/help/latest/module/ExternalProject.html +.. _`CMake ExternalProject`: https://cmake.org/cmake/help/latest/module/ExternalProject.html .. _`Combo-layer`: https://wiki.yoctoproject.org/wiki/Combo-layer .. _`CPM.cmake`: https://github.com/cpm-cmake/CPM.cmake .. _`CPPAN`: https://github.com/cppan/cppan diff --git a/pyproject.toml b/pyproject.toml index c250c0e6..e0c1fc3e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -98,7 +98,7 @@ docs = [ 'sphinx-jsonschema==1.19.2', 'sphinxcontrib-programoutput==0.18', 'sphinx-tabs==3.4.7', - 'sphix-autoissues==0.0.1', + 'sphinx-autoissues==0.0.1', ] test = ['pytest==8.4.2', 'pytest-cov==7.0.0', 'behave==1.3.3'] casts = ['asciinema==2.4.0']