gitlabber 1.2.7__tar.gz → 2.0.0__tar.gz

{gitlabber-1.2.7/gitlabber.egg-info → gitlabber-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: gitlabber
-Version: 1.2.7
+Version: 2.0.0
 Summary: A Gitlab clone/pull utility for backing up or cloning Gitlab groups
 Author-email: Erez Mazor <erezmazor@gmail.com>
 License: MIT
@@ -14,19 +14,19 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
-Requires-Dist: docopt
 Requires-Dist: anytree
 Requires-Dist: globre
 Requires-Dist: pyyaml
-Requires-Dist: tqdm
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: typer>=0.12
+Requires-Dist: rich
 Requires-Dist: GitPython
 Requires-Dist: python-gitlab
 Provides-Extra: test
@@ -34,6 +34,7 @@ Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: pytest-integration; extra == "test"
+Dynamic: license-file
 
 .. image:: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml/badge.svg?branch=master
     :target: https://github.com/ezbz/gitlabber/actions/workflows/python-app.yml
@@ -51,7 +52,7 @@ Requires-Dist: pytest-integration; extra == "test"
     :target: https://pypi.python.org/pypi/gitlabber/
 
 .. image:: https://readthedocs.org/projects/gitlabber/badge/?version=latest&style=plastic
-    :target: https://gitlabber.readthedocs.io/en/latest/README.html
+    :target: https://app.readthedocs.org/projects/gitlabber/
 
 
 Gitlabber
@@ -69,54 +70,84 @@ Gitlabber clones or pulls all projects under a subset of groups / subgroups by b
 Installation
 ------------
 
-* You can install Gitlabber from `PyPi <https://pypi.org/project/gitlabber>`_:
+System Requirements
+-------------------
+* Python 3.11 or higher
+* Git 2.0 or higher
+* Network access to GitLab instance
 
-.. code-block:: bash
+Installation Methods
+~~~~~~~~~~~~~~~~~~~~
+* PyPI (recommended):
 
-    pip install gitlabber
+  .. code-block:: bash
+
+      pip install gitlabber
+
+* From source:
+
+  .. code-block:: bash
+
+      git clone https://github.com/ezbz/gitlabber.git
+      cd gitlabber
+      pip install -e .
 
 * You'll need to create an `access token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_ from GitLab with API scopes `read_repository`
   and ``read_api`` (or ``api``, for GitLab versions <12.0)
 
+Quick Start
+-----------
+
+.. code-block:: bash
+
+    # Install gitlabber
+    pip install gitlabber
+
+    # Clone all your GitLab projects
+    gitlabber -t <your-token> -u <gitlab-url> .
+
 Usage
 -----
 
 * Arguments can be provided via the CLI arguments directly or via environment variables:
 
-    +---------------+---------------+---------------------------+
-    | Argument      | Flag          | Environment Variable      |
-    +===============+===============+===========================+
-    | token         | -t            | `GITLAB_TOKEN`            |
-    +---------------+---------------+---------------------------+
-    | url           | -u            | `GITLAB_URL`              |
-    +---------------+---------------+---------------------------+
-    | method        | -m            | `GITLABBER_CLONE_METHOD`  |
-    +---------------+---------------+---------------------------+
-    | naming        | -n            | `GITLABBER_FOLDER_NAMING` |
-    +---------------+---------------+---------------------------+
-    | include       | -i            | `GITLABBER_INCLUDE`       |
-    +---------------+---------------+---------------------------+
-    | exclude       | -x            | `GITLABBER_EXCLUDE`       |
-    +---------------+---------------+---------------------------+
+    +------------------+------------------+---------------------------+
+    | Argument         | Flag             | Environment Variable      |
+    +==================+==================+===========================+
+    | token            | -t               | `GITLAB_TOKEN`            |
+    +------------------+------------------+---------------------------+
+    | url              | -u               | `GITLAB_URL`              |
+    +------------------+------------------+---------------------------+
+    | method           | -m               | `GITLABBER_CLONE_METHOD`  |
+    +------------------+------------------+---------------------------+
+    | naming           | -n               | `GITLABBER_FOLDER_NAMING` |
+    +------------------+------------------+---------------------------+
+    | include          | -i               | `GITLABBER_INCLUDE`       |
+    +------------------+------------------+---------------------------+
+    | exclude          | -x               | `GITLABBER_EXCLUDE`       |
+    +------------------+------------------+---------------------------+
 
 * To view the tree run the command with your includes/excludes and the ``-p`` flag. It will print your tree like so:
 
-.. code-block:: bash
+    .. code-block:: bash
+
+        root [http://gitlab.my.com]
+        ├── group1 [/group1]
+        │   └── subgroup1 [/group1/subgroup1]
+        │       └── project1 [/group1/subgroup1/project1]
+        └── group2 [/group2]
+            ├── subgroup1 [/group2/subgroup1]
+            │   └── project2 [/group2/subgroup1/project2]
+            ├── subgroup2 [/group2/subgroup2]
+            └── subgroup3 [/group2/subgroup3]
 
-    root [http://gitlab.my.com]
-    ├── group1 [/group1]
-    │   └── subgroup1 [/group1/subgroup1]
-    │       └── project1 [/group1/subgroup1/project1]
-    └── group2 [/group2]
-        ├── subgroup1 [/group2/subgroup1]
-        │   └── project2 [/group2/subgroup1/project2]
-        ├── subgroup2 [/group2/subgroup2]
-        └── subgroup3 [/group2/subgroup3]
 
 * To see how to use glob patterns and regex to filter tree nodes, see the `globre project page <https://pypi.org/project/globre/#details>`_.
 
 * Include/Exclude patterns do not work at the API level but work on the results returned from the API, for large Gitlab installations this can take a lot of time, if you need to reduce the amound of API calls for such projects use the ``--group-search`` parameter to search only for the top level groups the interest you using the `Gitlab Group Search API <https://docs.gitlab.com/ee/api/groups.html#search-for-group>`_ which allows you to do a partial like query for a Group's path or name
 
+* **Performance optimization**: For large GitLab instances with many groups and projects, use the ``--api-concurrency`` option to dramatically speed up tree building. This enables parallel API calls (default: 5 concurrent requests) which can provide **4-6x speedup** in real-world scenarios. For example, building a tree with 21 subgroups and 21 projects can be reduced from ~96 seconds (sequential) to ~16-21 seconds (with ``--api-concurrency 5-10``). The ``-c/--concurrency`` option controls parallel git operations (cloning/pulling), while ``--api-concurrency`` controls parallel API calls (fetching groups/projects). Both can be tuned independently based on your needs.
+
 * Cloning vs Pulling: when running Gitlabber consecutively with the same parameters, it will scan the local tree structure; if the project directory exists and is a valid git repository (has .git folder in it) Gitlabber will perform a git pull in the directory, otherwise the project directory will be created and the GitLab project will be cloned into it.
 
 * Cloning submodules: use the ``-r`` flag to recurse git submodules, uses the ``--recursive`` for cloning and utilizes `GitPython's smart update method <https://github.com/gitpython-developers/GitPython/blob/20f4a9d49b466a18f1af1fdfb480bc4520a4cdc2/git/objects/submodule/root.py#L67>`_ for updating cloned repositories
@@ -126,7 +157,7 @@ Usage
 .. code-block:: bash
 
     usage: gitlabber [-h] [-t token] [-T] [-u url] [--verbose] [-p] [--print-format {json,yaml,tree}] [-n {name,path}] [-m {ssh,http}]
-                    [-a {include,exclude,only}] [-i csv] [-x csv] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version]
+                    [-a {include,exclude,only}] [-i csv] [-x csv] [-c N] [--api-concurrency N] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version]
                     [dest]
 
     Gitlabber - clones or pulls entire groups/projects tree from gitlab
@@ -148,15 +179,18 @@ Usage
                             the folder naming strategy for projects from the gitlab API attributes (default: "name")
     -m {ssh,http}, --method {ssh,http}
                             the git transport method to use for cloning (default: "ssh")
+    --fail-fast         exit immediately when encountering discovery errors
     -a {include,exclude,only}, --archived {include,exclude,only}
                             include archived projects and groups in the results (default: "include")
     -i csv, --include csv
                             comma delimited list of glob patterns of paths to projects or groups to clone/pull
     -x csv, --exclude csv
                             comma delimited list of glob patterns of paths to projects or groups to exclude from clone/pull
+    -c N, --concurrency N
+                            number of concurrent git operations (default: 1)
+    --api-concurrency N    number of concurrent API calls for tree building (default: 5)
     -r, --recursive       clone/pull git submodules recursively
     -F, --use-fetch       clone/fetch git repository (mirrored repositories)
-    -d, --dont-checkout   don't checkout pulled git repository
     -s, --include-shared  include shared projects in the results
     -g term, --group-search term
                             only include groups matching the search term, filtering done at the API level (useful for large projects, see: https://docs.gitlab.com/ee/api/groups.html#search-for-group works with partial names of path or name)
@@ -185,22 +219,54 @@ Usage
         clone projects that start with a case insensitive 'w' using a regular expression:
         gitlabber -i '/{[w].*}' .
 
-        clone a user's personal projects to username-personal-projects
+        clone the personal projects to username-personal-projects
         gitlabber -U .
 
         perform a shallow clone of the git repositories
         gitlabber -o "\-\-depth=1," .
 
+        speed up tree building for large GitLab instances with parallel API calls (4-6x faster)
+        # Real-world example: 96s → 16-21s for instances with many subgroups/projects
+        gitlabber --api-concurrency 10 -t <token> -u <url> .
+
+        use both API and git concurrency for maximum performance
+        # API concurrency speeds up tree discovery, git concurrency speeds up cloning
+        gitlabber --api-concurrency 5 -c 10 -t <token> -u <url> .
+
+        **Performance Results:**
+        * Sequential (``--api-concurrency 1``): ~96 seconds
+        * With ``--api-concurrency 5``: ~21 seconds (**4.6x speedup**)
+        * With ``--api-concurrency 10``: ~16 seconds (**6x speedup**)
 
+        *Note: Actual speedup depends on your GitLab instance structure (number of groups, subgroups, and projects). Instances with many nested subgroups benefit most from higher concurrency values.*
+
+Common Use Cases
+----------------
+
+Clone Specific Groups
+---------------------
+
+    .. code-block:: bash
+
+        # Clone only projects from a specific group
+        gitlabber -i '/MyGroup/**' .
+
+Exclude Archived Projects
+-------------------------
+
+    .. code-block:: bash
+
+        # Clone all non-archived projects
+        gitlabber -a exclude .
 
 Debugging
 ---------
 * You can use the ``--verbose`` flag to print Gitlabber debug messages
 * For more verbose GitLab messages, you can get the `GitPython <https://gitpython.readthedocs.io/en/stable>`_ module to print more debug messages by setting the environment variable:
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    export GIT_PYTHON_TRACE='full'
+        export GIT_PYTHON_TRACE='full'
 
 Troubleshooting
 ---------------
@@ -213,6 +279,26 @@ Known Limitations
 * Folder naming strategy: Consecutively running Gitlabber with different values for the ``-n`` parameter will produce undesirable results. Use the same value as previous runs, or simply don't change it from the default (project name).
 * If you're going to clone a large number of projects, observe rate limits `for gitlab.com <https://docs.gitlab.com/ee/user/gitlab_com/index.html#gitlabcom-specific-rate-limits/>`_, and `for on-premise installations <https://docs.gitlab.com/ee/security/rate_limits.html>`_.
 
+Branch Synchronization Issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Gitlabber's default pull behavior (``git pull -v -- origin``) may fail when you have a local branch checked out that no longer exists on the remote repository. This commonly occurs after:
+
+- Merging a merge request where the remote branch is automatically deleted
+- Manual deletion of remote branches
+
+**Error Example:**
+
+.. code-block:: text
+
+   git.exc.GitCommandError: Cmd('git') failed due to: exit code(1)
+   cmdline: git pull -v -- origin
+
+**Workaround:** Use the ``--use-fetch`` flag instead of the default pull behavior:
+
+.. code-block:: bash
+
+   gitlabber --use-fetch -t <your-token> -u <gitlab-url> .
 
 Links
 -----

{gitlabber-1.2.7 → gitlabber-2.0.0}/README.rst

@@ -14,7 +14,7 @@
     :target: https://pypi.python.org/pypi/gitlabber/
 
 .. image:: https://readthedocs.org/projects/gitlabber/badge/?version=latest&style=plastic
-    :target: https://gitlabber.readthedocs.io/en/latest/README.html
+    :target: https://app.readthedocs.org/projects/gitlabber/
 
 
 Gitlabber
@@ -32,54 +32,84 @@ Gitlabber clones or pulls all projects under a subset of groups / subgroups by b
 Installation
 ------------
 
-* You can install Gitlabber from `PyPi <https://pypi.org/project/gitlabber>`_:
+System Requirements
+-------------------
+* Python 3.11 or higher
+* Git 2.0 or higher
+* Network access to GitLab instance
 
-.. code-block:: bash
+Installation Methods
+~~~~~~~~~~~~~~~~~~~~
+* PyPI (recommended):
 
-    pip install gitlabber
+  .. code-block:: bash
+
+      pip install gitlabber
+
+* From source:
+
+  .. code-block:: bash
+
+      git clone https://github.com/ezbz/gitlabber.git
+      cd gitlabber
+      pip install -e .
 
 * You'll need to create an `access token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_ from GitLab with API scopes `read_repository`
   and ``read_api`` (or ``api``, for GitLab versions <12.0)
 
+Quick Start
+-----------
+
+.. code-block:: bash
+
+    # Install gitlabber
+    pip install gitlabber
+
+    # Clone all your GitLab projects
+    gitlabber -t <your-token> -u <gitlab-url> .
+
 Usage
 -----
 
 * Arguments can be provided via the CLI arguments directly or via environment variables:
 
-    +---------------+---------------+---------------------------+
-    | Argument      | Flag          | Environment Variable      |
-    +===============+===============+===========================+
-    | token         | -t            | `GITLAB_TOKEN`            |
-    +---------------+---------------+---------------------------+
-    | url           | -u            | `GITLAB_URL`              |
-    +---------------+---------------+---------------------------+
-    | method        | -m            | `GITLABBER_CLONE_METHOD`  |
-    +---------------+---------------+---------------------------+
-    | naming        | -n            | `GITLABBER_FOLDER_NAMING` |
-    +---------------+---------------+---------------------------+
-    | include       | -i            | `GITLABBER_INCLUDE`       |
-    +---------------+---------------+---------------------------+
-    | exclude       | -x            | `GITLABBER_EXCLUDE`       |
-    +---------------+---------------+---------------------------+
+    +------------------+------------------+---------------------------+
+    | Argument         | Flag             | Environment Variable      |
+    +==================+==================+===========================+
+    | token            | -t               | `GITLAB_TOKEN`            |
+    +------------------+------------------+---------------------------+
+    | url              | -u               | `GITLAB_URL`              |
+    +------------------+------------------+---------------------------+
+    | method           | -m               | `GITLABBER_CLONE_METHOD`  |
+    +------------------+------------------+---------------------------+
+    | naming           | -n               | `GITLABBER_FOLDER_NAMING` |
+    +------------------+------------------+---------------------------+
+    | include          | -i               | `GITLABBER_INCLUDE`       |
+    +------------------+------------------+---------------------------+
+    | exclude          | -x               | `GITLABBER_EXCLUDE`       |
+    +------------------+------------------+---------------------------+
 
 * To view the tree run the command with your includes/excludes and the ``-p`` flag. It will print your tree like so:
 
-.. code-block:: bash
+    .. code-block:: bash
+
+        root [http://gitlab.my.com]
+        ├── group1 [/group1]
+        │   └── subgroup1 [/group1/subgroup1]
+        │       └── project1 [/group1/subgroup1/project1]
+        └── group2 [/group2]
+            ├── subgroup1 [/group2/subgroup1]
+            │   └── project2 [/group2/subgroup1/project2]
+            ├── subgroup2 [/group2/subgroup2]
+            └── subgroup3 [/group2/subgroup3]
 
-    root [http://gitlab.my.com]
-    ├── group1 [/group1]
-    │   └── subgroup1 [/group1/subgroup1]
-    │       └── project1 [/group1/subgroup1/project1]
-    └── group2 [/group2]
-        ├── subgroup1 [/group2/subgroup1]
-        │   └── project2 [/group2/subgroup1/project2]
-        ├── subgroup2 [/group2/subgroup2]
-        └── subgroup3 [/group2/subgroup3]
 
 * To see how to use glob patterns and regex to filter tree nodes, see the `globre project page <https://pypi.org/project/globre/#details>`_.
 
 * Include/Exclude patterns do not work at the API level but work on the results returned from the API, for large Gitlab installations this can take a lot of time, if you need to reduce the amound of API calls for such projects use the ``--group-search`` parameter to search only for the top level groups the interest you using the `Gitlab Group Search API <https://docs.gitlab.com/ee/api/groups.html#search-for-group>`_ which allows you to do a partial like query for a Group's path or name
 
+* **Performance optimization**: For large GitLab instances with many groups and projects, use the ``--api-concurrency`` option to dramatically speed up tree building. This enables parallel API calls (default: 5 concurrent requests) which can provide **4-6x speedup** in real-world scenarios. For example, building a tree with 21 subgroups and 21 projects can be reduced from ~96 seconds (sequential) to ~16-21 seconds (with ``--api-concurrency 5-10``). The ``-c/--concurrency`` option controls parallel git operations (cloning/pulling), while ``--api-concurrency`` controls parallel API calls (fetching groups/projects). Both can be tuned independently based on your needs.
+
 * Cloning vs Pulling: when running Gitlabber consecutively with the same parameters, it will scan the local tree structure; if the project directory exists and is a valid git repository (has .git folder in it) Gitlabber will perform a git pull in the directory, otherwise the project directory will be created and the GitLab project will be cloned into it.
 
 * Cloning submodules: use the ``-r`` flag to recurse git submodules, uses the ``--recursive`` for cloning and utilizes `GitPython's smart update method <https://github.com/gitpython-developers/GitPython/blob/20f4a9d49b466a18f1af1fdfb480bc4520a4cdc2/git/objects/submodule/root.py#L67>`_ for updating cloned repositories
@@ -89,7 +119,7 @@ Usage
 .. code-block:: bash
 
     usage: gitlabber [-h] [-t token] [-T] [-u url] [--verbose] [-p] [--print-format {json,yaml,tree}] [-n {name,path}] [-m {ssh,http}]
-                    [-a {include,exclude,only}] [-i csv] [-x csv] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version]
+                    [-a {include,exclude,only}] [-i csv] [-x csv] [-c N] [--api-concurrency N] [-r] [-F] [-d] [-s] [-g term] [-U] [-o options] [--version]
                     [dest]
 
     Gitlabber - clones or pulls entire groups/projects tree from gitlab
@@ -111,15 +141,18 @@ Usage
                             the folder naming strategy for projects from the gitlab API attributes (default: "name")
     -m {ssh,http}, --method {ssh,http}
                             the git transport method to use for cloning (default: "ssh")
+    --fail-fast         exit immediately when encountering discovery errors
     -a {include,exclude,only}, --archived {include,exclude,only}
                             include archived projects and groups in the results (default: "include")
     -i csv, --include csv
                             comma delimited list of glob patterns of paths to projects or groups to clone/pull
     -x csv, --exclude csv
                             comma delimited list of glob patterns of paths to projects or groups to exclude from clone/pull
+    -c N, --concurrency N
+                            number of concurrent git operations (default: 1)
+    --api-concurrency N    number of concurrent API calls for tree building (default: 5)
     -r, --recursive       clone/pull git submodules recursively
     -F, --use-fetch       clone/fetch git repository (mirrored repositories)
-    -d, --dont-checkout   don't checkout pulled git repository
     -s, --include-shared  include shared projects in the results
     -g term, --group-search term
                             only include groups matching the search term, filtering done at the API level (useful for large projects, see: https://docs.gitlab.com/ee/api/groups.html#search-for-group works with partial names of path or name)
@@ -148,22 +181,54 @@ Usage
         clone projects that start with a case insensitive 'w' using a regular expression:
         gitlabber -i '/{[w].*}' .
 
-        clone a user's personal projects to username-personal-projects
+        clone the personal projects to username-personal-projects
         gitlabber -U .
 
         perform a shallow clone of the git repositories
         gitlabber -o "\-\-depth=1," .
 
+        speed up tree building for large GitLab instances with parallel API calls (4-6x faster)
+        # Real-world example: 96s → 16-21s for instances with many subgroups/projects
+        gitlabber --api-concurrency 10 -t <token> -u <url> .
+
+        use both API and git concurrency for maximum performance
+        # API concurrency speeds up tree discovery, git concurrency speeds up cloning
+        gitlabber --api-concurrency 5 -c 10 -t <token> -u <url> .
+
+        **Performance Results:**
+        * Sequential (``--api-concurrency 1``): ~96 seconds
+        * With ``--api-concurrency 5``: ~21 seconds (**4.6x speedup**)
+        * With ``--api-concurrency 10``: ~16 seconds (**6x speedup**)
 
+        *Note: Actual speedup depends on your GitLab instance structure (number of groups, subgroups, and projects). Instances with many nested subgroups benefit most from higher concurrency values.*
+
+Common Use Cases
+----------------
+
+Clone Specific Groups
+---------------------
+
+    .. code-block:: bash
+
+        # Clone only projects from a specific group
+        gitlabber -i '/MyGroup/**' .
+
+Exclude Archived Projects
+-------------------------
+
+    .. code-block:: bash
+
+        # Clone all non-archived projects
+        gitlabber -a exclude .
 
 Debugging
 ---------
 * You can use the ``--verbose`` flag to print Gitlabber debug messages
 * For more verbose GitLab messages, you can get the `GitPython <https://gitpython.readthedocs.io/en/stable>`_ module to print more debug messages by setting the environment variable:
 
-.. code-block:: bash
+    .. code-block:: bash
 
-    export GIT_PYTHON_TRACE='full'
+        export GIT_PYTHON_TRACE='full'
 
 Troubleshooting
 ---------------
@@ -176,7 +241,27 @@ Known Limitations
 * Folder naming strategy: Consecutively running Gitlabber with different values for the ``-n`` parameter will produce undesirable results. Use the same value as previous runs, or simply don't change it from the default (project name).
 * If you're going to clone a large number of projects, observe rate limits `for gitlab.com <https://docs.gitlab.com/ee/user/gitlab_com/index.html#gitlabcom-specific-rate-limits/>`_, and `for on-premise installations <https://docs.gitlab.com/ee/security/rate_limits.html>`_.
 
+Branch Synchronization Issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Gitlabber's default pull behavior (``git pull -v -- origin``) may fail when you have a local branch checked out that no longer exists on the remote repository. This commonly occurs after:
+
+- Merging a merge request where the remote branch is automatically deleted
+- Manual deletion of remote branches
+
+**Error Example:**
+
+.. code-block:: text
+
+   git.exc.GitCommandError: Cmd('git') failed due to: exit code(1)
+   cmdline: git pull -v -- origin
+
+**Workaround:** Use the ``--use-fetch`` flag instead of the default pull behavior:
+
+.. code-block:: bash
+
+   gitlabber --use-fetch -t <your-token> -u <gitlab-url> .
 
 Links
 -----
-* Gitlabber `tutorial <https://medium.com/@natskvi/clone-all-your-gitlab-groups-repos-before-starting-to-code-dd559ec5c8d6>`_ by nsk
+* Gitlabber `tutorial <https://medium.com/@natskvi/clone-all-your-gitlab-groups-repos-before-starting-to-code-dd559ec5c8d6>`_ by nsk

gitlabber-2.0.0/gitlabber/__init__.py

@@ -0,0 +1,8 @@
+"""Gitlabber - A tool for cloning GitLab project hierarchies.
+
+Gitlabber allows you to clone entire GitLab group/subgroup hierarchies
+while maintaining the directory structure. It supports filtering, progress
+tracking, and various configuration options.
+"""
+
+__version__ = '2.0.0'

gitlabber-2.0.0/gitlabber/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for running gitlabber as a module.
+
+This module allows gitlabber to be executed as:
+    python -m gitlabber
+"""
+
+from .cli import main
+main()

gitlabber-2.0.0/gitlabber/archive.py

@@ -0,0 +1,40 @@
+"""Enumeration for handling archived GitLab projects and groups.
+
+This module provides the ArchivedResults enum which controls how archived
+projects and groups are handled during tree building and filtering.
+"""
+
+from typing import Optional
+import enum
+
+
+class ArchivedResults(enum.Enum):
+    """Enumeration for handling archived results in GitLab projects.
+    
+    Attributes:
+        INCLUDE: Include both archived and non-archived projects
+        EXCLUDE: Exclude archived projects
+        ONLY: Only include archived projects
+    """
+    INCLUDE = (1, None)
+    EXCLUDE = (2, False)
+    ONLY = (3, True)
+
+    def __init__(self, int_value: int, api_value: Optional[bool]) -> None:
+        """Initialize the enum value.
+        
+        Args:
+            int_value: Integer value for internal use
+            api_value: Boolean value for GitLab API, None for INCLUDE
+        """
+        self.int_value = int_value
+        self.api_value = api_value 
+
+    def __str__(self) -> str:
+        """Return the lowercase name of the enum value."""
+        return self.name.lower()
+
+    def __repr__(self) -> str:
+        """Return the string representation of the enum value."""
+        return str(self)
+

gitlabber-2.0.0/gitlabber/auth.py

@@ -0,0 +1,62 @@
+"""Authentication providers for GitLab API access.
+
+This module defines the authentication interface and implementations
+for authenticating with GitLab instances. It supports token-based
+authentication and provides a no-op provider for testing.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+from gitlab import Gitlab
+from gitlab.exceptions import GitlabAuthenticationError
+
+class AuthProvider(ABC):
+    """Interface for GitLab authentication providers."""
+    
+    @abstractmethod
+    def authenticate(self, gitlab_client: Gitlab) -> None:
+        """Authenticate the GitLab client.
+        
+        Args:
+            gitlab_client: The GitLab client to authenticate
+            
+        Raises:
+            GitlabAuthenticationError: If authentication fails
+        """
+        pass
+
+class TokenAuthProvider(AuthProvider):
+    """Authentication provider using a personal access token."""
+    
+    def __init__(self, token: str) -> None:
+        """Initialize with a personal access token.
+        
+        Args:
+            token: GitLab personal access token
+        """
+        self.token = token
+        
+    def authenticate(self, gitlab_client: Gitlab) -> None:
+        """Authenticate using the personal access token.
+        
+        Args:
+            gitlab_client: The GitLab client to authenticate
+            
+        Raises:
+            GitlabAuthenticationError: If authentication fails
+        """
+        gitlab_client.auth()
+
+class NoAuthProvider(AuthProvider):
+    """Authentication provider that performs no authentication.
+    
+    This is useful for testing or when authentication is handled externally.
+    """
+    
+    def authenticate(self, gitlab_client: Gitlab) -> None:
+        """Perform no authentication.
+        
+        Args:
+            gitlab_client: The GitLab client (not used)
+        """
+        pass