skilleter-thingy 0.0.95__tar.gz → 0.0.97__tar.gz

{skilleter_thingy-0.0.95/skilleter_thingy.egg-info → skilleter_thingy-0.0.97}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: skilleter_thingy
-Version: 0.0.95
+Version: 0.0.97
 Summary: A collection of useful utilities, mainly aimed at making Git more friendly
 Author-email: John Skilleter <john@skilleter.org.uk>
 Project-URL: Home, https://skilleter.org.uk
@@ -36,43 +36,59 @@ This README just contains a summary of the functionality of each command.
 
 # Git Repo Management
 
-## multigit
+## Multigit
 
-Manage a collection of related git working trees.
+Multigit is a tool for managing a collection of related git working trees.
 
-This is intended for use in a situation where you have a collection of related git working trees organised in a directory hierarchy and not necessarily managed using git submodules or any other tool. It allows you to run git commands on multiple working trees at once, without navigating around the different working trees to do so.
+This is intended for use in a situation where you have a collection of related git working trees organised in a directory hierarchy which aren't managed using git submodules or any other tool. It allows you to run git commands on multiple working trees at once, without navigating around the different working trees to do so and to select which working trees commands are run in.
+
+## Initialisation
 
 Start by running ensuring that the default branch (e.g. `main`) is checked out in each of the working trees and, in the top-level directory, run `multigit init` to create the configuration file which, by default is called `multigit.toml` - this is just a text file that sets the configuration for each working tree in terms of name, origin, default branch and location.
 
+## Multigit Command Line
+
 The multigit command line format is:
 
     multigit OPTIONS COMMAND
 
-Where COMMAND is an internal multigit command if it starts with a '+' and is a git command otherwise.
+Where COMMAND is an internal multigit command if it starts with a `+` and is a git command otherwise (including the additional git commands described in this document).
 
-By default, when multigit is invoked with a git command, it runs a the command in each of the working trees selected by the command line options passed to multigit (if no options are specified then the command is run in all the working trees. 
+By default, when multigit is invoked with a git command, it runs a the command in each of the working trees selected by the command line options passed to multigit (if no options are specified then the command is run in *all* the working trees.
 
 The command takes a number of options that can be used to select the list of working trees that each of the subcommands that it supports runs in:
 
-*--repos / -r* Allows a list of working trees to be specfied, either as the full or relative path, the name or a wildcard.
+`--repos REPO` / `-r REPO` Allows a list of working trees to be specfied, either by path, name or a wildcard matching either.
+
+`--modified` / `-m` Run only in working trees containing locally modified files
+
+`--branched` / `-b` Run only in working trees where the current branch that is checked out is NOT the default branch
 
-*--modified / -m* Run only in working trees containing locally modified files
+`--tag TAG` / `-t TAG` Run only in working trees that are tagged with the specified tag
 
-*--branched / -b* Run only working trees where the current branch that is checked out is NOT the default branch
+These options are AND-ed together, so specifying `--modified --branched --tag WOMBAT` will select only working trees that are modified AND branched AND tagged with `WOMBAT`, but the parameters to the `--repos` and `--tag` options are OR-ed together, so specifying `--tag WOMBAT --tag EMU` will select repos that are tagged as `WOMBAT` *OR* `EMU`.
+
+Multigit tags are stored in the configuration file, not within the working tree and each working tree can have multiple tags.
+
+## Multigit Commands
 
 Multigit supports a small list of subcommands, each of which are prefixed with a `+` to distinguish them from Git commands:
 
-*+init* - Create or update the configuration file
+`+init` - Create or update the configuration file
+
+`+dir` - Given the name of a working tree, output the location within the multigit tree of that working tree if the name matches uniquely, or the name of the directory where the multigit configuration file resides if no parameter is specified.
 
-*+dir* - Given the name of a working tree, output the location within the multigit tree of that working tree if the name matches uniquely, or the name of the directory where the multigit configuration file resides if no parameter is specified.
+`+config` - Print the name and location of the multigit configuration file.
 
-*+config* - Print the name and location of the multigit configuration file.
+`+tag TAG` - If no tag specified list tags applied to the specified working trees. If a tag *is* specified, then *apply* the tag to the specified working trees.
 
-Any command not prefixed with '+' is run in each of the working trees (filtered by the various multigit options) as a git command.
+`+untag TAG` - Remove the tag from the specified working trees (do nothing if the tag is not applied in the first place).
+
+Any command *not* prefixed with `+` is run in each of the working trees (filtered by the various multigit options) as a git command.
 
 For example; `multigit -m commit -ab` would run `git commit -a` in each of the working trees that is branched and contains modified files.
 
-The `+dir` command can be used with shell aliases (or their equivalent in the user's shell of choice) to create an alias to run, for example, `cd (multigit +dir "$@")` (Bash) or `cd (multigit +dir $argv)` (for the Fish shell) that would cd to the top level direcory.
+The `+dir` command can be used with shell aliases (or their equivalent in the user's shell of choice) to create an alias to run, for example, `cd (multigit +dir "$@")` (Bash) or `cd (multigit +dir $argv)` (for the Fish shell) that would cd to the top level directory.
 
 # Miscellaneous Git Utilities
 
@@ -82,23 +98,96 @@ Output a string containing colour-coded shell nesting level, current directory a
 
 # Git Extensions
 
-Due to the way that the git command works, these can be run as they were additional git subcommands.
+Due to the way that the git command works, these can be run as they were additional git subcommands, although, due to a limitation in git, the only things that does not work is the `--help` option where the command has to be run with a hyphen between `git` and the subcommand - for example `git ca --help` does not work, but `git-ca --help` does.
+
+## Branch Names
+
+Where one of the git extensions takes an existing branch name as a parameter, the branch name can be abbreviated and the abbreviated form is expanded according to the following rules:
+
+* If the specified branch name exactly matches an existing branch, tag or commit ID then that is used (this includes remote branches where appropriate, if no local branches match).
+* Otherwise, the branch name is compared to existing branches (again, including remote branches where appropriate, if no local branches match) and, if the specified name uniquely partially matches an existing branch (optionally using `*` and `?` wildcard characters) that branch is used. If it matches multiple branches than an error is reported.
+
+For example, given a repo with the following branches:
+
+        origin/wombat
+        origin/platypus
+        wombat
+        emu
+        battery
+        chaos
+
+Then:
+
+* 'emu' will match 'emu'
+* 'wombat' will match 'wombat' but not 'origin/wombat' since the local branch takes precedence
+* 'at' will match both 'wombat' and 'battery' and will report an error
+* 'pus' will match 'origin/platypus'
+
+This is most useful where branches contain ticket numbers so, for instance given a branch called `feature/SKIL-103` you can check it out using `git co 103` assuming no other local branches contain `103` in their name.
+
+Note that the concept of the default branch `DEFAULT` mentioned above *only* applies when using the `multigit` command, although some of the commands will treat branches called `master` or `main` as special cases (see the individual command documentation).
 
 ## git ca
 
 Improved version of 'git commit --amend'. Updates files that are already in the commit and, optionally, adds and commits additional files.
 
+        usage: git-ca [-h] [--added] [--all] [--everything] [--ignored] [--patch] [--verbose] [--dry-run] [files ...]
+
+        positional arguments:
+          files             List of files to add to the commit
+
+        options:
+          -h, --help        show this help message and exit
+          --added, -A       Update files in the current commit, including files added with `git add`
+          --all, -a         Append all locally-modified, tracked files to the current commit
+          --everything, -e  Append all modified and untracked files to the current commit (implies `~--all`)
+          --ignored, -i     Include files normally hidden by `.gitignore`
+          --patch, -p       Use the interactive patch selection interface to chose which changes to commit.
+          --verbose, -v     Verbose mode
+          --dry-run, -D     Dry-run
+
 ## git cleanup
 
 List or delete branches that have already been merged and delete tracking branches that are no longer on the remote.
 
+        git-cleanup [-h] [--delete] [--master MASTER] [--force] [--unmerged] [--yes] [--debug] [branches ...]
+
+        positional arguments:
+
+        branches              List of branches to check (default is all branches)
+
+        options:
+        -h, --help            show this help message and exit
+        --delete, -d          Delete all branches that have been merged
+        --master MASTER, -m MASTER, --main MASTER
+                              Specify the master branch (Attempts to read this from GitLab or defaults to "develop" if present or "master" or "main" otherwise
+        --force, -f           Allow protected branches (e.g. master) to be removed
+        --unmerged, -u        List branches that have NOT been merged
+        --yes, -y             Assume "yes" in response to any prompts (e.g. to delete branches)
+        --debug               Enable debug output
+
 ## git co
 
-Equivalent to 'git checkout' but with intelligent branch matching, so specifying a partial branch name will work if it uniquely matches an existing branch
+Equivalent to `git checkout` but with enhanced branch matching as described above. The command does not support the full range of options supported by the `git checkout` comamnd which should still be used where additional functionality is required.
+
+        git-co [-h] [--branch] [--update] [--rebase] [--force] [--exact] [--debug] branchname
+
+        positional arguments:
+
+        branchname    The branch name (or a partial name that matches uniquely against a local branch, remote branch, commit ID or tag)
+
+        options:
+        -h, --help    show this help message and exit
+        --branch, -b  Create the specified branch
+        --update, -u  If a remote branch exists, delete any local branch and check out the remote version
+        --rebase, -r  Rebase the branch onto its parent after checking it out
+        --force, -f   When using the update option, recreate the local branch even if it is owned by the current user (based on the author of the most recent commit)
+        --exact, -e   Do not use branch name matching - check out the branch as specified (if it exists)
+        --debug       Enable debug output
 
 ## git parent
 
-Attempt to determine the parent branch for the specified branch (defaulting to the current one)
+Attempt to determine the parent branch for the specified branch (defaulting to the current one).
 
 ## git update
 

{skilleter_thingy-0.0.95 → skilleter_thingy-0.0.97}/README.md

@@ -14,43 +14,59 @@ This README just contains a summary of the functionality of each command.
 
 # Git Repo Management
 
-## multigit
+## Multigit
 
-Manage a collection of related git working trees.
+Multigit is a tool for managing a collection of related git working trees.
 
-This is intended for use in a situation where you have a collection of related git working trees organised in a directory hierarchy and not necessarily managed using git submodules or any other tool. It allows you to run git commands on multiple working trees at once, without navigating around the different working trees to do so.
+This is intended for use in a situation where you have a collection of related git working trees organised in a directory hierarchy which aren't managed using git submodules or any other tool. It allows you to run git commands on multiple working trees at once, without navigating around the different working trees to do so and to select which working trees commands are run in.
+
+## Initialisation
 
 Start by running ensuring that the default branch (e.g. `main`) is checked out in each of the working trees and, in the top-level directory, run `multigit init` to create the configuration file which, by default is called `multigit.toml` - this is just a text file that sets the configuration for each working tree in terms of name, origin, default branch and location.
 
+## Multigit Command Line
+
 The multigit command line format is:
 
     multigit OPTIONS COMMAND
 
-Where COMMAND is an internal multigit command if it starts with a '+' and is a git command otherwise.
+Where COMMAND is an internal multigit command if it starts with a `+` and is a git command otherwise (including the additional git commands described in this document).
 
-By default, when multigit is invoked with a git command, it runs a the command in each of the working trees selected by the command line options passed to multigit (if no options are specified then the command is run in all the working trees. 
+By default, when multigit is invoked with a git command, it runs a the command in each of the working trees selected by the command line options passed to multigit (if no options are specified then the command is run in *all* the working trees.
 
 The command takes a number of options that can be used to select the list of working trees that each of the subcommands that it supports runs in:
 
-*--repos / -r* Allows a list of working trees to be specfied, either as the full or relative path, the name or a wildcard.
+`--repos REPO` / `-r REPO` Allows a list of working trees to be specfied, either by path, name or a wildcard matching either.
+
+`--modified` / `-m` Run only in working trees containing locally modified files
+
+`--branched` / `-b` Run only in working trees where the current branch that is checked out is NOT the default branch
 
-*--modified / -m* Run only in working trees containing locally modified files
+`--tag TAG` / `-t TAG` Run only in working trees that are tagged with the specified tag
 
-*--branched / -b* Run only working trees where the current branch that is checked out is NOT the default branch
+These options are AND-ed together, so specifying `--modified --branched --tag WOMBAT` will select only working trees that are modified AND branched AND tagged with `WOMBAT`, but the parameters to the `--repos` and `--tag` options are OR-ed together, so specifying `--tag WOMBAT --tag EMU` will select repos that are tagged as `WOMBAT` *OR* `EMU`.
+
+Multigit tags are stored in the configuration file, not within the working tree and each working tree can have multiple tags.
+
+## Multigit Commands
 
 Multigit supports a small list of subcommands, each of which are prefixed with a `+` to distinguish them from Git commands:
 
-*+init* - Create or update the configuration file
+`+init` - Create or update the configuration file
+
+`+dir` - Given the name of a working tree, output the location within the multigit tree of that working tree if the name matches uniquely, or the name of the directory where the multigit configuration file resides if no parameter is specified.
 
-*+dir* - Given the name of a working tree, output the location within the multigit tree of that working tree if the name matches uniquely, or the name of the directory where the multigit configuration file resides if no parameter is specified.
+`+config` - Print the name and location of the multigit configuration file.
 
-*+config* - Print the name and location of the multigit configuration file.
+`+tag TAG` - If no tag specified list tags applied to the specified working trees. If a tag *is* specified, then *apply* the tag to the specified working trees.
 
-Any command not prefixed with '+' is run in each of the working trees (filtered by the various multigit options) as a git command.
+`+untag TAG` - Remove the tag from the specified working trees (do nothing if the tag is not applied in the first place).
+
+Any command *not* prefixed with `+` is run in each of the working trees (filtered by the various multigit options) as a git command.
 
 For example; `multigit -m commit -ab` would run `git commit -a` in each of the working trees that is branched and contains modified files.
 
-The `+dir` command can be used with shell aliases (or their equivalent in the user's shell of choice) to create an alias to run, for example, `cd (multigit +dir "$@")` (Bash) or `cd (multigit +dir $argv)` (for the Fish shell) that would cd to the top level direcory.
+The `+dir` command can be used with shell aliases (or their equivalent in the user's shell of choice) to create an alias to run, for example, `cd (multigit +dir "$@")` (Bash) or `cd (multigit +dir $argv)` (for the Fish shell) that would cd to the top level directory.
 
 # Miscellaneous Git Utilities
 
@@ -60,23 +76,96 @@ Output a string containing colour-coded shell nesting level, current directory a
 
 # Git Extensions
 
-Due to the way that the git command works, these can be run as they were additional git subcommands.
+Due to the way that the git command works, these can be run as they were additional git subcommands, although, due to a limitation in git, the only things that does not work is the `--help` option where the command has to be run with a hyphen between `git` and the subcommand - for example `git ca --help` does not work, but `git-ca --help` does.
+
+## Branch Names
+
+Where one of the git extensions takes an existing branch name as a parameter, the branch name can be abbreviated and the abbreviated form is expanded according to the following rules:
+
+* If the specified branch name exactly matches an existing branch, tag or commit ID then that is used (this includes remote branches where appropriate, if no local branches match).
+* Otherwise, the branch name is compared to existing branches (again, including remote branches where appropriate, if no local branches match) and, if the specified name uniquely partially matches an existing branch (optionally using `*` and `?` wildcard characters) that branch is used. If it matches multiple branches than an error is reported.
+
+For example, given a repo with the following branches:
+
+        origin/wombat
+        origin/platypus
+        wombat
+        emu
+        battery
+        chaos
+
+Then:
+
+* 'emu' will match 'emu'
+* 'wombat' will match 'wombat' but not 'origin/wombat' since the local branch takes precedence
+* 'at' will match both 'wombat' and 'battery' and will report an error
+* 'pus' will match 'origin/platypus'
+
+This is most useful where branches contain ticket numbers so, for instance given a branch called `feature/SKIL-103` you can check it out using `git co 103` assuming no other local branches contain `103` in their name.
+
+Note that the concept of the default branch `DEFAULT` mentioned above *only* applies when using the `multigit` command, although some of the commands will treat branches called `master` or `main` as special cases (see the individual command documentation).
 
 ## git ca
 
 Improved version of 'git commit --amend'. Updates files that are already in the commit and, optionally, adds and commits additional files.
 
+        usage: git-ca [-h] [--added] [--all] [--everything] [--ignored] [--patch] [--verbose] [--dry-run] [files ...]
+
+        positional arguments:
+          files             List of files to add to the commit
+
+        options:
+          -h, --help        show this help message and exit
+          --added, -A       Update files in the current commit, including files added with `git add`
+          --all, -a         Append all locally-modified, tracked files to the current commit
+          --everything, -e  Append all modified and untracked files to the current commit (implies `~--all`)
+          --ignored, -i     Include files normally hidden by `.gitignore`
+          --patch, -p       Use the interactive patch selection interface to chose which changes to commit.
+          --verbose, -v     Verbose mode
+          --dry-run, -D     Dry-run
+
 ## git cleanup
 
 List or delete branches that have already been merged and delete tracking branches that are no longer on the remote.
 
+        git-cleanup [-h] [--delete] [--master MASTER] [--force] [--unmerged] [--yes] [--debug] [branches ...]
+
+        positional arguments:
+
+        branches              List of branches to check (default is all branches)
+
+        options:
+        -h, --help            show this help message and exit
+        --delete, -d          Delete all branches that have been merged
+        --master MASTER, -m MASTER, --main MASTER
+                              Specify the master branch (Attempts to read this from GitLab or defaults to "develop" if present or "master" or "main" otherwise
+        --force, -f           Allow protected branches (e.g. master) to be removed
+        --unmerged, -u        List branches that have NOT been merged
+        --yes, -y             Assume "yes" in response to any prompts (e.g. to delete branches)
+        --debug               Enable debug output
+
 ## git co
 
-Equivalent to 'git checkout' but with intelligent branch matching, so specifying a partial branch name will work if it uniquely matches an existing branch
+Equivalent to `git checkout` but with enhanced branch matching as described above. The command does not support the full range of options supported by the `git checkout` comamnd which should still be used where additional functionality is required.
+
+        git-co [-h] [--branch] [--update] [--rebase] [--force] [--exact] [--debug] branchname
+
+        positional arguments:
+
+        branchname    The branch name (or a partial name that matches uniquely against a local branch, remote branch, commit ID or tag)
+
+        options:
+        -h, --help    show this help message and exit
+        --branch, -b  Create the specified branch
+        --update, -u  If a remote branch exists, delete any local branch and check out the remote version
+        --rebase, -r  Rebase the branch onto its parent after checking it out
+        --force, -f   When using the update option, recreate the local branch even if it is owned by the current user (based on the author of the most recent commit)
+        --exact, -e   Do not use branch name matching - check out the branch as specified (if it exists)
+        --debug       Enable debug output
 
 ## git parent
 
-Attempt to determine the parent branch for the specified branch (defaulting to the current one)
+Attempt to determine the parent branch for the specified branch (defaulting to the current one).
 
 ## git update
 

{skilleter_thingy-0.0.95 → skilleter_thingy-0.0.97}/pyproject.toml

@@ -7,7 +7,7 @@ name = "skilleter_thingy"
 
 # Version must be incremented to install updated Thingy
 
-version = "0.0.95"
+version = "0.0.97"
 
 authors = [
     {name="John Skilleter", email="john@skilleter.org.uk"},