Closes #1 & README follow dotfiles repo structure & precommit hooks replaced from dotfiles

Author: PhysShell

.gitattributes

@@ -10,3 +10,4 @@
 .gitignore text eol=lf
 .gitattributes text eol=lf
 LICENSE text eol=lf
+tools/hooks/* text eol=lf

GitAliases.Extras.psm1

@@ -400,6 +400,11 @@ function Register-GitAliasCompletion {
 
         # Reconstruct the command line as if 'git <subcommand>' was typed
         $line = $commandAst.Extent.Text
+        # CommandAst extent drops trailing whitespace, but completion context
+        # depends on it (e.g. "gsw " vs "gsw"). Restore it using cursor offset.
+        if ($cursorPosition -gt $line.Length) {
+            $line += (' ' * ($cursorPosition - $line.Length))
+        }
         $gitLine = $line -replace "^$commandName", "git $subCommand"
         $offset = ("git $subCommand").Length - $commandName.Length
         $gitCursorPosition = $cursorPosition + $offset

README.md

@@ -2,40 +2,66 @@
 
 Custom PowerShell git aliases and tab completion helpers on top of `posh-git` and `git-aliases`.
 
-## Install from PowerShell Gallery
+## Module installation
+
+Install from PowerShell Gallery:
 
 ```powershell
 Install-Module GitAliases.Extras -Scope CurrentUser
 Import-Module GitAliases.Extras
 ```
 
-## Install from source
+Install from source:
 
 ```powershell
 git clone https://github.com/PhysShell/GitAliases.Extras.git "$HOME\Documents\PowerShell\Modules\GitAliases.Extras"
 Import-Module GitAliases.Extras
 ```
 
-## Prerequisites
-
-- `git`
-- `posh-git`
-- `git-aliases`
-
-Example bootstrap:
+Install dependencies:
 
 ```powershell
 Install-Module posh-git -Scope CurrentUser -Force
 Install-Module git-aliases -Scope CurrentUser -Force
 Install-Module GitAliases.Extras -Scope CurrentUser -Force
 ```
 
-## Local quality checks
+## Quality checks
+
+Run both lint and tests:
 
 ```powershell
 .\tools\ci.ps1
 ```
 
+Run only lint:
+
+```powershell
+.\tools\ci.ps1 -LintOnly
+```
+
+Run only tests:
+
+```powershell
+.\tools\ci.ps1 -TestOnly
+```
+
+## Commit hooks
+
+Install local git hooks:
+
+```powershell
+.\tools\install-hooks.ps1
+```
+
+Installed hooks:
+- `pre-commit` (lightweight no-op)
+- `commit-msg` (runs `tools/ci.ps1`)
+
+Checks are skipped when:
+- commit message contains `[skip precommit hook]` or `[skip pch]`
+- there are no working tree changes (for example, `git commit --allow-empty ...`)
+
 ## Publishing
 
 This repository includes:
@@ -49,6 +75,14 @@ To publish from CI:
 2. Bump `ModuleVersion` in `GitAliases.Extras.psd1`.
 3. Push a tag `v<ModuleVersion>` (for example, `v0.1.0`) or run the publish workflow manually.
 
+## What CI checks
+
+- `PSScriptAnalyzer` linting with `PSScriptAnalyzerSettings.psd1`
+- `Pester` tests in `tests\`
+- GitHub Actions matrix on:
+  - Windows PowerShell
+  - PowerShell 7
+
 ## License
 
 WTFPL. See `LICENSE`.

tests/GitAliases.Extras.Module.Tests.ps1

@@ -47,3 +47,11 @@ Describe 'GitAliases.Extras module exports' {
         Get-Command Register-GitAliasCompletion -ErrorAction Stop | Should -Not -BeNullOrEmpty
     }
 }
+
+Describe 'GitAliases.Extras tooling' {
+    It 'includes install-hooks and hook templates' {
+        (Test-Path -LiteralPath (Join-Path $script:RepoRoot 'tools\install-hooks.ps1')) | Should -BeTrue
+        (Test-Path -LiteralPath (Join-Path $script:RepoRoot 'tools\hooks\pre-commit')) | Should -BeTrue
+        (Test-Path -LiteralPath (Join-Path $script:RepoRoot 'tools\hooks\commit-msg')) | Should -BeTrue
+    }
+}

tools/hooks/commit-msg

@@ -0,0 +1,37 @@
+#!/bin/sh
+set -e
+
+message_file="$1"
+if [ -z "$message_file" ] || [ ! -f "$message_file" ]; then
+  echo "commit-msg: missing commit message file"
+  exit 1
+fi
+
+# Allow opt-out tokens in the commit message.
+if grep -Eiq '\[skip[[:space:]]+precommit[[:space:]]+hook\]|\[skip[[:space:]]+pch\]' "$message_file"; then
+  echo "commit-msg: checks skipped by commit message tag"
+  exit 0
+fi
+
+# Skip expensive checks for no-op commits (for example, --allow-empty with no file changes).
+if [ -z "$(git status --porcelain)" ]; then
+  exit 0
+fi
+
+# Prevent hook-provided Git env vars from leaking into nested temp-repo tests.
+unset GIT_DIR
+unset GIT_WORK_TREE
+unset GIT_INDEX_FILE
+unset GIT_OBJECT_DIRECTORY
+unset GIT_ALTERNATE_OBJECT_DIRECTORIES
+unset GIT_COMMON_DIR
+unset GIT_PREFIX
+
+if command -v pwsh >/dev/null 2>&1; then
+  pwsh -NoProfile -ExecutionPolicy Bypass -File tools/ci.ps1
+elif command -v powershell >/dev/null 2>&1; then
+  powershell -NoProfile -ExecutionPolicy Bypass -File tools/ci.ps1
+else
+  echo "commit-msg: neither pwsh nor powershell is available"
+  exit 1
+fi

tools/hooks/pre-commit

@@ -0,0 +1,6 @@
+#!/bin/sh
+set -e
+
+# Validation runs in commit-msg, where Git provides the commit message file.
+# Keep pre-commit lightweight and deterministic.
+exit 0

tools/install-hooks.ps1

@@ -0,0 +1,35 @@
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+[string]$root = Resolve-Path -LiteralPath (Join-Path $PSScriptRoot '..') |
+    Select-Object -ExpandProperty Path -First 1
+
+$gitDir = (git -C $root rev-parse --git-dir 2>$null)
+if (-not $gitDir) {
+    throw "Not a git repository: $root"
+}
+
+$gitDir = $gitDir.Trim()
+$hookDir = if ([IO.Path]::IsPathRooted($gitDir)) {
+    Join-Path $gitDir 'hooks'
+} else {
+    Join-Path $root $gitDir 'hooks'
+}
+
+New-Item -ItemType Directory -Path $hookDir -Force | Out-Null
+
+$hookNames = @('pre-commit', 'commit-msg')
+foreach ($hookName in $hookNames) {
+    $source = Join-Path $root ("tools\hooks\{0}" -f $hookName)
+    $destination = Join-Path $hookDir $hookName
+
+    if (-not (Test-Path -LiteralPath $source)) {
+        throw "Hook source not found: $source"
+    }
+
+    Copy-Item -Path $source -Destination $destination -Force
+    Write-Host ("Installed {0} hook: {1}" -f $hookName, $destination)
+}