Merge a43d243 into ab7f67b

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 2.3 (beta)
+
+- Updated default arguments to `Source` model for improved library usage.
+
 # 2.2 (2020-12-24)
 
 - Fixed working tree validation to ignore case. (@sch0125)

README.md

@@ -45,25 +45,24 @@ or manually create one (`gitman.yml` or `.gitman.yml`) in the root of your worki
 location: vendor/gitman
 
 sources:
-  - name: framework
-    repo: https://github.com/kstenerud/iOS-Universal-Framework
+  - repo: https://github.com/kstenerud/iOS-Universal-Framework
+    name: framework
     rev: Mk5-end-of-life
-  - name: coverage
-    repo: https://github.com/jonreid/XcodeCoverage
-    rev: master
+  - repo: https://github.com/jonreid/XcodeCoverage
+    name: coverage
     link: Tools/XcodeCoverage
-  - name: trufflehog
-    repo: https://github.com/dxa4481/truffleHog
+  - repo: https://github.com/dxa4481/truffleHog
+    name: trufflehog
     rev: master
     scripts:
       - chmod a+x truffleHog/truffleHog.py
-  - name: fontawesome
-    repo: https://github.com/FortAwesome/Font-Awesome
+  - repo: https://github.com/FortAwesome/Font-Awesome
+    name: fontawesome
+    rev: master
     sparse_paths:
       - "webfonts/*"
-    rev: master
-  - name: material-design-icons
-    repo: https://github.com/google/material-design-icons.git
+  - repo: https://github.com/google/material-design-icons.git
+    name: material-design-icons
     rev: master
 
 groups:

docs/extras/git-svn-bridge.md

@@ -20,19 +20,19 @@ Example Configuration:
 location: imports
 
 sources:
-  - name: MyDirectory
+  - repo: http:http://my-svn-repo/trunk/MyDirectory
+    name: MyDirectory
     type: git-svn
-    repo: http:http://my-svn-repo/trunk/MyDirectory
     rev: HEAD
 
-  - name: MySecondDirectory
+  - repo: http:http://my-svn-repo/trunk/MySecondDirectory
+    name: MySecondDirectory
     type: git-svn
-    repo: http:http://my-svn-repo/trunk/MySecondDirectory
     rev: 72846
 
-  - name: lz4
+  - repo: https://github.com/lz4/lz4
+    name: lz4
     type: git
-    repo: https://github.com/lz4/lz4
     rev: v1.8.1.2
 ```
 

docs/interfaces/api.md

@@ -1,6 +1,10 @@
 # Package API
 
-All of the [command-line interface](cli.md) functionality is available from the Python package by importing `gitman`.
+All of the [command-line interface](cli.md) functionality is available from the Python package:
+
+```python
+import gitman
+```
 
 ## Init
 

docs/interfaces/models.md

@@ -0,0 +1,47 @@
+# Models
+
+The internal models can be used as a high-level wrapper for creating and managing working trees of cloned source code repositories.
+
+## `Source`
+
+### Define Repository
+
+Create a new `Source` instance from a repository URL:
+
+```python
+from gitman.models import Source
+
+source = Source("https://github.com/jacebrowning/gitman-demo")
+```
+
+or customize the source name and revision to get:
+
+```python
+source = Source(
+    repo="https://github.com/jacebrowning/gitman-demo",
+    name="my-demo", # defaults to repository name
+    rev="my-branch", # defaults to 'main'
+)
+```
+
+### Update Files
+
+Then, update files on disk:
+
+```python
+source.update_files()
+```
+
+or overwrite changes, if necessary:
+
+```python
+source.update_files(force=True)
+```
+
+## `Group`
+
+*TBD*
+
+## `Config`
+
+*TBD*

docs/requirements.txt

@@ -1,2 +1,2 @@
 mkdocs==1.0.4
-Pygments==2.7.2
+Pygments==2.7.3

docs/use-cases/branch-tracking.md

@@ -8,13 +8,15 @@ A web app's `gitman.yml` might look something like:
 
 ```yaml
 location: vendor/gitman
+
 sources:
-- name: api
-  repo: https://github.com/example/api
+- repo: https://github.com/example/api
+  name: api
   rev: main
+
 sources_locked:
-- name: api
-  repo: https://github.com/example/api
+- repo: https://github.com/example/api
+  name: api
   rev: b2730855c9efaaa7448b25b82e5a4363785c83ed
 ```
 

docs/use-cases/build-integration.md

@@ -27,19 +27,21 @@ using a config file similar to:
 
 ```yaml
 location: vendor/gitman
+
 sources:
-- name: lib_foo
-  repo: https://github.com/example/lib_foo
+- repo: https://github.com/example/lib_foo
+  name: lib_foo
   rev: main
-- name: lib_bar
-  repo: https://github.com/example/lib_bar
+- repo: https://github.com/example/lib_bar
+  name: lib_bar
   rev: master
+
 sources_locked:
-- name: lib_foo
-  repo: https://github.com/example/lib_foo
+- repo: https://github.com/example/lib_foo
+  name: lib_foo
   rev: 73cb3668d4c9c3388fb21de16c9c3f6217cc0e1c
-- name: lib_bar
-  repo: https://github.com/example/lib_bar
+- repo: https://github.com/example/lib_bar
+  name: lib_bar
   rev: 560ea99953a4b3e393e170e07895d14904eb032c
 ```
 

docs/use-cases/default-groups.md

@@ -14,9 +14,8 @@ Project A's configuration file:
 location: dependencies
 
 sources:
-  - name: b
-    type: git
-    repo: https://project_b
+  - repo: http://project_b
+    name: b
     rev: master
 ```
 
@@ -26,13 +25,11 @@ Project B's configuration file:
 location: dependencies
 
 sources:
-  - name: c
-    type: git
-    repo: https://project_c
+  - repo: http://project_c
+    name: c
     rev: master
-  - name: d
-    type: git
-    repo: https://project_d
+  - repo: http://project_d
+    name: d
     rev: master
 
 groups:

docs/use-cases/linked-features.md

@@ -9,13 +9,15 @@ By manually modifying the `sources_locked` section, a particular version of the
 
 ```yaml
 location: vendor/gitman
+
 sources:
-- name: api
-  repo: https://github.com/example/api
+- repo: https://github.com/example/api
+  name: api
   rev: main
+
 sources_locked:
-- name: api
-  repo: https://github.com/example/api
+- repo: https://github.com/example/api
+  name: api
   rev: feature/authenticate-with-github  # related feature branch in the API
 ```
 

docs/use-cases/sparse-checkouts.md

@@ -12,9 +12,9 @@ The following example configuration will clone the full font-awesome repo into t
 clone will only contain the `fonts` directory and it's children.
 
 ```yaml
-- name: fontawesome
-  repo: "https://github.com/FortAwesome/Font-Awesome"
+- repo: "https://github.com/FortAwesome/Font-Awesome"
+  name: fontawesome
+  rev: master
   sparse_paths:
     - "fonts/*"
-  rev: master
 ```

docs/use-cases/submodules.md

@@ -18,17 +18,18 @@ To get the same behavior using `gitman`, first delete the `.gitmodules` file and
 
 ```yaml
 location: .gitman
+
 sources:
-- name: my_dependency
-  repo: <URL of my_dependency's repository>
-  rev: a943a702d06f34599aee1f8da8ef9f7296031d69
-  link: vendor/my_depenendy
+  - repo: <URL of my_dependency repository>
+    name: my_dependency
+    rev: a943a702d06f34599aee1f8da8ef9f7296031d69
+    link: vendor/my_depenendy
 ```
 
 Add `.gitman` to your `.gitignore` file and overwrite the old submodule location by running:
 
 ```sh
-gitman install --force
+$ gitman install --force
 ```
 
 Now `<root>/vendor/my_dependency` will be a symbolic link that points to an ignored working tree of `my_dependency` at revision `a943a7`.

gitman/models/source.py

@@ -11,20 +11,24 @@
 class Source:
     """A dictionary of `git` and `ln` arguments."""
 
-    name: Optional[str]
-    type: str
-    repo: str
+    repo: str = ''
+    name: Optional[str] = None
+    rev: str = 'main'
+
+    type: str = 'git'
     sparse_paths: List[str] = field(default_factory=list)
-    rev: str = 'master'
     link: Optional[str] = None
+
     scripts: List[str] = field(default_factory=list)
 
     DIRTY = '<dirty>'
     UNKNOWN = '<unknown>'
 
     def __post_init__(self):
         if self.name is None:
-            self.name = self._infer_name(self.repo)
+            self.name = self.repo.split('/')[-1].split('.')[0]
+        else:
+            self.name = str(self.name)
         self.type = self.type or 'git'
 
     def __repr__(self):
@@ -267,9 +271,3 @@ def _invalid_repository(self):
             path
         )
         return exceptions.InvalidRepository(msg)
-
-    @staticmethod
-    def _infer_name(repo):
-        filename = repo.split('/')[-1]
-        name = filename.split('.')[0]
-        return name

gitman/tests/test_models_source.py

@@ -20,9 +20,15 @@ def test_init_defaults(self):
 
         assert 'http://example.com/foo/bar.git' == source.repo
         assert 'bar' == source.name
-        assert 'master' == source.rev
+        assert 'main' == source.rev
         assert None is source.link
 
+    def test_init_name_as_path(self, tmp_path):
+        """Verify the name can be a path."""
+        source = Source(type='git', repo='http://example.com', name=tmp_path)
+
+        assert isinstance(source.name, str)
+
     def test_init_rev(self):
         """Verify the revision can be customized."""
         source = Source(

mkdocs.yml

@@ -13,24 +13,25 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Setup:
-      - Git: setup/git.md
-      - Git SVN: setup/git-svn.md
-      - Environment: setup/environment.md
+    - Git: setup/git.md
+    - Git SVN: setup/git-svn.md
+    - Environment: setup/environment.md
   - Interfaces:
-      - Command Line: interfaces/cli.md
-      - Git Plugin: interfaces/plugin.md
-      - Package API: interfaces/api.md
+    - Command Line: interfaces/cli.md
+    - Git Plugin: interfaces/plugin.md
+    - Package API: interfaces/api.md
+    - Models: interfaces/models.md
   - Use Cases:
-      - Replacing Submodules: use-cases/submodules.md
-      - Tracking Branches: use-cases/branch-tracking.md
-      - Linking Feature Branches: use-cases/linked-features.md
-      - Build System Integration: use-cases/build-integration.md
-      - Sparse Checkouts: use-cases/sparse-checkouts.md
-      - Default Groups: use-cases/default-groups.md
+    - Replacing Submodules: use-cases/submodules.md
+    - Tracking Branches: use-cases/branch-tracking.md
+    - Linking Feature Branches: use-cases/linked-features.md
+    - Build System Integration: use-cases/build-integration.md
+    - Sparse Checkouts: use-cases/sparse-checkouts.md
+    - Default Groups: use-cases/default-groups.md
   - Extras:
-      - Git SVN Bridge: extras/git-svn-bridge.md
-      - Bundled Application: extras/bundled-application.md
+    - Git SVN Bridge: extras/git-svn-bridge.md
+    - Bundled Application: extras/bundled-application.md
   - About:
-      - Release Notes: about/changelog.md
-      - Contributing: about/contributing.md
-      - License: about/license.md
+    - Release Notes: about/changelog.md
+    - Contributing: about/contributing.md
+    - License: about/license.md