From 58fc9701be3e02e81a6281c966d322e2dc22b141 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Mon, 15 Dec 2025 09:03:06 +0800 Subject: [PATCH 01/12] small changes to docs and error messages --- README.md | 14 ++++++++------ src/gimmegit/_cli.py | 2 +- tests/functional/test_clone.py | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 478f48b..f9e3298 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ The new branch is based on the repo's main branch. To specify the base branch, u gimmegit -b / ``` -After working on the new branch for a while, you might want to merge remote changes from the base branch. To merge remote changes, run `git update-branch` in the clone directory. `update-branch` is a git alias that gimmegit created. +After working on the new branch for a while, you might want to merge remote changes from the base branch. To merge remote changes, run `git update-branch` in the clone directory. `update-branch` is a Git alias that gimmegit created. ### Example @@ -117,7 +117,7 @@ gimmegit https://github.com///tree/ This clones the repo `/` into a directory called `/-` and checks out the branch ``. -After working on the branch for a while, you might want to merge remote changes from the repo's main branch. To merge remote changes, run `git update-branch` in the clone directory. `update-branch` is a git alias that gimmegit created. +After working on the branch for a while, you might want to merge remote changes from the repo's main branch. To merge remote changes, run `git update-branch` in the clone directory. `update-branch` is a Git alias that gimmegit created. ### Example @@ -169,7 +169,7 @@ The new branch is based on the upstream repo's main branch. (Technically, it's b gimmegit -b -u / ``` -After working on the new branch for a while, you might want to merge changes from the upstream base branch. To merge changes from upstream, run `git update-branch` in the clone directory. `update-branch` is a git alias that gimmegit created. +After working on the new branch for a while, you might want to merge changes from the upstream base branch. To merge changes from upstream, run `git update-branch` in the clone directory. `update-branch` is a Git alias that gimmegit created. ### Example @@ -194,7 +194,8 @@ cd ../.. gimmegit -b 2.23-maintenance -u canonical dwilding/operator backport-docs # This does the same thing: -# gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance dwilding/operator backport-docs +# gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \ +# dwilding/operator backport-docs # Change to the second clone directory cd operator/dwilding-backport-docs @@ -246,7 +247,7 @@ gimmegit -u https://github.com///tree/ This clones ``'s fork of `/` into a directory called `/-` and checks out the branch ``. -After working on the branch for a while, you might want to merge changes from the upstream repo's main branch. To merge changes from upstream, run `git update-branch` in the clone directory. `update-branch` is a git alias that gimmegit created. +After working on the branch for a while, you might want to merge changes from the upstream repo's main branch. To merge changes from upstream, run `git update-branch` in the clone directory. `update-branch` is a Git alias that gimmegit created. ### Example @@ -292,7 +293,8 @@ If the branch wasn't based on the upstream repo's main branch, use `-b` to set t gimmegit -b 2.23-maintenance -u canonical https://github.com/dwilding/operator/tree/backport-fix # This does the same thing: -# gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance https://github.com/dwilding/operator/tree/backport-fix +# gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \ +# https://github.com/dwilding/operator/tree/backport-fix # If GIMMEGIT_GITHUB_TOKEN is set, this also does the same thing: # gimmegit -b 2.23-maintenance https://github.com/dwilding/operator/tree/backport-fix diff --git a/src/gimmegit/_cli.py b/src/gimmegit/_cli.py index 18ce065..6a0e0d0 100644 --- a/src/gimmegit/_cli.py +++ b/src/gimmegit/_cli.py @@ -165,7 +165,7 @@ def primary_usage(args: argparse.Namespace, cloning_args: list[str]) -> None: candidate = _inspect.get_repo_from_latest_dir(Path.cwd()) if candidate and _status.get_status(candidate): logger.error( - "The working directory has a gimmegit clone. Try running gimmegit in the parent directory." + "The working directory contains a gimmegit clone. Try running gimmegit in the parent directory." ) sys.exit(1) try: diff --git a/tests/functional/test_clone.py b/tests/functional/test_clone.py index 9a56354..8f18b2c 100644 --- a/tests/functional/test_clone.py +++ b/tests/functional/test_clone.py @@ -175,7 +175,7 @@ def test_in_project_dir(uv_run, test_dir): """ assert result.stdout == expected_stdout expected_stderr = """\ -Error: The working directory has a gimmegit clone. Try running gimmegit in the parent directory. +Error: The working directory contains a gimmegit clone. Try running gimmegit in the parent directory. """ assert result.stderr == expected_stderr assert not (working_dir / "jubilant").exists() From 786ed8dca2ad062ffce5120275e09e00fa9a4b4a Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Mon, 15 Dec 2025 09:03:18 +0800 Subject: [PATCH 02/12] expand help output --- src/gimmegit/_help.py | 97 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 87 insertions(+), 10 deletions(-) diff --git a/src/gimmegit/_help.py b/src/gimmegit/_help.py index a8035dc..a9b5802 100644 --- a/src/gimmegit/_help.py +++ b/src/gimmegit/_help.py @@ -1,15 +1,92 @@ help = """\ -Usage: - gimmegit [] [] [-- ] - gimmegit [] [-- ] +gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone in a +dedicated directory, based on the project, owner, and branch name. -Show status: - gimmegit [--color {auto,always,never}] +▶ USAGE +gimmegit [] [] [-- ] Clone a GitHub repo and check out + a new branch. +gimmegit [] [-- ] Clone a GitHub repo and check out + an existing branch. -Additional commands: - gimmegit -h - gimmegit --help +▶ POSITIONAL ARGUMENTS + One of: + • /. For example, 'dwilding/frogtab'. is optional if the + GIMMEGIT_GITHUB_TOKEN environment variable contains a personal access token. + • A repo URL. For example, 'https://github.com/dwilding/frogtab'. + The name of a branch that doesn't already exist. gimmegit generates a branch name + if you omit . For example, 'snapshot0801' on August 1. + A URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. - gimmegit --version +▶ DIRECTORY STRUCTURE +When you clone a repo, gimmegit creates a dedicated directory for the clone: + . + └── The project directory. For example, 'frogtab'. + └── - The clone directory. For example, 'dwilding-my-feature'. - gimmegit [--ssh {auto,always,never}] --parse-url """ +If the clone directory already exists, gimmegit skips cloning. If the clone directory would be +inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error if it +detects that the working directory is a project directory (specifically, if the latest modified +subdirectory is a gimmegit clone). + +▶ BRANCH MAPPING +When you clone a repo, gimmegit creates a Git alias 'update-branch' that merges remote changes +from the base branch. The base branch is the repo's main branch. If the repo is a fork and +GIMMEGIT_GITHUB_TOKEN is set, the base branch is the upstream version of the repo's main branch. + +For new branches: +• gimmegit branches off the base branch. +• gimmegit doesn't push the branch to GitHub. + +▶ OPTIONS +-u, --upstream-owner Owner of the base branch. For example, if you're cloning a fork of + a repo from github.com/canonical, provide '-u canonical'. If you + provide -u, gimmegit doesn't try to use GIMMEGIT_GITHUB_TOKEN to + look for an upstream repo. +-b, --base-branch Name or URL of the base branch. If '-b ', gimmegit uses + instead of the repo's main branch (or upstream main). + If '-b https://github.com///tree/', + gimmegit sets the owner & name of the base branch, overriding -u. +--no-pre-commit Don't try to install a pre-commit hook after cloning the repo. +--allow-outer-repo Clone the repo even if the clone directory will be inside a repo. +--force-project-dir Create the project directory even if gimmegit finds a gimmegit + clone in the working directory. +--ssh auto|always|never Controls whether Git remotes use SSH or HTTPS. + Default: auto - use SSH if ~/.ssh contains a SSH key. +--color auto|always|never Controls whether the output has colored text. + Default: auto - use colors if the NO_COLOR environment variable is + empty and the output is going to a terminal. +--return-dir Output the clone directory path to stdout and send full progress + to stderr. + +▶ GIT OPTIONS +gimmegit sets --no-tags when cloning. To provide extra git-clone options, use '-- '. +For example, to clone tags, use '-- --tags'. + +▶ PRE-COMMIT +If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook after +cloning the repo. For more information, see https://pre-commit.com/. + +▶ ADDITIONAL COMMANDS +gimmegit [--color auto|always|never] Display the branch mapping if the working + directory is inside a gimmegit clone. +gimmegit -c | --compare Compare branches in GitHub if the working + directory is inside a gimmegit clone. +gimmegit -h | --help Display a summary of how to use gimmegit. +gimmegit --version Display the installed version of gimmegit. +gimmegit [--ssh auto|always|never] --parse-url Display a JSON representation of a GitHub + URL. Intended for extensions to gimmegit. + +▶ EXAMPLES +# Clone https://github.com/dwilding/frogtab and check out a new branch +gimmegit dwilding/frogtab my-feature # branching off main +gimmegit -b candidate dwilding/frogtab bump-version # branching off a dev branch + +# Clone the same repo and check out an existing branch +gimmegit https://github.com/dwilding/frogtab/tree/fix-something + +# Clone dwilding's fork of https://github.com/canonical/operator and check out a new branch +gimmegit -u canonical dwilding/operator update-docs # branching off upstream main +gimmegit -b 2.23-maintenance -u canonical \\ # branching off an upstream dev branch + dwilding/operator backport-docs +gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \\ # same as previous + dwilding/operator backport-docs""" From f5f124184f71cdd4054ffadd5f2a428f9c22ea81 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Mon, 15 Dec 2025 09:10:01 +0800 Subject: [PATCH 03/12] fix grammar --- src/gimmegit/_help.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/gimmegit/_help.py b/src/gimmegit/_help.py index a9b5802..84f03b5 100644 --- a/src/gimmegit/_help.py +++ b/src/gimmegit/_help.py @@ -51,7 +51,7 @@ --force-project-dir Create the project directory even if gimmegit finds a gimmegit clone in the working directory. --ssh auto|always|never Controls whether Git remotes use SSH or HTTPS. - Default: auto - use SSH if ~/.ssh contains a SSH key. + Default: auto - use SSH if ~/.ssh contains an SSH key. --color auto|always|never Controls whether the output has colored text. Default: auto - use colors if the NO_COLOR environment variable is empty and the output is going to a terminal. From d018041a4ff928ff74a89141a750286029717833 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Mon, 15 Dec 2025 09:11:52 +0800 Subject: [PATCH 04/12] add help output to README --- README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/README.md b/README.md index f822354..2cf3c86 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ In this README: - [Clone a fork and create a branch](#clone-a-fork-and-create-a-branch) - [Clone a fork on an existing branch](#clone-a-fork-on-an-existing-branch) - [Provide clone options](#provide-clone-options) + - [Command reference](#command-reference) ## Install gimmegit @@ -296,3 +297,99 @@ To provide [clone options](https://git-scm.com/docs/git-clone#_options) to gimme # create a branch called update-profile, cloning with --recurse-submodules gimmegit -u canonical dwilding/charmcraft update-profile -- --recurse-submodules ``` + +# Command reference + +```text +gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone in a +dedicated directory, based on the project, owner, and branch name. + +▶ USAGE +gimmegit [] [] [-- ] Clone a GitHub repo and check out + a new branch. +gimmegit [] [-- ] Clone a GitHub repo and check out + an existing branch. + +▶ POSITIONAL ARGUMENTS + One of: + • /. For example, 'dwilding/frogtab'. is optional if the + GIMMEGIT_GITHUB_TOKEN environment variable contains a personal access token. + • A repo URL. For example, 'https://github.com/dwilding/frogtab'. + The name of a branch that doesn't already exist. gimmegit generates a branch name + if you omit . For example, 'snapshot0801' on August 1. + A URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. + +▶ DIRECTORY STRUCTURE +When you clone a repo, gimmegit creates a dedicated directory for the clone: + . + └── The project directory. For example, 'frogtab'. + └── - The clone directory. For example, 'dwilding-my-feature'. + +If the clone directory already exists, gimmegit skips cloning. If the clone directory would be +inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error if it +detects that the working directory is a project directory (specifically, if the latest modified +subdirectory is a gimmegit clone). + +▶ BRANCH MAPPING +When you clone a repo, gimmegit creates a Git alias 'update-branch' that merges remote changes +from the base branch. The base branch is the repo's main branch. If the repo is a fork and +GIMMEGIT_GITHUB_TOKEN is set, the base branch is the upstream version of the repo's main branch. + +For new branches: +• gimmegit branches off the base branch. +• gimmegit doesn't push the branch to GitHub. + +▶ OPTIONS +-u, --upstream-owner Owner of the base branch. For example, if you're cloning a fork of + a repo from github.com/canonical, provide '-u canonical'. If you + provide -u, gimmegit doesn't try to use GIMMEGIT_GITHUB_TOKEN to + look for an upstream repo. +-b, --base-branch Name or URL of the base branch. If '-b ', gimmegit uses + instead of the repo's main branch (or upstream main). + If '-b https://github.com///tree/', + gimmegit sets the owner & name of the base branch, overriding -u. +--no-pre-commit Don't try to install a pre-commit hook after cloning the repo. +--allow-outer-repo Clone the repo even if the clone directory will be inside a repo. +--force-project-dir Create the project directory even if gimmegit finds a gimmegit + clone in the working directory. +--ssh auto|always|never Controls whether Git remotes use SSH or HTTPS. + Default: auto - use SSH if ~/.ssh contains an SSH key. +--color auto|always|never Controls whether the output has colored text. + Default: auto - use colors if the NO_COLOR environment variable is + empty and the output is going to a terminal. +--return-dir Output the clone directory path to stdout and send full progress + to stderr. + +▶ GIT OPTIONS +gimmegit sets --no-tags when cloning. To provide extra git-clone options, use '-- '. +For example, to clone tags, use '-- --tags'. + +▶ PRE-COMMIT +If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook after +cloning the repo. For more information, see https://pre-commit.com/. + +▶ ADDITIONAL COMMANDS +gimmegit [--color auto|always|never] Display the branch mapping if the working + directory is inside a gimmegit clone. +gimmegit -c | --compare Compare branches in GitHub if the working + directory is inside a gimmegit clone. +gimmegit -h | --help Display a summary of how to use gimmegit. +gimmegit --version Display the installed version of gimmegit. +gimmegit [--ssh auto|always|never] --parse-url Display a JSON representation of a GitHub + URL. Intended for extensions to gimmegit. + +▶ EXAMPLES +# Clone https://github.com/dwilding/frogtab and check out a new branch +gimmegit dwilding/frogtab my-feature # branching off main +gimmegit -b candidate dwilding/frogtab bump-version # branching off a dev branch + +# Clone the same repo and check out an existing branch +gimmegit https://github.com/dwilding/frogtab/tree/fix-something + +# Clone dwilding's fork of https://github.com/canonical/operator and check out a new branch +gimmegit -u canonical dwilding/operator update-docs # branching off upstream main +gimmegit -b 2.23-maintenance -u canonical \ # branching off an upstream dev branch + dwilding/operator backport-docs +gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \ # same as previous + dwilding/operator backport-docs +``` From c28edec1093bc73a24f2b7802502c63486ec73e8 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Thu, 18 Dec 2025 23:51:57 +0800 Subject: [PATCH 05/12] make help output more readable --- README.md | 144 +++++++++++++++++++++++++----------------- src/gimmegit/_help.py | 144 +++++++++++++++++++++++++----------------- 2 files changed, 172 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index 2cf3c86..058310f 100644 --- a/README.md +++ b/README.md @@ -301,95 +301,123 @@ gimmegit -u canonical dwilding/charmcraft update-profile -- --recurse-submodules # Command reference ```text -gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone in a -dedicated directory, based on the project, owner, and branch name. +gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone +in a dedicated directory, based on the project, owner, and branch name. + ▶ USAGE -gimmegit [] [] [-- ] Clone a GitHub repo and check out - a new branch. -gimmegit [] [-- ] Clone a GitHub repo and check out - an existing branch. - -▶ POSITIONAL ARGUMENTS - One of: - • /. For example, 'dwilding/frogtab'. is optional if the - GIMMEGIT_GITHUB_TOKEN environment variable contains a personal access token. - • A repo URL. For example, 'https://github.com/dwilding/frogtab'. - The name of a branch that doesn't already exist. gimmegit generates a branch name - if you omit . For example, 'snapshot0801' on August 1. - A URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. + +gimmegit [] [] [-- ] (1) +gimmegit [] [-- ] (2) + +1. Clone a GitHub repo and check out a new branch. + is one of: + • /. For example, 'dwilding/frogtab'. is optional if the + GIMMEGIT_GITHUB_TOKEN environment variable contains a personal access token. + • A repo URL. For example, 'https://github.com/dwilding/frogtab'. + is the name of a branch that doesn't already exist. gimmegit generates a + branch name if you omit . For example, 'snapshot0801' on August 1. + +2. Clone a GitHub repo and check out an existing branch. + is a URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. + ▶ DIRECTORY STRUCTURE + When you clone a repo, gimmegit creates a dedicated directory for the clone: . └── The project directory. For example, 'frogtab'. └── - The clone directory. For example, 'dwilding-my-feature'. -If the clone directory already exists, gimmegit skips cloning. If the clone directory would be -inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error if it -detects that the working directory is a project directory (specifically, if the latest modified -subdirectory is a gimmegit clone). +If the clone directory already exists, gimmegit skips cloning. If the clone directory would +be inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error +if it detects that the working directory is a project directory (specifically, if the latest +modified subdirectory is a gimmegit clone). + ▶ BRANCH MAPPING -When you clone a repo, gimmegit creates a Git alias 'update-branch' that merges remote changes -from the base branch. The base branch is the repo's main branch. If the repo is a fork and -GIMMEGIT_GITHUB_TOKEN is set, the base branch is the upstream version of the repo's main branch. + +gimmegit creates a Git alias 'update-branch' that merges remote changes from the base branch. +The base branch is the repo's main branch. If the repo is a fork and GIMMEGIT_GITHUB_TOKEN is +set, the base branch is the upstream version of the repo's main branch. For new branches: -• gimmegit branches off the base branch. -• gimmegit doesn't push the branch to GitHub. + • gimmegit branches off the base branch. + • gimmegit doesn't push the branch to GitHub. + ▶ OPTIONS --u, --upstream-owner Owner of the base branch. For example, if you're cloning a fork of - a repo from github.com/canonical, provide '-u canonical'. If you - provide -u, gimmegit doesn't try to use GIMMEGIT_GITHUB_TOKEN to - look for an upstream repo. + +-u, --upstream-owner Owner of the base branch. For example, provide '-u canonical' + to clone a fork of a repo from https://github.com/canonical. + If you provide -u, gimmegit doesn't try to use + GIMMEGIT_GITHUB_TOKEN to look for an upstream repo. + -b, --base-branch Name or URL of the base branch. If '-b ', gimmegit uses instead of the repo's main branch (or upstream main). - If '-b https://github.com///tree/', - gimmegit sets the owner & name of the base branch, overriding -u. + If '-b https://github.com///tree/', + gimmegit sets the base branch and ignores -u. + --no-pre-commit Don't try to install a pre-commit hook after cloning the repo. ---allow-outer-repo Clone the repo even if the clone directory will be inside a repo. + +--allow-outer-repo Allow the clone directory to be inside a repo. + --force-project-dir Create the project directory even if gimmegit finds a gimmegit clone in the working directory. + --ssh auto|always|never Controls whether Git remotes use SSH or HTTPS. - Default: auto - use SSH if ~/.ssh contains an SSH key. + • auto (default): Use SSH if ~/.ssh contains an SSH key. + --color auto|always|never Controls whether the output has colored text. - Default: auto - use colors if the NO_COLOR environment variable is - empty and the output is going to a terminal. ---return-dir Output the clone directory path to stdout and send full progress - to stderr. + • auto (default): Use colors if the NO_COLOR environment + variable is empty and the output is going to a terminal. + +--return-dir Output the clone directory path to stdout and send full + progress to stderr. + ▶ GIT OPTIONS -gimmegit sets --no-tags when cloning. To provide extra git-clone options, use '-- '. + +gimmegit sets --no-tags when cloning. To provide extra clone options, use '-- '. For example, to clone tags, use '-- --tags'. + ▶ PRE-COMMIT -If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook after -cloning the repo. For more information, see https://pre-commit.com/. + +If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook +after cloning the repo. For more information, see https://pre-commit.com/. + ▶ ADDITIONAL COMMANDS -gimmegit [--color auto|always|never] Display the branch mapping if the working - directory is inside a gimmegit clone. -gimmegit -c | --compare Compare branches in GitHub if the working - directory is inside a gimmegit clone. -gimmegit -h | --help Display a summary of how to use gimmegit. -gimmegit --version Display the installed version of gimmegit. -gimmegit [--ssh auto|always|never] --parse-url Display a JSON representation of a GitHub - URL. Intended for extensions to gimmegit. -▶ EXAMPLES -# Clone https://github.com/dwilding/frogtab and check out a new branch -gimmegit dwilding/frogtab my-feature # branching off main -gimmegit -b candidate dwilding/frogtab bump-version # branching off a dev branch +gimmegit [--color auto|always|never] (1) +gimmegit -c | --compare (2) +gimmegit -h | --help (3) +gimmegit --version (4) +gimmegit [--ssh auto|always|never] --parse-url (5) -# Clone the same repo and check out an existing branch -gimmegit https://github.com/dwilding/frogtab/tree/fix-something +1. Display the branch mapping if the working directory is inside a gimmegit clone. +2. Compare branches in GitHub if the working directory is inside a gimmegit clone. +3. Display a summary of how to use gimmegit. +4. Display the installed version of gimmegit. +5. Display a JSON representation of a GitHub URL. Intended for extensions to gimmegit. -# Clone dwilding's fork of https://github.com/canonical/operator and check out a new branch -gimmegit -u canonical dwilding/operator update-docs # branching off upstream main -gimmegit -b 2.23-maintenance -u canonical \ # branching off an upstream dev branch - dwilding/operator backport-docs -gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \ # same as previous + +▶ EXAMPLES + +gimmegit dwilding/frogtab my-feature (1) +gimmegit -b candidate dwilding/frogtab bump-version (2) +gimmegit https://github.com/dwilding/frogtab/tree/fix-something (3) +gimmegit -u canonical dwilding/operator update-docs (4) +gimmegit -b 2.23-maintenance -u canonical dwilding/operator backport-docs (5) +gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \ (6) dwilding/operator backport-docs + +1. Clone https://github.com/dwilding/frogtab and check out a new branch, branching off main. +2. Clone the same repo and check out a new branch, branching off a dev branch. +3. Clone the same repo and check out an existing branch. +4. Clone dwilding's fork of https://github.com/canonical/operator and check out a new branch, + branching off upstream main. +5. Clone the same fork and check out a new branch, branching off an upstream dev branch. +6. Equivalent to (5). ``` diff --git a/src/gimmegit/_help.py b/src/gimmegit/_help.py index 84f03b5..174b118 100644 --- a/src/gimmegit/_help.py +++ b/src/gimmegit/_help.py @@ -1,92 +1,120 @@ help = """\ -gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone in a -dedicated directory, based on the project, owner, and branch name. +gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone +in a dedicated directory, based on the project, owner, and branch name. + ▶ USAGE -gimmegit [] [] [-- ] Clone a GitHub repo and check out - a new branch. -gimmegit [] [-- ] Clone a GitHub repo and check out - an existing branch. - -▶ POSITIONAL ARGUMENTS - One of: - • /. For example, 'dwilding/frogtab'. is optional if the - GIMMEGIT_GITHUB_TOKEN environment variable contains a personal access token. - • A repo URL. For example, 'https://github.com/dwilding/frogtab'. - The name of a branch that doesn't already exist. gimmegit generates a branch name - if you omit . For example, 'snapshot0801' on August 1. - A URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. + +gimmegit [] [] [-- ] (1) +gimmegit [] [-- ] (2) + +1. Clone a GitHub repo and check out a new branch. + is one of: + • /. For example, 'dwilding/frogtab'. is optional if the + GIMMEGIT_GITHUB_TOKEN environment variable contains a personal access token. + • A repo URL. For example, 'https://github.com/dwilding/frogtab'. + is the name of a branch that doesn't already exist. gimmegit generates a + branch name if you omit . For example, 'snapshot0801' on August 1. + +2. Clone a GitHub repo and check out an existing branch. + is a URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. + ▶ DIRECTORY STRUCTURE + When you clone a repo, gimmegit creates a dedicated directory for the clone: . └── The project directory. For example, 'frogtab'. └── - The clone directory. For example, 'dwilding-my-feature'. -If the clone directory already exists, gimmegit skips cloning. If the clone directory would be -inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error if it -detects that the working directory is a project directory (specifically, if the latest modified -subdirectory is a gimmegit clone). +If the clone directory already exists, gimmegit skips cloning. If the clone directory would +be inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error +if it detects that the working directory is a project directory (specifically, if the latest +modified subdirectory is a gimmegit clone). + ▶ BRANCH MAPPING -When you clone a repo, gimmegit creates a Git alias 'update-branch' that merges remote changes -from the base branch. The base branch is the repo's main branch. If the repo is a fork and -GIMMEGIT_GITHUB_TOKEN is set, the base branch is the upstream version of the repo's main branch. + +gimmegit creates a Git alias 'update-branch' that merges remote changes from the base branch. +The base branch is the repo's main branch. If the repo is a fork and GIMMEGIT_GITHUB_TOKEN is +set, the base branch is the upstream version of the repo's main branch. For new branches: -• gimmegit branches off the base branch. -• gimmegit doesn't push the branch to GitHub. + • gimmegit branches off the base branch. + • gimmegit doesn't push the branch to GitHub. + ▶ OPTIONS --u, --upstream-owner Owner of the base branch. For example, if you're cloning a fork of - a repo from github.com/canonical, provide '-u canonical'. If you - provide -u, gimmegit doesn't try to use GIMMEGIT_GITHUB_TOKEN to - look for an upstream repo. + +-u, --upstream-owner Owner of the base branch. For example, provide '-u canonical' + to clone a fork of a repo from https://github.com/canonical. + If you provide -u, gimmegit doesn't try to use + GIMMEGIT_GITHUB_TOKEN to look for an upstream repo. + -b, --base-branch Name or URL of the base branch. If '-b ', gimmegit uses instead of the repo's main branch (or upstream main). - If '-b https://github.com///tree/', - gimmegit sets the owner & name of the base branch, overriding -u. + If '-b https://github.com///tree/', + gimmegit sets the base branch and ignores -u. + --no-pre-commit Don't try to install a pre-commit hook after cloning the repo. ---allow-outer-repo Clone the repo even if the clone directory will be inside a repo. + +--allow-outer-repo Allow the clone directory to be inside a repo. + --force-project-dir Create the project directory even if gimmegit finds a gimmegit clone in the working directory. + --ssh auto|always|never Controls whether Git remotes use SSH or HTTPS. - Default: auto - use SSH if ~/.ssh contains an SSH key. + • auto (default): Use SSH if ~/.ssh contains an SSH key. + --color auto|always|never Controls whether the output has colored text. - Default: auto - use colors if the NO_COLOR environment variable is - empty and the output is going to a terminal. ---return-dir Output the clone directory path to stdout and send full progress - to stderr. + • auto (default): Use colors if the NO_COLOR environment + variable is empty and the output is going to a terminal. + +--return-dir Output the clone directory path to stdout and send full + progress to stderr. + ▶ GIT OPTIONS -gimmegit sets --no-tags when cloning. To provide extra git-clone options, use '-- '. + +gimmegit sets --no-tags when cloning. To provide extra clone options, use '-- '. For example, to clone tags, use '-- --tags'. + ▶ PRE-COMMIT -If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook after -cloning the repo. For more information, see https://pre-commit.com/. + +If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook +after cloning the repo. For more information, see https://pre-commit.com/. + ▶ ADDITIONAL COMMANDS -gimmegit [--color auto|always|never] Display the branch mapping if the working - directory is inside a gimmegit clone. -gimmegit -c | --compare Compare branches in GitHub if the working - directory is inside a gimmegit clone. -gimmegit -h | --help Display a summary of how to use gimmegit. -gimmegit --version Display the installed version of gimmegit. -gimmegit [--ssh auto|always|never] --parse-url Display a JSON representation of a GitHub - URL. Intended for extensions to gimmegit. -▶ EXAMPLES -# Clone https://github.com/dwilding/frogtab and check out a new branch -gimmegit dwilding/frogtab my-feature # branching off main -gimmegit -b candidate dwilding/frogtab bump-version # branching off a dev branch +gimmegit [--color auto|always|never] (1) +gimmegit -c | --compare (2) +gimmegit -h | --help (3) +gimmegit --version (4) +gimmegit [--ssh auto|always|never] --parse-url (5) + +1. Display the branch mapping if the working directory is inside a gimmegit clone. +2. Compare branches in GitHub if the working directory is inside a gimmegit clone. +3. Display a summary of how to use gimmegit. +4. Display the installed version of gimmegit. +5. Display a JSON representation of a GitHub URL. Intended for extensions to gimmegit. -# Clone the same repo and check out an existing branch -gimmegit https://github.com/dwilding/frogtab/tree/fix-something -# Clone dwilding's fork of https://github.com/canonical/operator and check out a new branch -gimmegit -u canonical dwilding/operator update-docs # branching off upstream main -gimmegit -b 2.23-maintenance -u canonical \\ # branching off an upstream dev branch +▶ EXAMPLES + +gimmegit dwilding/frogtab my-feature (1) +gimmegit -b candidate dwilding/frogtab bump-version (2) +gimmegit https://github.com/dwilding/frogtab/tree/fix-something (3) +gimmegit -u canonical dwilding/operator update-docs (4) +gimmegit -b 2.23-maintenance -u canonical dwilding/operator backport-docs (5) +gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \\ (6) dwilding/operator backport-docs -gimmegit -b https://github.com/canonical/operator/tree/2.23-maintenance \\ # same as previous - dwilding/operator backport-docs""" + +1. Clone https://github.com/dwilding/frogtab and check out a new branch, branching off main. +2. Clone the same repo and check out a new branch, branching off a dev branch. +3. Clone the same repo and check out an existing branch. +4. Clone dwilding's fork of https://github.com/canonical/operator and check out a new branch, + branching off upstream main. +5. Clone the same fork and check out a new branch, branching off an upstream dev branch. +6. Equivalent to (5).""" From 7fd704377829ce54f154f606abe8fffe97006208 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Thu, 18 Dec 2025 23:55:50 +0800 Subject: [PATCH 06/12] small tweaks to help output --- README.md | 10 +++++----- src/gimmegit/_help.py | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 058310f..956b677 100644 --- a/README.md +++ b/README.md @@ -325,9 +325,9 @@ gimmegit [] [-- ] (2) ▶ DIRECTORY STRUCTURE When you clone a repo, gimmegit creates a dedicated directory for the clone: - . - └── The project directory. For example, 'frogtab'. - └── - The clone directory. For example, 'dwilding-my-feature'. + . + └── The project directory. For example, 'frogtab'. + └── - The clone directory. For example, 'dwilding-my-feature'. If the clone directory already exists, gimmegit skips cloning. If the clone directory would be inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error @@ -378,8 +378,8 @@ For new branches: ▶ GIT OPTIONS -gimmegit sets --no-tags when cloning. To provide extra clone options, use '-- '. -For example, to clone tags, use '-- --tags'. +gimmegit sets --no-tags when cloning. Use '-- ' to provide extra clone options. +For example, use '-- --tags' to clone tags. ▶ PRE-COMMIT diff --git a/src/gimmegit/_help.py b/src/gimmegit/_help.py index 174b118..5a6f620 100644 --- a/src/gimmegit/_help.py +++ b/src/gimmegit/_help.py @@ -23,9 +23,9 @@ ▶ DIRECTORY STRUCTURE When you clone a repo, gimmegit creates a dedicated directory for the clone: - . - └── The project directory. For example, 'frogtab'. - └── - The clone directory. For example, 'dwilding-my-feature'. + . + └── The project directory. For example, 'frogtab'. + └── - The clone directory. For example, 'dwilding-my-feature'. If the clone directory already exists, gimmegit skips cloning. If the clone directory would be inside an existing repo, gimmegit exits with an error. gimmegit also exits with an error @@ -76,8 +76,8 @@ ▶ GIT OPTIONS -gimmegit sets --no-tags when cloning. To provide extra clone options, use '-- '. -For example, to clone tags, use '-- --tags'. +gimmegit sets --no-tags when cloning. Use '-- ' to provide extra clone options. +For example, use '-- --tags' to clone tags. ▶ PRE-COMMIT From b3960062aab3cbb40bc8e7373784c76a83b81761 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Fri, 19 Dec 2025 12:16:32 +0800 Subject: [PATCH 07/12] remove double blank lines --- README.md | 7 ------- src/gimmegit/_help.py | 7 ------- 2 files changed, 14 deletions(-) diff --git a/README.md b/README.md index 956b677..137c12e 100644 --- a/README.md +++ b/README.md @@ -304,7 +304,6 @@ gimmegit -u canonical dwilding/charmcraft update-profile -- --recurse-submodules gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone in a dedicated directory, based on the project, owner, and branch name. - ▶ USAGE gimmegit [] [] [-- ] (1) @@ -321,7 +320,6 @@ gimmegit [] [-- ] (2) 2. Clone a GitHub repo and check out an existing branch. is a URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. - ▶ DIRECTORY STRUCTURE When you clone a repo, gimmegit creates a dedicated directory for the clone: @@ -334,7 +332,6 @@ be inside an existing repo, gimmegit exits with an error. gimmegit also exits wi if it detects that the working directory is a project directory (specifically, if the latest modified subdirectory is a gimmegit clone). - ▶ BRANCH MAPPING gimmegit creates a Git alias 'update-branch' that merges remote changes from the base branch. @@ -345,7 +342,6 @@ For new branches: • gimmegit branches off the base branch. • gimmegit doesn't push the branch to GitHub. - ▶ OPTIONS -u, --upstream-owner Owner of the base branch. For example, provide '-u canonical' @@ -381,13 +377,11 @@ For new branches: gimmegit sets --no-tags when cloning. Use '-- ' to provide extra clone options. For example, use '-- --tags' to clone tags. - ▶ PRE-COMMIT If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook after cloning the repo. For more information, see https://pre-commit.com/. - ▶ ADDITIONAL COMMANDS gimmegit [--color auto|always|never] (1) @@ -402,7 +396,6 @@ gimmegit [--ssh auto|always|never] --parse-url (5) 4. Display the installed version of gimmegit. 5. Display a JSON representation of a GitHub URL. Intended for extensions to gimmegit. - ▶ EXAMPLES gimmegit dwilding/frogtab my-feature (1) diff --git a/src/gimmegit/_help.py b/src/gimmegit/_help.py index 5a6f620..2f51eac 100644 --- a/src/gimmegit/_help.py +++ b/src/gimmegit/_help.py @@ -2,7 +2,6 @@ gimmegit is a tool for cloning GitHub repos and creating branches. gimmegit puts each clone in a dedicated directory, based on the project, owner, and branch name. - ▶ USAGE gimmegit [] [] [-- ] (1) @@ -19,7 +18,6 @@ 2. Clone a GitHub repo and check out an existing branch. is a URL such as 'https://github.com/dwilding/frogtab/tree/fix-something'. - ▶ DIRECTORY STRUCTURE When you clone a repo, gimmegit creates a dedicated directory for the clone: @@ -32,7 +30,6 @@ if it detects that the working directory is a project directory (specifically, if the latest modified subdirectory is a gimmegit clone). - ▶ BRANCH MAPPING gimmegit creates a Git alias 'update-branch' that merges remote changes from the base branch. @@ -43,7 +40,6 @@ • gimmegit branches off the base branch. • gimmegit doesn't push the branch to GitHub. - ▶ OPTIONS -u, --upstream-owner Owner of the base branch. For example, provide '-u canonical' @@ -79,13 +75,11 @@ gimmegit sets --no-tags when cloning. Use '-- ' to provide extra clone options. For example, use '-- --tags' to clone tags. - ▶ PRE-COMMIT If the repo contains a file '.pre-commit-config.yaml', gimmegit installs a pre-commit hook after cloning the repo. For more information, see https://pre-commit.com/. - ▶ ADDITIONAL COMMANDS gimmegit [--color auto|always|never] (1) @@ -100,7 +94,6 @@ 4. Display the installed version of gimmegit. 5. Display a JSON representation of a GitHub URL. Intended for extensions to gimmegit. - ▶ EXAMPLES gimmegit dwilding/frogtab my-feature (1) From 56fb2b035c9904621b5cd7daa7533f4d38d0681e Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Fri, 19 Dec 2025 12:44:46 +0800 Subject: [PATCH 08/12] add missing comma in pyproject.toml --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 69f94c8..cfd7720 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,5 +38,5 @@ line-length = 99 root = [ "./src", "./tests/functional", - "./tests/unit" + "./tests/unit", ] From b49adac7bb547a03792e6d34de4633c404c3c40b Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Fri, 19 Dec 2025 12:58:23 +0800 Subject: [PATCH 09/12] add check for the command reference in README.md --- .github/workflows/checks.yaml | 2 ++ .pre-commit-config.yaml | 6 ++++++ justfile | 6 +++++- 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 6dcd7aa..31aaf5c 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -23,3 +23,5 @@ jobs: run: uvx --from rust-just just lint - name: Run unit tests run: uvx --from rust-just just test-unit + - name: Check the command reference + run: uvx --from rust-just just check-command-reference diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index acdb2fc..8de1df3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -16,3 +16,9 @@ repos: language: system pass_filenames: false always_run: true + - id: just-check-command-reference + name: Run 'just check-command-reference' + entry: just check-command-reference + language: system + pass_filenames: false + always_run: true diff --git a/justfile b/justfile index ecb8b50..c7da977 100644 --- a/justfile +++ b/justfile @@ -15,8 +15,12 @@ test-functional: (test "tests/functional") test args="tests/unit tests/functional": uv run pytest -vv {{args}} +check-command-reference: + #!/bin/bash + diff <(uv run .scripts/extract_command_reference.py) <(uv run gimmegit -h) + demo: - #!/bin/sh + #!/bin/bash package_dir="$PWD" mkdir -p demo cd demo From f4a0dfcf1f397a50994bbaa6af71a705be0f810b Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Fri, 19 Dec 2025 13:02:02 +0800 Subject: [PATCH 10/12] update pre-commit config --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8de1df3..99af0a6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -10,8 +10,8 @@ repos: - id: check-toml - repo: local hooks: - - id: just-default - name: Run default 'just' recipe + - id: just + name: Run 'just' entry: just language: system pass_filenames: false From e7e1b51aec44d154b8b0ece8c6e5d996d8e223c8 Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Fri, 19 Dec 2025 13:03:07 +0800 Subject: [PATCH 11/12] remove one more blank line --- README.md | 1 - src/gimmegit/_help.py | 1 - 2 files changed, 2 deletions(-) diff --git a/README.md b/README.md index 137c12e..e472f6f 100644 --- a/README.md +++ b/README.md @@ -371,7 +371,6 @@ For new branches: --return-dir Output the clone directory path to stdout and send full progress to stderr. - ▶ GIT OPTIONS gimmegit sets --no-tags when cloning. Use '-- ' to provide extra clone options. diff --git a/src/gimmegit/_help.py b/src/gimmegit/_help.py index 2f51eac..0d9b131 100644 --- a/src/gimmegit/_help.py +++ b/src/gimmegit/_help.py @@ -69,7 +69,6 @@ --return-dir Output the clone directory path to stdout and send full progress to stderr. - ▶ GIT OPTIONS gimmegit sets --no-tags when cloning. Use '-- ' to provide extra clone options. From b535f9b004a7b815c77237d39bc0aa2b0846fcab Mon Sep 17 00:00:00 2001 From: Dave Wilding Date: Fri, 19 Dec 2025 13:03:31 +0800 Subject: [PATCH 12/12] add script needed by new check --- .scripts/extract_command_reference.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .scripts/extract_command_reference.py diff --git a/.scripts/extract_command_reference.py b/.scripts/extract_command_reference.py new file mode 100644 index 0000000..97471d5 --- /dev/null +++ b/.scripts/extract_command_reference.py @@ -0,0 +1,18 @@ +"""Extracts gimmegit's help output from the "Command reference" section of README.md.""" + +from pathlib import Path + + +def main() -> None: + text = Path("README.md").read_text() + start_marker = "# Command reference\n\n```text\n" + start_index = text.find(start_marker) + assert start_index > 0 + start_index += len(start_marker) + end_index = text.find("\n```", start_index) + assert end_index > start_index + print(text[start_index:end_index]) + + +if __name__ == "__main__": + main()