Gust – Git Utility Something Tool (PowerShell)

Gust is a PowerShell script that automates common Git (and GitHub CLI) tasks for your GitHub repository (managing branches, pushing etc.) with all being configurable in config.json.

Table Of Contents (TOC)

Gust – Git Utility Something Tool (PowerShell)

Dependencies

This script has two dependencies:

Note: GitHub CLI is only used right now only for Releases. More about everything Github CLI specific in chapter about it.

Features

Verifies if the user has set user.name and user.email (global and local) - or set their name and email in config with "changeNameGlobal" : true (default is false)
Initializes a new Git repository if one doesn't exists
Adds and commits changes
Pushes to the selected branch (default is main)
A most of things being configurable in config.json
Supports multiple "modes" (mode is what the script will do when you run GUST) - including modes: branch switching, branch creating, etc.
Allows setting default message for commit messages
Support short aliases for inputs (more on that later)
Adds a remote origin (or any other depends on config) and pulls with --allow-unrelated-histories

Parameters

Parameter	Required	Description	Aliases
message	For commits, releases...	Your commit message you want to use	-c (as commit message)
gitURL	Only required when initializing repository.	The GitHub repository URL (omit .git at the end it will be added automatically)	-u (as URL)
otherModes	When you don't want to run from config defaultMode.	This is used to change the mode you want to do, also it has configurable default value `"defaultMode" : "c"`	-m (as mode)
branch	Only when working with branches.	this is for working branches, it has default configurable in config under `"defaultBranch" : "main",`in some cases as `main`	-b
number	Only for log.	this is used when you need some number as an input (now it's only used in log, it has default configurable in config `"defaultLogLength" : 5,`	-n
path	Only for autocommit.	This is used for autoCommit to automatically commit specific folder	-p
release	For release only.	This is used when you want to make a release, this is the version of the release.	-r
title	For release only.	This is used when you want to make a release, this is the name of the release.	-t
name	For creating repositories only.	This is used to create repositories and giving them name.	-na
public	For creating repositories only.	This is True or False (or $null but that makes it Public) to make repository public or private. True => public.	-pu
description	Used in most GitHub cli functionality.	Used to add description to PRs, Issues etc.	-d
who	Used in PRs and Issues.	This assigns the Issue / PR to someone, default is "@me" or the one publishing it.	-w
label	Used in PRs and Issues.	This is for organizing the Issues / PR to it's label.	-la

Note : commit message is used for more things where message is needed, for example in releases, you'll use message for description of the release.

You can learn all possible labels on official GitHub docs.

Mode parameters

(git)

Name	Description
c(ommit)	This is configs default. Adds a commit message and pushes to your GitHub repository.
b(ranch)s(witch)c(create)	Creates a new branch and switches to the new branch.
b(ranch)s(witch)	Switches to an existing branch.
b(ranch)d(elete)	Deletes an existing branch.
s(tatus)	Shows the status of current branch.
p(ull)	Pulls the latest changes from your remote repository.
l(og)	Shows recent commits (default number or set with -number / -n).
autoCommit	Use this for automatically commit (Task Scheduler)
d(escription)	This shows you this description in terminal
r(evert)c(ommit)	This reverts your last commit and and commits a new one that "one commit back"

(GitHub CLI)

Name	Description
i(ssue)c(reate)	This creates new issue on your active github repository.
i(ssue)c(heck)	This mode lists and shows the status of issues the issues in current repository.
prc(heck)	This mode lists and shows the status of PRs the issues in current repository.
(p)c(reate)	This creates new PR on your active github repository.
c(reate)r(epo)	This mode creates new repository on your github account.
r(elease)	This releases your code as new release on github from folder `./RELEASE/`

autoCommit setup

You can use auto-commit like this:

gust -m "autoCommit" -c "auto commit message" -p "C:/some/folder/

I recommend using this with Task Scheduler, you'll have to look into it if you want to use it, but it's really useful and probably easiest Windows way to do it.

configurations

{
  "defaultBranch": "main",
  "defaultRemote": "origin",
  "userName": null,
  "userEmail": null,
  "changeNameGlobal": null,
  "autoPullBeforePush": null,
  "useDefaultCommitMessage": false,
  "defaultCommitMessage": "small fixes",
  "forceBranchDelete": null,
  "defaultLogLength": 5,
  "defaultMode": "c",
  "runModification": true,
  "runActions": true,
  "language": "english",
  "runAfterActions": true,
  "runBeforeActions": true,
  "defaultRelease": "1.0.0",
  "defaultTitle": "Released",
  "defaultPath": "Set this value in config!!",
  "defaultReleaseMessage": "released",
  "defaultWho": "@me",
  "defaultDescriptionPR": "PR created",
  "defaultPRTitle": "PR",
  "defaultLabelsIssue": "bug",
  "defaultDescriptionIssue": "issue created",
  "defaultIssueTitle": "Issue",
  "defaultLabelsPR": "bug"
}

key	description
defaultBranch	Default branch to push to.
defaultRemote	Default git remote name.
userName	Used if no git config is set for user.name.
userEmail	Used if no git config is set for user.email.
changeNameGlobal	Boolean value that makes the name / email change global or local (to enable name changing you have to change the userEmail to your email address and userName to your name)
autoPullBeforePush	If `True` this sets if you automatically pull before pushing.
defaultCommitMessage	Used as no commit message is inputted.
forceBranchDelete	If `true` uses `-D` (force deletes) branches.
defaultLogLength	Number of commits shown when using the `log` mode.
defaultMode	Default mode used when no mode is inputted.
runModifications	Defaults to `true`, when it's true mods are enabled and can be executed.
runActions	Defaults to `true`, when it's true actions are enabled and will be executed.
language	Defaults to `english`, if you have another json in other language than english that translates GUST, you can add it, if it was named `czech.json` you would change the english to Czech (it works that it adds .json to whatever you add there).
runAfterActions	Defaults to `true`, this runs actions after everything
runBeforeActions	Defaults to `true`, this runs actions before everything
defaultRelease	Defaults to `1.0.0`, this is default release version if you don't input any
defaultTitle	Defaults to `Release`, this is the default title for releases
defaultPath	Defaults ti `Set this value in config!!`, this is used for any path needed (autocommit)
defaultReleaseMessage	Defaults to `released`, this is used as release message (description)
defaultWho	Defaults to `@me` so you assighn everything in default to yourself. Used in PRs and Issues.
defaultDescriptionPR	Defaults to `PR created`, this the description you give to PR if you don't provide any.
defaultPRTitle	Defaults to `PR`, this is the PR title if you don't prive any for Issues.
defaultLabelsIssue	Defaults to `bug`, this is the default Label id you don't provide any for Issues.
defaultDescriptionIssue	Defaults to `issue created`, this is the default description for Issues if you don't provide any.
defaultIssueTitle	Defaults to `Issue`, this is the default issue title if you don't provide any.
defaultLabelsPR	Defaults to `bug`, this is used as default label for PRs if you don't provide any.

Prerequisites

Git installed on your system
User has configured name and email configured:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Note: To configure local configuration instead, remove --global. Note: this can also be setup as automatic action if you set userName, userEmail to change your name locally, if you want it globally you can change to true changeNameGlobal in your config file.

Usage

.\gust.ps1 -c "commit message" -u "URL"

This is an example of pushing and setting up remote code to your GitHub repository.

.\gust.ps1 -c "Refactor UI"

This is an example of committing to an already established repository.

.\gust.ps1 -m "bcs" -b "coolBranch"

this is example of creating a new branch and switching to the branch

.\gust.ps1 -m "bs" -b "main"

This is example of switching to a already existing branch.

.\gust.ps1 -m "bd" -b "coolBranch"

This is example of deleting a existing branch.

.\gust.ps1 -m "s"

This is example of showing git status.

.\gust.ps1 -m "log" -n 8

This is example of showing the log provided the length of how much you want (in this you'l see 8 things in the log).

.\gust.ps1 -c "Bug fixes"

This is showcase you don't need to use -m dor mode because you have default mode in config (which defaults to c - commit mode).

.\gust.ps1 --update
.\gust.ps1 -update
.\gust.ps1 -m "update"

This automatically updates to the newest version of GUST, by using github commits and downloading from there. This might download unstable version.

Note : these are all ways to run update.

.\gust.ps1

No inputs in default does (this can be changed in config):

.\gust.ps1 -c "small changes"

Profiles

GUST has it's own profile manager, in /profiles is folder for every profile you have currently locally on your disc (in default it comes with default profile), you can create as many you want.

gust -m "swp"

This is used to switch profiles from your current profile to other profile that exists.

gust -m "cnp"

This is used for creating a new profile that doesn't exists.

Note : you can't change configs with GUST in version 0.4.0 for now, so you have to change it by hand in /profiles/'profileName'/config.json.

Stats

Every profile has stats.json in their respective folder, it counts how many times you used any command.

Note: it doesn't have any CLI output or any usage in version 0.4.0, it might have in future or you can write mod for it.

Project Folder Structure

  GUST/
    actions/
      actionTemplate.ps1
      example.ps1
    languages/
      czech.json
      english.json
    mods/
      bluesky.ps1
      exampleMod.ps1
      exampleMod2.ps1
      modTeplate.ps1
      NASupload.ps1
      twitter.ps1
    profiles/
      default/
        stats.json
        config.json
      Custom/
        stats.json
        config.json
    source/
      actions.ps1
      funcs.ps1
      gitFuncs.ps1
      githubCliFuncs.ps1
      interactiveMode.ps1
      modAPI.ps1
      modLoader.ps1
    .gitignore
    gust.cmd
    gust.ps1
    install.ps1
    LICENSE
    README.md

GitHub CLI

This is used for GitHub specific things. Now only for releases.

Release

This has two modes in a way, if you don't have GitHub CLI you'll just create (and push) tag with the name from parametre release and with message from parametre message.

release -> the version of the tag.
message -> message of te tag.

Note: in this release will your full repository at that time, you can't change that from what I could find, you can't just (easily*) make that like releases with GitHub CLI.

With GitHub CLI you'll create full release and not just tag. You have to add .exe and other files for your release to .\RELEASE\. You have to add these parameters:

release -> Version of the tag.
title -> Name of the release.
message -> Description of the release.

Issue Check

This doesn't require any variables for you to call it, this will just show you the list and status of all issues on your current github repository.

Issue Create

This creates a new issue on your current GitHub repository. With this you can from just from your CLI create issues.

For this to work correctly you have to pass values for $who (defaults in default to "@me" which assigns your account to the Issue), $description which describes the Issue (it has default which you should change!!), $title (it defaults to value but you should change it in your profile config) and $label (which default to bug).

You would call something like this, where you add your values or rely on your default config values.

gust -m "icr" -w "who" -d "description" -t "title" -la "label"

NOTE: You can learn all possible labels on official GitHub docs.

PR check

This doesn't require any variables for you to call it, this will just show you the list and status of all PRs on your current github repository.

PR Create

This creates a new PR on your current GitHub repository. With this you can from just from your CLI create PRs.

For this to work correctly you have to pass values for $who (defaults in default to "@me" which assigns your account to the Issue), $branch (branch you want to merge to from your branch, so from branch new-feature to branch main you would just say $branch = main), $description which describes the Issue (it has default which you should change!!), $title (it defaults to value but you should change it in your profile config) and $label (which default to bug).

You would call something like this, where you add your values or rely on your default config values.

gust -m "pc" -w "who" -d "description" -t "title" -la "label"

#both modes call the same thing

gust -m "prc" -w "who" -d "description" -t "title" -la "label"

NOTE: You can learn all possible labels on official GitHub docs.

Create Repo

This is for creating repository on your github account easily from CLI, much faster then from web.

This expects you to add $name (-na "nameOfRepo"), $publicity ("true", "false", $null are expected), $description (any description of your repo). Some values have their default.

You would call it something like this:

gust -m "cr" -na "someRepo" -pu "true" -d "repoDescription"

Set Up To Call GUST Globally

automatic setup (recommended)

Download file install.ps1 from this repository.
Add it into your desired folder where you want GUST to be saved and downloaded.
After that run the file and it will automatically download and set itself into Path in Windows.

Note: no linux support for automatic download, because I have no idea how that would work or even if

After this GUST should be fully working and you should be able to use it.

manual GitHub clone

You can make gust.ps1 callable from anywhere by adding its directory to your PATH environment variable.

For example, if the script is located at: C:\downloads\gust\gust.ps1

Then add the following path to your system's PATH variable: C:\downloads\gust\

Note: last \ is necesery for it to work

After that, you can run the script using:

gust -c "Your commit message"

Note: If you delete the gust.cmd file, you'll need to call the script explicitly using gust.ps1. In that case, include the full path or ensure the .ps1 file extension is recognized in your environment.

Modding Support

GUST supports mods (external PowerShell scripts) to extend its functionality.
Each mod must follow a strict structure and expose specific functions so GUST can load and execute them.

Mod Structure

A mod is a .ps1 file placed in the mods/ directory.
It must define these functions:

versionOfGust → return GUST version the mod is for
getModificationName → returns the mod’s name
getModificationVersion → returns the mod’s version
getModifications → returns a list of regex/string patterns that the mod recognizes as valid "modes"
behaviourSwitchCheck → main function called when a mode matches
getHelpPages → return object with name and helpPages (for interactive mode)

Function names must not be changed. Renaming them will break the mod system.

Example Mods

There are already example mods included in the repository:

mods/exampleMod1.ps1 (mod tester)
mods/exampleMod2.ps1 (gust importer)

You can use these as a reference to see how mods are structured.

A reusable template is also provided in:

mods/modTemplate.ps1

This file can be copied and modified to create your own mods quickly.

Action Support

GUST supports actions (external PowerShell scripts, similar to mods) to extend its functionality.
Each action file must follow a strict structure and expose specific functions so GUST can load and execute them. Actions are scripts that run before / after specific mode you programme it for, it can be useful to extend features of default functionality or without changing source code of mod from somebody else change what it does (which is limited but I can be really helpful).

Action Structure

A action file is a .ps1 file placed in the actions/ directory.
It must define these functions:

versionOfGust → return GUST version the mod is for
getActionName → returns the action’s name
getActionVersion → returns the action’s version
getActions → returns a list of string names that the mod recognizes as valid "modes"
behaviourSwitchCheck → main function called when a mode matches

Function names must not be changed. Renaming them will break the action system.

Example actions

There are already example actions included in the repository:

actions/actionExample.ps1 (action tester)

You can use these as a reference to see how actions are structured.

A reusable template is also provided in:

actions/actionTemplate.ps1

This file can be copied and modified to create your own mods quickly.

Mod / action API

Mod API is stored in the file modAPI.ps1.
For now, it is only used as an easy way to access user inputs and GUST functionality from the main GUST script.

Function	Description
getMessage	Returns the input for commit message.
getURL	Returns the input for repository URL.
getOtherModes	Returns the input for mode string.
getBranch	Returns the input for branch name.
getNumber	Returns the input for numeric input (used in log)
getUpdate	Returns the input for update value
getInteractive	Returns the input for interactivity value
getPath	Returns the input for path
getRelease	Returns the input for release
getTitle	Returns the input for title
callNormalMode	Executes a normal mode with the parameters you passed to GUST.
getConfigValue	Return any value in config variable / config.json.

Final Note

This was made mainly for my use, because these are most of the commands I use and it streamlines most of my committing to github.

Name		Name	Last commit message	Last commit date
Latest commit History 120 Commits
actions		actions
languages		languages
mods		mods
profiles		profiles
source		source
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
gust.cmd		gust.cmd
gust.ps1		gust.ps1
install.ps1		install.ps1

License

Treechcer/GUST

Folders and files

Latest commit

History

Repository files navigation