...

lib/develop/gittools/README.md

@@ -1,6 +1,84 @@
 # Git Tools Module
 
-### Get a specific path starting from url
+## GitTools HeroScript 
+
+### `!!git.define`
+
+Configure or retrieve a `GitStructure`, if not set will use the default
+
+```heroscript
+!!git.define
+    coderoot:'/tmp/code' //when we overrule the location, the default is ~/code
+    light:true //depth of git clone is 1
+    log:true 
+    debug:false //give more error reporting
+    offline:false //makes sure will not try to get to internet, but do all locally
+    ssh_key_path:'' //if a specific ssh key is needed
+    reload:false //if set then will remove cache and load full status, this is slow !
+```
+
+### `!!git.clone`
+
+Clones a Git repository from a specified URL into the configured coderoot.
+
+```heroscript
+!!git.clone
+	url: 'https://github.com/freeflowuniverse/test_repo.git'
+    pull: true // Optional: if true, pulls latest changes after cloning
+    reset: false // Optional: if true, resets the repository before cloning/pulling
+	light: true // Optional: if true, clones only the last history (default: is from git structure as defined above)
+	recursive: false // Optional: if true, also clones submodules (default: false)
+```
+
+### `!!git.repo_action`
+
+Performs various Git operations on an existing repository, the filter matches more than 1 repo, gives error if none found
+
+```heroscript
+!!git.repo_action 
+    filter: 'freeflowuniverse/test_repo'
+	action: 'pull' // pull, commit, push, reset, branch_create, branch_switch, tag_create, tag_switch, delete
+	message: 'feat: Added new feature' // Optional: for 'commit' action
+	branchname: 'feature-branch' // Optional: for 'branch_create' or 'branch_switch' actions
+	tagname: 'v1.0.0' // Optional: for 'tag_create' or 'tag_switch' actions
+	submodules: true // Optional: for 'pull' action, if true, also updates submodules
+    error_ignore: false // Optional: if true, ignores errors during the action and continue for the next repo
+```
+
+**Parameters:**
+
+- `filter` (string, **required**): A substring to filter repositories by name or relative path. This can match multiple repositories.
+- `action` (string, **required**): The Git operation to perform. Valid values:
+    -   `pull`: Pulls latest changes from the remote.
+    -   `commit`: Commits staged changes. Requires `message`.
+    -   `push`: Pushes local commits to the remote.
+    -   `reset`: Resets all local changes (hard reset).
+    -   `branch_create`: Creates a new branch. Requires `branchname`.
+    -   `branch_switch`: Switches to an existing branch. Requires `branchname`.
+    -   `tag_create`: Creates a new tag. Requires `tagname`.
+    -   `tag_switch`: Switches to an existing tag. Requires `tagname`.
+    -   `delete`: Deletes the local repository.
+
+### `!!git.list`
+
+Lists known Git repositories managed by the `gittools` module.
+
+```heroscript
+!!git.list
+	filter: 'my_project' // Optional: filter by repository name or path
+    reload: true //if true then will check the status of those repo's against the remote's
+```
+
+###  `!!git.reload`
+
+Forces a reload of all Git repositories in the cache, re-scanning the `coderoot` and updating their statuses.
+
+```heroscript
+!!git.reload
+	filter: 'my_project' // Optional: filter by repository name or path
+```
+
+## Get a specific path starting from url
 
 below is powerful command, will get the repo, put on right location, you can force a pull or even reset everything