This page helps you get started hacking on the Git Town codebase. See file ARCHITECTURE.md for an overview of how the Git Town engine works.
- install Go version 1.21
- install Make
- Mac and Linux users have this out of the box
- Windows users can install
Make for Windows or
run
choco install make
if Chocolatey is available.
- run all tests:
make test
- install the tool locally:
make build
- run a quick test suite during development:
make test-go
Add an external Go module:
- run
go get [dependency]
inside the Git Town folder to register the dependency - use the new dependency in the code
- run
go mod vendor
to vendor it - run
go mod tidy
to clean up
Update an external Go module:
go get <path>
Update all external Go modules:
make update
Run all unit tests:
make unit-all
Run all unit tests with race detection:
make unit-race
Run unit tests for packages containing changes:
make unit
Run an individual unit test:
go test src/cmd/root_test.go
go test src/cmd/root_test.go -v -run TestIsAcceptableGitVersion
Run all end-to-end tests:
make cuke
To run individual Cucumber tests, add a @this
flag to the test you want to
run. Example:
@this
Scenario: foo bar
Then run:
make cukethis
Certain tests require that the Git remote points to an actual GitHub, Gitea,
GitLab or Bitbucket address. This causes git push
operations in this test to
also go to GitHub. To prevent this, set an environment variable
GIT_TOWN_REMOTE
with the desired value of the origin
remote, and Git Town
will use that value instead of what is in the repo.
If Cucumber tests produce garbled output on Windows, try running them inside Git Bash. See this issue for details.
Inspect basic variables:
fmt.Printf("%#v\n", variable)
Inspect more complex variables:
import "github.com/davecgh/go-spew/spew"
spew.Dump(variable)
To see the CLI output of the shell commands in a Cucumber test, as well as the
Git commands that the Git Town test suite runs under the hood, add a tag
@debug
above the feature or scenario you want to debug:
@debug @this
Scenario: A foo walks into a bar
To see all Git commands that the test runner and the Git Town command execute,
runs the Git Town command with the --verbose
option. As an example, if the
step When I run "git-town append new"
mysteriously fails, you could change it
to When I run "git-town append new -v"
. Also enable @debug
to see the output
on the console.
To get a quick glance of which status the repo is at any point in time, insert
the step And display "<command_>"
running whatever command you want to execute
in the Git repo under test. Example: And display "git status"
.
To manually inspect the local and remote Git repositories used in an end-to-end
test, insert the step And inspect the repo
. This step will make Cucumber print
the path of the workspace and wait until you hit ENTER.
Debug a Godog Cucumber feature in VSCode:
- open
main_test.go
- change the path of the test to execute
- set a breakpoint in your test code
- run the
debug a test
configuration in the debugger
End-to-end tests sometimes hang due to Git Town waiting for input that the test doesn't define. To find the hanging test:
- open
main_test.go
- find the call to
godog.RunWithOptions
and adjust its arguments:- Make the
Paths
field more specific, for example by changing it from "features" to "features/sync/current_branch". Now it runs only the tests in that subfolder. - To see the executed steps in the output, change
Format
topretty
andConcurrency
to 1. This reduces the speed at which the end-to-end tests execute.
- Make the
Format all code, auto-fix all fixable issues, and run all linters:
make fix
Run git town debug
to see the commands to display Git Town's dialogs.
The source code contains Godoc comments that explain the code architecture.
The source code for the website is in the
website folder. This folder contains its own
Makefile for activities related to working on the website.
To work on the website, cd into the website
folder and run
make serve
to start a local
development server. The production site auto-updates on changes to the main
branch. The site hoster is Netlify. Netlify
configuration is in netlify.toml.