Skip to content

jdschleicher/bashcuts

BranchesTags

Repository files navigation

Table of Contents



Choose which Prerequisite CLI's and Other Tools to Install



System Setup for bash and PowerShell Profiles


IMPORTANT FOR MAC USERS There are several use cases of the command "start" that allows files and websites to be opened from the terminal. An "if check conditional" has been introduced to create an alias for the mac command "open" to run whenever "start" is entered. From my initial setup on a mac this has been working for me but if any erros around "start is not a command" we can also replace all instances of "start" with "open" locally in your bashcuts clone to your machine.


SETUP FOR BASH TERMINAL:

Shortcuts using bashrc or bash_profile files. Many of the shortcuts provide prompts to support populated necessary arguments/flags to make the functions work

You may not already have a .bashrc file on your system. To create one, open a bash terminal and copy and paste the below command in the terminal or create a new file in your user directory with the name .bashrc

touch ~/.bashrc

You can also use the .bash_profile file instead of the .bashrc.

To get started, add the below content and associated logic to the your .bashrc file and from there it will load up all the aliases and functions referenced from the .bcut_home file.

To open the .bashrc file that was created above type in the terminal: start ~/.bashrc

IMPORTANT -- clone the bashcuts directory into a folder directory structure without spaces or the source command won't be able to evaluate the path correctly (still working on setting it up correctly to not care about spaces). Also note you will have to provide that path to the variable below:

PATH_TO_BASHCUTS="/c/path/to/your-parent-directory-where-bashcuts-will-be-cloned-into/"  
if [ -f $PATH_TO_BASHCUTS/bashcuts/.bcut_home ]; 
then 
    echo "bashrc loaded"
    source $PATH_TO_BASHCUTS/bashcuts/.bcut_home
else
    echo "missing bashrc"
fi

SETUP FOR PowerShell Terminal AND PowerShell Debugger Terminal in VS Code:

Once PowerShell Core has been installed on your machine you can open up a new PowerShell terminal in VS Code or a standalone PowerShell Terminal.

With the terminal open enter "$profile" into the terminal to see where the terminal's expecting a profile file to exist. This file may not exist so we may need to create it.

To create the file enter the below powershell command to create an empty file at the expected profile path:

New-Item -ItemType File -Path $profile

To edit the profile select, enter the below command:

start $profile

This will open up the PowerShell profile and may prompt for which application to open the file in. Choose VSCode and select the checkbox to use VSCode for all ps1 files. This gives us syntax highlighting and other features that can be leveraged within the VS Code IDE.

With the PowerShell Profile open add the following code snippet AND IMPORTANT replace the path directories to point to where the bashcuts directory was cloned to.

We will know if its working as expected if the terminal prompts out "powershell starting" on initialization/opening:


$path_to_bashcuts_parent_directory = 'C:\git'
$bashcuts_git_directory = "bashcuts"
if ("$path_to_bashcuts_parent_directory\$bashcuts_git_directory" -ne $NULL) {
    $path_to_bashcuts = "$path_to_bashcuts_parent_directory\$bashcuts_git_directory"
    Write-Host "PowerShell bashcuts exists"
	. "$path_to_bashcuts\powcuts_home.ps1"
} else {
	Write-Host "Cannot find bashcuts"
    Write-Host "pow_home not setup"
}

For the PowerShell terminal from the VS Code PowerShell extension, we can use the same steps as above. It more than likely will be a different profile to update.

Here's a screen shot of the commands to the empty profile being opened in VS Code:

image

Here's a side-by-side view of a regular PowerShell core terminal and the PowerShell VS Code extension terminal:

image


How to use bashcuts


The bashcuts commands (for the majority of commands) have a convention of 'verb-noun' and meant to be auto-filled with tab-tab to avoid any typos or copy/paste mistakes

image

Press tab twice for auto-fill and available command options:

image

To See Where Shortcuts are Loaded and may be available

  • "o-" for "Open" --> "o-sfdx" will open the file containing all aliases and supporting logic for sfdx cli shortcuts. With the sfdx-bashcuts (or any bashcuts commands file) can be easily searched, modified, or new commands added and can be committed. When modifying files enter the command "reinit" when done to reload the current terminal instead of closing and repopening.
  • To see all possible aliases and associated functions, in bash terminal, type "o-" and then press tab twice to see options of each file of shortcuts image

image

Opening VS Code Snipppets

When using VS Code it is HIGHLY recommend to setup VSCode settings sync: https://code.visualstudio.com/docs/editor/settings-sync

This will sync settings, keyboard shortcuts, much more, AND SNIPPETS.

For windows machines, the snippets are stored in an expected directory, so we can created custom snippet files or use VSCode made snippet files and quickly open them to add new snippets as needed. VS-Code saves those snippets via sync and bashcuts allows us to easily open, edit, and add to them without leaving our VS Code editor.

image


Azure DevOps work-item shortcuts

PowerShell shortcuts in powcuts_by_cli/azdevops_workitems.ps1 provide guided setup and work-item navigation against an Azure DevOps organization. Today this includes a guided Connect-AzDevOps first-run helper, a cached background sync (Sync-AzDevOpsCache + Register-AzDevOpsSyncSchedule), a list/open pair for items assigned to you (Get-AzDevOpsAssigned, Open-AzDevOpsAssigned), the matching pair for items where you've been @-mentioned in discussion (Get-AzDevOpsMentions, Open-AzDevOpsMention), an Epic→Feature→User Story tree view (Show-AzDevOpsTree), an interactive new-user-story creator with parent-feature, iteration, and area-path pickers (New-AzDevOpsUserStory), and a per-org field-schema config (Initialize-AzDevOpsSchema, Get-AzDevOpsSchema, Edit-AzDevOpsSchema, Test-AzDevOpsSchema) that future schema-aware updates to the work-item commands consume.

Prerequisites

  • Azure CLI: https://aka.ms/installazurecli
  • azure-devops CLI extension: az extension add --name azure-devops (Connect-AzDevOps will offer to install this for you on first run)
  • An active az login session (Connect-AzDevOps will offer to start one for you on first run)

Profile environment variables

Add this block to your PowerShell $profile and reload (open a new terminal). Replace each value with what's appropriate for your organization:

$env:AZ_DEVOPS_ORG = 'https://dev.azure.com/myorg'
$env:AZ_PROJECT    = 'My Project'
$env:AZ_USER_EMAIL = 'user@example.com'
$env:AZ_AREA       = 'My Project\My Team'
$env:AZ_ITERATION  = 'My Project\Sprint 42'

First run

In a fresh PowerShell terminal:

Connect-AzDevOps

This walks through six checks (Azure CLI present, azure-devops extension installed, env vars set, az login session active, az devops defaults configured, smoke az boards query succeeds) and prints a clear READY or NOT READY verdict at the end. It will offer to install the extension and run az login for you if either is missing.

After Connect-AzDevOps reports READY once, later commands in the AzDevOps batch use the silent Test-AzDevOpsAuth check at startup to confirm the environment is still good before they hit the cache.

Day-to-day work-item shortcuts

These read the local cache populated by Sync-AzDevOpsCache (and the recurring Register-AzDevOpsSyncSchedule job). They never call az directly, so they return instantly.

Get-AzDevOpsAssigned                       # everything assigned to you (excludes Closed/Removed)
Get-AzDevOpsAssigned -State Active         # filter to a single state
Get-AzDevOpsAssigned -State Active,New     # filter to multiple states
Get-AzDevOpsAssigned | Format-Table -AutoSize

Open-AzDevOpsAssigned 12345                # open one of your assigned items in the browser

Get-AzDevOpsMentions                                  # work items where you've been @-mentioned (excludes items you're already assigned to)
Get-AzDevOpsMentions -State Active                    # filter to a single state
Get-AzDevOpsMentions -Since (Get-Date).AddDays(-7)    # only mentions whose last activity was in the past week
Get-AzDevOpsMentions -IncludeAssigned                 # also surface mentioned items already assigned to you
Get-AzDevOpsMentions | Format-Table -AutoSize

Open-AzDevOpsMention 12345                 # open one of your mentioned items in the browser

Show-AzDevOpsTree                          # print the project's Epic -> Feature -> User Story tree

If the cache is older than 6 hours, Get-AzDevOpsAssigned, Get-AzDevOpsMentions, and Show-AzDevOpsTree each print a one-line WARNING stale (last sync: ...) notice above their output and still render the cached data.

Sync-AzDevOpsCache populates two more cache files alongside the existing assigned.json / mentions.json / hierarchy.json: iterations.json and areas.json. The new-user-story command below uses these for instant iteration / area-path pickers; if you've upgraded but haven't re-synced yet, the picker fetches them live with a one-line "(run Sync-AzDevOpsCache to make this instant)" notice.

Creating a new User Story

New-AzDevOpsUserStory walks you through title / description / priority / story points / acceptance criteria, then offers a numbered picker for the parent Feature (active Features pulled from hierarchy.json), the iteration, and the area path. After it creates the story it links the chosen parent and opens the new work item in your browser.

New-AzDevOpsUserStory                       # full interactive walk-through

Every prompt is skippable via a parameter, so the function works non-interactively in a script:

New-AzDevOpsUserStory `
    -Title              "Add new dashboard widget" `
    -Description        "Surface deploy frequency on the team home page." `
    -Priority           2 `
    -StoryPoints        3 `
    -AcceptanceCriteria "- Widget renders for all team members`n- Updates within 60s of new deploy" `
    -FeatureId          1240 `
    -Iteration          "My Project\Sprint 42" `
    -Area               "My Project\My Team" `
    -NoOpen

-FeatureId 0 creates an orphan (no parent link). -NoOpen skips the browser launch and just echoes the new work-item URL — handy in scripts. The existing az-create-userstory in pow_az_cli.ps1 is left in place for users who prefer the original flow.

Per-org field-schema config

Every Azure DevOps org configures its own required + custom fields via process templates (e.g. a "Customer Impact" required field on every User Story, or a "Compliance Risk" picklist). The schema-management commands let you declare those fields once per org so future schema-aware updates to New-AzDevOpsUserStory, Get-AzDevOpsAssigned, Show-AzDevOpsTree, etc. can prompt for / surface them automatically.

The schema lives at $HOME/.bashcuts/azure-devops/schema-<org>.json (per-org keyed off $env:AZ_DEVOPS_ORG; falls back to schema.json when unset). The directory is created with 0700 permissions on macOS / Linux; Windows inherits the user-only ACL from %USERPROFILE%.

Initialize-AzDevOpsSchema     # introspect your org via `az boards work-item-type show`
                              #   and write a starter schema. Refine afterward.
Get-AzDevOpsSchema            # print summary table of every required/optional field
Get-AzDevOpsSchema -PassThru  # return objects (pipeable / scriptable)
Edit-AzDevOpsSchema           # open the schema in $env:EDITOR / code / notepad / nano
                              #   (creates a stub if the file doesn't exist yet)
Test-AzDevOpsSchema           # validate the JSON, that every ref still exists in the
                              #   org, and that picklist options are a subset of
                              #   the org's allowedValues. Verdict: VALID / STALE /
                              #   INVALID with a list of any unknown refs / option
                              #   mismatches.

Schema file format (one entry per work-item type, each with required and optional field arrays):

{
  "User Story": {
    "required": [
      { "name": "Customer Impact", "ref": "Custom.CustomerImpact", "type": "string" },
      { "name": "Compliance Risk", "ref": "Custom.ComplianceRisk", "type": "picklist",
        "options": ["Low","Medium","High"] }
    ],
    "optional": [
      { "name": "Epic Owner Name", "ref": "Custom.EpicOwnerName", "type": "string" }
    ]
  }
}

Supported type values: string, int, picklist, bool, date, multiline. Unknown types are treated as string with a warning from Test-AzDevOpsSchema.

About

Shortcuts using bashrc file

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages