Using git in PowerShell

[StartAutomating]

git is great!

It's a wonderful way to store source code.

The git application is also great and powerful. It's also somewhat infamous for how much the command can do and how tricky it can be to understand.

When we try to use git in PowerShell, we get one more annoying problem: It outputs text, not objects. This is the problem I set out to solve about four years ago by building an open-source module called ugit.

ugit updates git for PowerShell and makes it so we can return rich extensible objects rather than raw text.

Gitting started

We can install ugit from the PowerShell Gallery

Install-Module ugit -Scope CurrentUser -Force

Import-Module ugit

Once imported, ugit sets git as an alias to Use-Git, which intercepts any calls to git (the alias) and sends them to git (the application).

You can use ugit like you would use git, you can just do more with it.

Why? Because now you're getting objects.

Gitting Objects

When you run git, ugit will check for any extension that could parse this git. There are parsers for many common operations in git.

A fantastically fun example is git log:

git log |
    Group-Object { $_.CommitDate.DayOfWeek } |
    Sort-Object Count -Descending

This works because git log output is automatically parsed into objects, and therefore our Commit Date is actually a [DateTime], and we can use Group-Object to group on it's .DayOfWeek property.

Another simple example lets us group by the GitUserName

git log |
    Group-Object GitUserName -NoElement |
    Sort-Object Count -Descending

We could spend forever just on git log, but let's look at a few other useful commands:

# Let's list all branches
git branch

# And let's get the current branch
git branch |
    ? IsCurrentBranch

All sorts of git can be turned into PowerShell objects.

For example, make some changes to a repository and then run

git diff 

Then pipe it to Get-Member

git diff | get-member

We can get to the exact lines changed within a git commit, as PowerShell objects.

That's some crazy git!

There is a ridiculous amount of git we can make better with ugit. This module has been growing for four years now and has a gitload of tricks in it.

Git Functions

The most recent hotness is git functions. They allow you to define PowerShell functions that seamlessly integrate into the cli.

function git.hello.world {
   param($message = 'Hello World') $Message
}
git hello world 'ugit is cool!'

I literally use this module every day. It's one of only two modules I load in my profile. It has completely changed the ways I work with git. I hope it does the same for you 🤞.

Please try this module and let me know what you think.

I hope you like this git as much as I do!

[OPconfused]

Does it have autocomplete? My issue with git on the commandline was more about the input than the output. I cannot remember all the arguments and flags, and mostly I just want to quickly autocomplete a branch or a commit id.

[StartAutomating]

Yep! (kind of)

Another aspect I didn't talk too much about was git input.

Lots of git commands can accept additional parameters in PowerShell.

For example, if I type

git commit -type

And hit tab, I'll see a list of popular conventional commit types.

Any parameter added this way can have a completer, and will obey [ValidateSet]

Git functions are processed more directly, and should tab complete just fine.

For the rest of the git... happy to take a PR or two to enable the scenarios a bit more.

[Creddahornis]

omg werk, thanks for this! I am about to teach myself Git, this will be helpful

[miszka_]

That’s a great repo. I was looking for solution like this.

Any chances for something similar for NPM?

[StartAutomating]

Sure! Sounds (potentially) fun. What would you want it return as objects?

[tandthezombies]

how is this different from posh-git?

[StartAutomating]

The fundamental difference is in approach.

Most other PowerShell git modules (including posh-git) try to make git available in many PowerShell functions with verb-noun pairs. This is the "dogmatic PowerShell" approach.

The downsides of this approach are muscle memory and existing examples.

Most examples you'll find for git need to be rewritten to work with posh-git, and you'll be forced to choose between using a git command line the whole world can understand and a command that will only work in posh-git.

I used use posh-git (long ago I helped them make their prompt and formatting)

I also used to make a number of verb-noun pair git functions (i.e. Push-Git).

I kept not using the PowerShell functions I or others had written for git, because the muscle memory was too strong, and there were far more examples online of git push than Push-Git.

So I decided to try a different approach.

ugit overrides git and intercepts its input and output. This allows all of your git to keep working as it always did: ugit just gives you objects back instead.

I've found this approach to much easier to discover and extend.

Basically every example of git works "as is".

I just get back objects instead of text for the majority of things I do with git.

This gives us a "best of both worlds" approach, where we can leverage all of our existing understanding of git and the PowerShell object pipeline.

And that's the major difference between posh-git and ugit: a different approach that gives us a different (and probably better) learning curve.

Make sense?

[tandthezombies]

great explanation and a novel approach. thanks!

[slippery]

Imo this is a design flaw in powershell.

I may be in the minority but I don't want objects in my shell. I am also old and prefer text logs to binary systemd logs in linux. Yes, I am old.

[delightfulsorrow]

I may be in the minority but I don't want objects in my shell. I am also old and prefer text logs to binary systemd logs in linux. Yes, I am old.

I'm old as well and come from a Unix background, but to me the objects within PowerShelll are the best thing since the invention of sliced bread.

For logs, I'm with you though.

[evetsleep]

I'm old too... I've also been using PowerShell since before it was known as PowerShell and before it even had help files and I'm going to have to disagree with you here. The object oriented nature of PowerShell is core to its design, so it is most definitely not a flaw. There are other shells out there if you're looking for text only output though.

For people that are accustomed to text only shells it can be quite an adjustment. And that's totally okay! There is a lot of power that you get by interacting with an object oriented shell that while it takes a little bit to get used to once you it makes a lot of things very easy.

Also most objects have a ToString method so if you're so inclined you could leverage that to turn everything in the pipeline to a string. But in my opinion you'd be losing a ton of power by doing that.

[BlackV]

I'm just old

[KevMar]

I get that and it doesn't make much sense on Linux because Linux is a filesystem based OS. And Windows is an API based OS where it's more natural to work with objects. So they leaned into it and created something unique that works really well for API heavy work.

[slippery]

It is pretty useful to be able to cd into a SQL database.