Add deprecation warning for link feature

docs/use-cases/multiple-links.md

@@ -4,14 +4,18 @@ This feature can be used to create as many symbolic links as you need from one r
 
 ## The syntax
 
-Let's say we have a simple project structure.
+Let's say we have a simple project structure:
 
+```text
 |- include
 |- src
 |- docs
+```
+
+with the following `gitman.yml`:
 
 ```yaml
-location: .gitman 
+location: .gitman
 
 sources:
   - repo: <URL of my_dependency repository>
@@ -24,13 +28,14 @@ sources:
 ```
 
 This will result in the following symbolic links:
+
 - `<root>/vendor/partial_repo` -> `<root>/.gitman/my_dependency/include`
 - `<root>/vendor/full_repo` -> `<root>/.gitman/my_dependency`
 
 ## Alternative syntax
 
 ```yaml
-location: vendor 
+location: vendor
 
 sources:
   - repo: <URL of my_dependency repository>

gitman.yml

@@ -6,7 +6,7 @@ sources:
     type: git
     sparse_paths:
       -
-    link:
+    link: demo/example
     links:
       -
     scripts:
@@ -53,7 +53,7 @@ sources_locked:
     type: git
     sparse_paths:
       -
-    link:
+    link: demo/example
     links:
       -
     scripts:

gitman/models/source.py

@@ -1,4 +1,5 @@
 import os
+import warnings
 from dataclasses import dataclass, field
 from typing import List, Optional
 
@@ -37,6 +38,11 @@ def __post_init__(self):
         else:
             self.name = str(self.name)
         self.type = self.type or 'git'
+        if self.link:
+            warnings.warn(
+                "'link' will be replaced with 'links' in version 3.0",
+                DeprecationWarning,
+            )
 
     def __repr__(self):
         return "<source {}>".format(self)

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "gitman"
-version = "2.3b4"
+version = "2.3b5"
 description = "A language-agnostic dependency manager using Git."
 
 license = "MIT"