batchfetch 1.3.6__tar.gz → 1.3.8__tar.gz

{batchfetch-1.3.6 → batchfetch-1.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batchfetch
-Version: 1.3.6
+Version: 1.3.8
 Summary: Efficiently clone and pull multiple Git repositories.
 Home-page: https://github.com/jamescherti/batchfetch
 Author: James Cherti
@@ -80,7 +80,7 @@ tasks:
     delete: true
 ```
 
-Execute the `batchfetch` command from the same directory as `batchfetch.yml` to make it clone or update the local copies of the repositories above.
+Execute the `batchfetch` command from the same directory as `batchfetch.yaml` to make it clone or update the local copies of the repositories above.
 
 ## Command-line options
 
@@ -94,7 +94,7 @@ Efficiently clone/pull multiple Git repositories in parallel.
 positional arguments:
   target                This is a target path that batchfetch is supposed to
                         handle. When no target is specified, execute the tasks
-                        of all target paths defined in the batchfetch.yml list
+                        of all target paths defined in the batchfetch.yaml list
                         of tasks.
 
 options:
@@ -117,6 +117,7 @@ options:
 ```
 
 ## Features
+
 - Git Clone and Fetch/Merge: Clones the repositories and their submodules, ensuring that all the repositories are always up-to-date by fetching and merging changes.
 - Parallel Operations: Utilizes threads to simultaneously Git clone or pull multiple repositories, dramatically reducing wait times.
 - User-Friendly Interface: Provides simple and straightforward command-line options that make it easy to get started and effectively manage your repositories.
@@ -135,7 +136,7 @@ When *batchfetch* encounters an untracked file, it displays an error message to
 
 Here is an example of a *batchfetch.yaml* file that enables *batchfetch* to accept a list of untracked files:
 
-``` yaml
+```yaml
 options:
   ignore_untracked:
     - ./test
@@ -161,7 +162,8 @@ Batchfetch is fast, not only because it runs Git commands in parallel, but also
 When the user has specifies a revision (branch or commit reference), Batchfetch only performs a `git fetch` if that revision does not exist locally. If the revision is already up to date, it simply proceeds to the next repository in the queue.
 
 That's why it is highly recommended to always specify the revision to speed up Batchfetch, if speed is important to you. Here is an example of a `batchfetch.yaml` file where the branch (`1.1.0`) or commit reference (`b9c6d9b6134b4981760893254f804a371ffbc899`) is specified:
-``` yaml
+
+```yaml
 tasks:
   - git: https://github.com/jamescherti/outline-indent.el
     revision: "1.1.0"
@@ -171,12 +173,59 @@ tasks:
     revision: b9c6d9b6134b4981760893254f804a371ffbc899
 ```
 
+### How to customize Git clone, merge, and update strategies?
+
+Batchfetch allows you to define advanced options for interacting with Git repositories. These parameters can be declared globally under the `options` block to apply to all tasks, or individually within a specific task to override the global defaults.
+
+* `git_clone_args`: A list of extra arguments to pass to `git clone`.
+* `git_merge_args`: A list of extra arguments to pass to `git merge`.
+* `git_update_strategy`: Specifies how updates should be applied. Valid options are `"merge"` (default), `"rebase"`, or `"reset"`.
+* `git_pull`: A boolean indicating whether to run Git pull/fetch operations. Set to `false` to disable updating entirely (default: `true`).
+
+Here is an example demonstrating both global and local configurations:
+
+```yaml
+---
+
+options:
+  # Apply these defaults to all tasks
+  git_update_strategy: reset
+  git_clone_args:
+    - --recurse-submodules
+
+tasks:
+  - git: https://github.com/jamescherti/compile-angel.el
+    git_pull: false # Do not attempt to update this repo
+
+  - git: https://github.com/jamescherti/outline-indent.el
+    # Override global strategy specifically for this task
+    git_update_strategy: merge
+    git_merge_args:
+      - --no-ff
+
+```
+
+### How to configure additional Git remotes?
+
+You can define additional remotes for a Git repository using the `remote` option. Pass a list of key-value pairs where the key is the remote name and the value is the corresponding URL. Batchfetch will automatically ensure these remotes are present and point to the correct URLs.
+
+```yaml
+---
+tasks:
+  - git: https://github.com/jamescherti/easysession.el
+    path: emacs/easysession
+    remote:
+      upstream: https://github.com/name/repo
+      upstream2: https://github.com/name/repo2
+```
+
 ### How to execute a command before and after a task?
 
 To execute a command both before and after a specific task, you can define the `exec_before` and `exec_after` directives within the task configuration. These directives specify commands to be executed at the respective stages of the task lifecycle.
 
 Here is an example:
-``` yaml
+
+```yaml
 ---
 tasks:
   - git: https://github.com/jamescherti/easysession.el
@@ -187,11 +236,12 @@ tasks:
 
 ### How to make batchfetch handle only one path?
 
-To configure `batchfetch` to handle a specific path, you can define your tasks in a `batchfetch.yml` file and pass the desired path as an argument to the `batchfetch` command.
+To configure `batchfetch` to handle a specific path, you can define your tasks in a `batchfetch.yaml` file and pass the desired path as an argument to the `batchfetch` command.
 
-#### Example `batchfetch.yml` file:
+#### Example `batchfetch.yaml` file:
 
 In the following example, the `easysession` task clones two Git repositories:
+
 ```yaml
 ---
 tasks:
@@ -208,7 +258,7 @@ To make `batchfetch` clone only `easysession`, pass its path as an argument:
 batchfetch easysession
 ```
 
-This will execute only the task corresponding to the `easysession` path, skipping all others in the `batchfetch.yml` file.
+This will execute only the task corresponding to the `easysession` path, skipping all others in the `batchfetch.yaml` file.
 
 ### How can I configure batchfetch to load a file other than batchfetch.yaml?
 
@@ -227,7 +277,7 @@ batchfetch
 
 ## License
 
-Copyright (C) 2024-2025 [James Cherti](https://www.jamescherti.com)
+Copyright (C) 2024-2026 [James Cherti](https://www.jamescherti.com)
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 

{batchfetch-1.3.6 → batchfetch-1.3.8}/README.md

@@ -46,7 +46,7 @@ tasks:
     delete: true
 ```
 
-Execute the `batchfetch` command from the same directory as `batchfetch.yml` to make it clone or update the local copies of the repositories above.
+Execute the `batchfetch` command from the same directory as `batchfetch.yaml` to make it clone or update the local copies of the repositories above.
 
 ## Command-line options
 
@@ -60,7 +60,7 @@ Efficiently clone/pull multiple Git repositories in parallel.
 positional arguments:
   target                This is a target path that batchfetch is supposed to
                         handle. When no target is specified, execute the tasks
-                        of all target paths defined in the batchfetch.yml list
+                        of all target paths defined in the batchfetch.yaml list
                         of tasks.
 
 options:
@@ -83,6 +83,7 @@ options:
 ```
 
 ## Features
+
 - Git Clone and Fetch/Merge: Clones the repositories and their submodules, ensuring that all the repositories are always up-to-date by fetching and merging changes.
 - Parallel Operations: Utilizes threads to simultaneously Git clone or pull multiple repositories, dramatically reducing wait times.
 - User-Friendly Interface: Provides simple and straightforward command-line options that make it easy to get started and effectively manage your repositories.
@@ -101,7 +102,7 @@ When *batchfetch* encounters an untracked file, it displays an error message to
 
 Here is an example of a *batchfetch.yaml* file that enables *batchfetch* to accept a list of untracked files:
 
-``` yaml
+```yaml
 options:
   ignore_untracked:
     - ./test
@@ -127,7 +128,8 @@ Batchfetch is fast, not only because it runs Git commands in parallel, but also
 When the user has specifies a revision (branch or commit reference), Batchfetch only performs a `git fetch` if that revision does not exist locally. If the revision is already up to date, it simply proceeds to the next repository in the queue.
 
 That's why it is highly recommended to always specify the revision to speed up Batchfetch, if speed is important to you. Here is an example of a `batchfetch.yaml` file where the branch (`1.1.0`) or commit reference (`b9c6d9b6134b4981760893254f804a371ffbc899`) is specified:
-``` yaml
+
+```yaml
 tasks:
   - git: https://github.com/jamescherti/outline-indent.el
     revision: "1.1.0"
@@ -137,12 +139,59 @@ tasks:
     revision: b9c6d9b6134b4981760893254f804a371ffbc899
 ```
 
+### How to customize Git clone, merge, and update strategies?
+
+Batchfetch allows you to define advanced options for interacting with Git repositories. These parameters can be declared globally under the `options` block to apply to all tasks, or individually within a specific task to override the global defaults.
+
+* `git_clone_args`: A list of extra arguments to pass to `git clone`.
+* `git_merge_args`: A list of extra arguments to pass to `git merge`.
+* `git_update_strategy`: Specifies how updates should be applied. Valid options are `"merge"` (default), `"rebase"`, or `"reset"`.
+* `git_pull`: A boolean indicating whether to run Git pull/fetch operations. Set to `false` to disable updating entirely (default: `true`).
+
+Here is an example demonstrating both global and local configurations:
+
+```yaml
+---
+
+options:
+  # Apply these defaults to all tasks
+  git_update_strategy: reset
+  git_clone_args:
+    - --recurse-submodules
+
+tasks:
+  - git: https://github.com/jamescherti/compile-angel.el
+    git_pull: false # Do not attempt to update this repo
+
+  - git: https://github.com/jamescherti/outline-indent.el
+    # Override global strategy specifically for this task
+    git_update_strategy: merge
+    git_merge_args:
+      - --no-ff
+
+```
+
+### How to configure additional Git remotes?
+
+You can define additional remotes for a Git repository using the `remote` option. Pass a list of key-value pairs where the key is the remote name and the value is the corresponding URL. Batchfetch will automatically ensure these remotes are present and point to the correct URLs.
+
+```yaml
+---
+tasks:
+  - git: https://github.com/jamescherti/easysession.el
+    path: emacs/easysession
+    remote:
+      upstream: https://github.com/name/repo
+      upstream2: https://github.com/name/repo2
+```
+
 ### How to execute a command before and after a task?
 
 To execute a command both before and after a specific task, you can define the `exec_before` and `exec_after` directives within the task configuration. These directives specify commands to be executed at the respective stages of the task lifecycle.
 
 Here is an example:
-``` yaml
+
+```yaml
 ---
 tasks:
   - git: https://github.com/jamescherti/easysession.el
@@ -153,11 +202,12 @@ tasks:
 
 ### How to make batchfetch handle only one path?
 
-To configure `batchfetch` to handle a specific path, you can define your tasks in a `batchfetch.yml` file and pass the desired path as an argument to the `batchfetch` command.
+To configure `batchfetch` to handle a specific path, you can define your tasks in a `batchfetch.yaml` file and pass the desired path as an argument to the `batchfetch` command.
 
-#### Example `batchfetch.yml` file:
+#### Example `batchfetch.yaml` file:
 
 In the following example, the `easysession` task clones two Git repositories:
+
 ```yaml
 ---
 tasks:
@@ -174,7 +224,7 @@ To make `batchfetch` clone only `easysession`, pass its path as an argument:
 batchfetch easysession
 ```
 
-This will execute only the task corresponding to the `easysession` path, skipping all others in the `batchfetch.yml` file.
+This will execute only the task corresponding to the `easysession` path, skipping all others in the `batchfetch.yaml` file.
 
 ### How can I configure batchfetch to load a file other than batchfetch.yaml?
 
@@ -193,7 +243,7 @@ batchfetch
 
 ## License
 
-Copyright (C) 2024-2025 [James Cherti](https://www.jamescherti.com)
+Copyright (C) 2024-2026 [James Cherti](https://www.jamescherti.com)
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 

{batchfetch-1.3.6 → batchfetch-1.3.8}/batchfetch/__init__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (C) 2024-2025 James Cherti
+# Copyright (C) 2024-2026 James Cherti
 # URL: https://github.com/jamescherti/batchfetch
 #
 # This program is free software: you can redistribute it and/or modify it under

{batchfetch-1.3.6 → batchfetch-1.3.8}/batchfetch/batchfetch_base.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (C) 2024-2025 James Cherti
+# Copyright (C) 2024-2026 James Cherti
 # URL: https://github.com/jamescherti/batchfetch
 #
 # This program is free software: you can redistribute it and/or modify it under
@@ -16,12 +16,14 @@
 # You should have received a copy of the GNU General Public License along with
 # this program. If not, see <https://www.gnu.org/licenses/>.
 #
-"Base class used to run tasks in parallel."
+"""Base class used to run tasks in parallel."""
+
+from __future__ import annotations
 
 import os
 from copy import deepcopy
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any
 
 from schema import Optional, Or, Schema
 
@@ -29,7 +31,7 @@ from .helpers import run_indent_str
 
 
 class BatchFetchError(Exception):
-    """Exception raised by Downloader()."""
+    """Exception raised by batchfetch functions."""
 
 
 class DataAlreadyInitialized(Exception):
@@ -37,21 +39,25 @@ class DataAlreadyInitialized(Exception):
 
 
 class TaskBase:
-    def __init__(self, data: Dict[str, Any], options: Dict[str, Any]):
-        self.global_options_schema: Dict[Any, Any] = {}
-        self.global_options_values: Dict[str, Any] = options
+    """Base class representing a general task to be executed."""
+
+    def __init__(self, data: dict[str, Any], options: dict[str, Any]) -> None:
+        """Initialize the task with specific data and options."""
+        self.global_options_schema: dict[Any, Any] = {}
+        self.global_options_values: dict[str, Any] = options
 
-        self.task_schema: Dict[Any, Any] = {}
-        self.task_default_values: Dict[str, Any] = {}
+        self.task_schema: dict[Any, Any] = {}
+        self.task_default_values: dict[str, Any] = {}
 
         self._item_values = data
 
         # Variables
-        self.values: Dict[str, Any] = {}
-        self.options: Dict[str, Any] = {}
+        self.values: dict[str, Any] = {}
+        self.options: dict[str, Any] = {}
         self._values_initialized = False
 
-    def _initialize_data(self):
+    def _initialize_data(self) -> None:
+        """Initialize the options and data values for the task."""
         if self._values_initialized:
             raise DataAlreadyInitialized
 
@@ -76,10 +82,12 @@ class TaskBase:
             "changed": False,
         }
 
-    def validate_schema(self):
+    def validate_schema(self) -> None:
+        """Validate the schema of the task data and options."""
         self._initialize_data()
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> Any:
+        """Retrieve an item from the task values or options."""
         self._initialize_data()
 
         if key in self.values:
@@ -88,14 +96,15 @@ class TaskBase:
         if key in self.options:
             return self.options[key]
 
-        raise KeyError(f"The item '{key}' was not found in '{self.values}")
+        raise KeyError(f"The item '{key}' was not found in '{self.values}'")
 
 
 class TaskBatchFetch(TaskBase):
     """Plugin downloader base class."""
 
-    def __init__(self, data: Dict[str, Any], options: Dict[str, Any]):
-        new_options: Dict[str, Any] = {"exec_before": [],
+    def __init__(self, data: dict[str, Any], options: dict[str, Any]) -> None:
+        """Initialize the batchfetch task plugin."""
+        new_options: dict[str, Any] = {"exec_before": [],
                                        "exec_after": [],
                                        "ignore_untracked": []}
         new_options.update(options)
@@ -107,13 +116,13 @@ class TaskBatchFetch(TaskBase):
         self.env = os.environ.copy()
 
         # Default
-        self.global_options_schema: Dict[Any, Any] = {
+        self.global_options_schema: dict[Any, Any] = {
             Optional("exec_before"): Or([str], str),
             Optional("exec_after"): Or([str], str),
             Optional("ignore_untracked"): Or([str], str),
         }
 
-        self.task_schema: Dict[Any, Any] = {
+        self.task_schema: dict[Any, Any] = {
             Optional("path"): str,
             Optional("delete"): bool,
 
@@ -124,12 +133,13 @@ class TaskBatchFetch(TaskBase):
             Optional("ignore_untracked"): Or([str], str),
         }
 
-        self.task_default_values: Dict[str, Any] = {
+        self.task_default_values: dict[str, Any] = {
             # Optional items
             "delete": False,
         }
 
-    def _initialize_data(self):
+    def _initialize_data(self) -> None:
+        """Safely initialize data for the batchfetch task."""
         try:
             super()._initialize_data()
         except DataAlreadyInitialized:
@@ -138,14 +148,16 @@ class TaskBatchFetch(TaskBase):
         # Mark values as initialized
         self._values_initialized = True
 
-    def _local_task_exec(self, *args, **kwargs):
+    def _local_task_exec(self, *args: Any, **kwargs: Any) -> None:
+        """Execute a local task command and capture its output."""
         stdout = run_indent_str(env=self.env, spaces=self.indent,
                                 *args, **kwargs)
         if not stdout.endswith("\n"):
             stdout += "\n"
         self.add_output(stdout)
 
-    def _exec_before(self, cwd: os.PathLike = Path(".")):
+    def _exec_before(self, cwd: os.PathLike = Path(".")) -> None:
+        """Execute pre-task commands defined in options and task items."""
         self._initialize_data()
         if self["delete"]:
             return
@@ -162,9 +174,10 @@ class TaskBatchFetch(TaskBase):
         if cmd:
             self._local_task_exec(cmd, cwd=str(cwd))
 
-    def _exec_after(self, cwd: os.PathLike = Path(".")):
+    def _exec_after(self, cwd: os.PathLike = Path(".")) -> None:
+        """Execute post-task commands if the task was changed successfully."""
         self._initialize_data()
-        if self["delete"] or not self.is_changed():
+        if self["delete"] or self.is_error() or not self.is_changed():
             return
 
         # Local
@@ -180,32 +193,39 @@ class TaskBatchFetch(TaskBase):
             self._local_task_exec(cmd, cwd=str(cwd))
 
     def is_changed(self) -> bool:
+        """Return True if the task execution resulted in changes."""
         self._initialize_data()
         return bool(self.values["result"]["changed"])
 
-    def set_changed(self, changed: bool):
+    def set_changed(self, changed: bool) -> None:
+        """Set the changed status of the task."""
         self._initialize_data()
         self.values["result"]["changed"] = changed
 
     def get_changed(self) -> bool:
+        """Return the changed status of the task without initializing data."""
         try:
             return bool(self.values["result"]["changed"])
         except KeyError:
             return False
 
     def is_error(self) -> bool:
+        """Return True if the task encountered an error."""
         self._initialize_data()
         return bool(self.values["result"]["error"])
 
-    def set_error(self, error: bool):
+    def set_error(self, error: bool) -> None:
+        """Set the error status of the task."""
         self._initialize_data()
         self.values["result"]["error"] = error
 
-    def set_output(self, output: str):
+    def set_output(self, output: str) -> None:
+        """Set the output string of the task."""
         self._initialize_data()
         self.values["result"]["output"] = output
 
-    def add_output(self, output: str):
+    def add_output(self, output: str) -> None:
+        """Append a string to the output of the task."""
         self._initialize_data()
         self.values["result"]["output"] += output
 
@@ -214,6 +234,7 @@ class TaskBatchFetch(TaskBase):
         self._initialize_data()
         return str(self.values["result"]["output"])
 
-    def update(self):
+    def update(self) -> dict[str, Any]:
+        """Update the task data and return the current values."""
         self._initialize_data()
         return self.values