Merge pull request #278 from jacebrowning/document-config

Document all possible source keys

CHANGELOG.md

@@ -3,6 +3,7 @@
 - Added support for locking dependencies to specific versions. (@Erich-McMillan)
 - Updated dependency locator to include all nested projects.
 - Added a summary message to display the dependency count.
+- Added support for custom `clone` params. (@mrpossoms)
 
 # 3.1 (2022-02-23)
 

Makefile

@@ -162,8 +162,7 @@ $(MKDOCS_INDEX): docs/requirements.txt mkdocs.yml docs/*.md
 	poetry run mkdocs build --clean --strict
 
 docs/requirements.txt: poetry.lock
-	poetry export --dev --without-hashes | grep mkdocs > $@
-	poetry export --dev --without-hashes | grep pygments >> $@
+	poetry export --dev --without-hashes --output $@
 
 .PHONY: uml
 uml: install docs/*.png

docs/requirements.txt

@@ -1,2 +1,83 @@
+altgraph==0.17.2; sys_platform == "darwin" and python_version >= "3.6"
+astroid==2.4.2; python_version >= "3.5"
+astunparse==1.6.3; python_version < "3.9" and python_version >= "3.7"
+atomicwrites==1.4.0; python_version >= "3.6" and python_full_version < "3.0.0" and sys_platform == "win32" or sys_platform == "win32" and python_version >= "3.6" and python_full_version >= "3.4.0"
+attrs==21.4.0; python_version >= "3.6" and python_full_version < "3.0.0" or python_full_version >= "3.5.0" and python_version >= "3.6"
+black==22.1.0; python_full_version >= "3.6.2"
+cached-property==1.5.2; python_version >= "3.7" and python_version < "3.8"
+certifi==2021.10.8; python_version >= "3.6" and python_full_version < "3.0.0" and python_version < "4.0" or python_version >= "3.6" and python_version < "4.0" and python_full_version >= "3.6.0"
+charset-normalizer==2.0.12; python_version >= "3.6" and python_version < "4.0" and python_full_version >= "3.6.0"
+classproperties==0.2.0; python_version >= "3.7" and python_version < "4.0"
+click==8.0.4; python_version >= "3.7" and python_full_version >= "3.6.2"
+colorama==0.4.4; sys_platform == "win32" and python_version >= "3.6" and python_full_version >= "3.6.2" and python_version < "4.0" and platform_system == "Windows" and (python_version >= "3.6" and python_full_version < "3.0.0" and sys_platform == "win32" or sys_platform == "win32" and python_version >= "3.6" and python_full_version >= "3.5.0")
+coverage==6.3.2; python_version >= "3.7" and python_version < "4.0"
+coveragespace==4.2; python_version >= "3.6" and python_version < "4.0"
+datafiles==1.2; python_version >= "3.7" and python_version < "4.0"
+docopt==0.6.2; python_version >= "3.6" and python_version < "4.0"
+freezegun==1.2.1; python_version >= "3.6"
+future==0.18.2; sys_platform == "win32" and python_version >= "3.6" and python_full_version >= "3.6.0"
+ghp-import==2.0.2; python_version >= "3.7"
+idna==3.3; python_version >= "3.6" and python_full_version < "3.0.0" and python_version < "4.0" or python_version >= "3.6" and python_version < "4.0" and python_full_version >= "3.6.0"
+importlib-metadata==4.11.3; python_version < "3.8" and python_version >= "3.7" and python_full_version >= "3.6.2"
+iniconfig==1.1.1; python_version >= "3.6"
+isort==5.10.1; python_full_version >= "3.6.1" and python_version < "4.0"
+jinja2==3.0.3; python_version >= "3.6"
+lazy-object-proxy==1.4.3; python_version >= "3.5" and python_full_version < "3.0.0" or python_full_version >= "3.4.0" and python_version >= "3.5"
+macfsevents==0.8.1; sys_platform == "darwin"
+macholib==1.16; sys_platform == "darwin" and python_version >= "3.6"
+markdown==3.3.6; python_version >= "3.7"
+markupsafe==2.1.1; python_version >= "3.7"
+mccabe==0.6.1; python_version >= "3.5"
+mergedeep==1.3.4; python_version >= "3.7"
+minilog==2.1; python_version >= "3.7" and python_version < "4.0"
+mkdocs-autorefs==0.4.1; python_version >= "3.7"
 mkdocs==1.2.3; python_version >= "3.6"
+mkdocstrings-python-legacy==0.2.2; python_version >= "3.7"
+mkdocstrings==0.18.1; python_version >= "3.7"
+mypy-extensions==0.4.3; python_full_version >= "3.6.2" and python_version >= "3.6"
+mypy==0.940; python_version >= "3.6"
+nose==1.3.7
+packaging==21.3; python_version >= "3.7"
+parse==1.19.0; python_version >= "3.7" and python_version < "4.0"
+pathspec==0.9.0; python_full_version >= "3.6.2"
+pefile==2021.9.3; sys_platform == "win32" and python_version >= "3.6" and python_full_version >= "3.6.0"
+platformdirs==2.5.1; python_version >= "3.7" and python_full_version >= "3.6.2"
+pluggy==1.0.0; python_version >= "3.6"
+py==1.11.0; python_version >= "3.6" and python_full_version < "3.0.0" or python_full_version >= "3.5.0" and python_version >= "3.6"
+pydocstyle==6.1.1; python_version >= "3.6"
 pygments==2.11.2; python_version >= "3.5"
+pyinstaller-hooks-contrib==2022.3; python_version >= "3.7"
+pyinstaller==4.5.1; python_version >= "3.6"
+pylint==2.6.2; python_version >= "3.5"
+pymdown-extensions==9.3; python_version >= "3.7"
+pync==2.0.3; sys_platform == "darwin"
+pyparsing==3.0.7; python_version >= "3.6"
+pytest-cov==3.0.0; python_version >= "3.6"
+pytest-describe==1.0.0
+pytest-expecter==2.3; python_version >= "3.6" and python_version < "4.0"
+pytest-random==0.02
+pytest==6.2.5; python_version >= "3.6"
+python-dateutil==2.8.2; python_version >= "3.6" and python_full_version < "3.0.0" and sys_platform == "darwin" or python_full_version >= "3.3.0" and python_version >= "3.6" and sys_platform == "darwin"
+python-termstyle==0.1.10
+pytkdocs==0.16.1; python_version >= "3.7"
+pywin32-ctypes==0.2.0; sys_platform == "win32" and python_version >= "3.6"
+pyyaml-env-tag==0.1; python_version >= "3.7"
+pyyaml==6.0; python_version >= "3.7"
+requests==2.27.1; python_version >= "3.6" and python_full_version < "3.0.0" and python_version < "4.0" or python_version >= "3.6" and python_version < "4.0" and python_full_version >= "3.6.0"
+rope==0.14.0
+ruamel.yaml.clib==0.2.6; platform_python_implementation == "CPython" and python_version < "3.11" and python_version >= "3.7"
+ruamel.yaml==0.17.21; python_version >= "3.7" and python_version < "4.0"
+six==1.16.0; python_version >= "3.7" and python_full_version < "3.0.0" and sys_platform == "darwin" and python_version < "3.9" or python_full_version >= "3.3.0" and python_version >= "3.7" and sys_platform == "darwin" and python_version < "3.9"
+sniffer==0.4.1
+snowballstemmer==2.2.0; python_version >= "3.6"
+toml==0.10.2; python_version >= "3.6" and python_full_version < "3.0.0" or python_full_version >= "3.3.0" and python_version >= "3.6"
+tomli==2.0.1; python_version >= "3.7" and python_full_version >= "3.6.2" and python_version < "4.0"
+tomlkit==0.7.2; python_version >= "3.7" and python_full_version < "3.0.0" and python_version < "4.0" or python_version >= "3.7" and python_version < "4.0" and python_full_version >= "3.5.0"
+typed-ast==1.4.3; python_version < "3.8" and implementation_name == "cpython" and python_full_version >= "3.6.2" and python_version >= "3.6"
+types-freezegun==1.1.7
+types-setuptools==57.4.11
+typing-extensions==3.10.0.2; python_version >= "3.7" and python_version < "3.8" and python_full_version >= "3.6.2"
+urllib3==1.26.9; python_version >= "3.6" and python_full_version < "3.0.0" and python_version < "4.0" or python_full_version >= "3.6.0" and python_version < "4" and python_version >= "3.6"
+watchdog==2.1.7; python_version >= "3.7"
+wrapt==1.14.0; python_version >= "3.5" and python_full_version < "3.0.0" or python_full_version >= "3.5.0" and python_version >= "3.5"
+zipp==3.7.0; python_version < "3.8" and python_version >= "3.7" and python_full_version >= "3.6.2"

docs/setup/configuration.md

@@ -0,0 +1,13 @@
+# Configuration
+
+The `gitman.yml` configuration file controls which repositories are cloned.
+
+## Sources
+
+::: gitman.models.Source
+    selection:
+        members:
+            -
+    rendering:
+      show_source: false
+      heading_level: 0

gitman/__init__.py

@@ -1,9 +1,12 @@
 """Package for GitMan."""
 
-from pkg_resources import get_distribution
+from pkg_resources import DistributionNotFound, get_distribution
 
 from .commands import delete as uninstall  # pylint: disable=redefined-builtin
 from .commands import display as list
 from .commands import init, install, lock, update
 
-__version__ = get_distribution("gitman").version
+try:
+    __version__ = get_distribution("gitman").version
+except DistributionNotFound:
+    __version__ = "???"

gitman/models/source.py

@@ -18,7 +18,20 @@ class Link:
 
 @dataclass
 class Source:
-    """A dictionary of `git` and `ln` arguments."""
+    """Represents a repository to clone and options for controlling checkout.
+
+    | Key | Purpose | Required | Default |
+    | --- | ------- | -------- | ------- |
+    | `repo` | URL of the repository | Yes |
+    | `name` | Directory for checkout | Yes | (inferred) |
+    | `rev` | SHA, tag, or branch to checkout | Yes | `"main"`|
+    | `type` | `"git"` or `"git-svn"` | No | `"git"` |
+    | `params` | Additional arguments for `clone` | No | `null` |
+    | `sparse_paths` | Controls partial checkout | No | `[]` |
+    | `links` | Creates symlinks within a project | No | `[]` |
+    | `scripts` | Shell commands to run after checkout | No | `[]` |
+
+    """
 
     repo: str = ""
     name: Optional[str] = None

mkdocs.yml

@@ -7,6 +7,11 @@ edit_uri: https://github.com/jacebrowning/gitman/edit/main/docs
 
 theme: readthedocs
 
+plugins:
+  - mkdocstrings:
+     watch:
+        - gitman
+
 markdown_extensions:
   - codehilite
 
@@ -16,6 +21,7 @@ nav:
     - Git: setup/git.md
     - Git SVN: setup/git-svn.md
     - Environment: setup/environment.md
+    - Configuration: setup/configuration.md
   - Interfaces:
     - Command Line: interfaces/cli.md
     - Git Plugin: interfaces/plugin.md