Step Over to Go Part 1 of 50
  1. 1 Goodbye .csproj, Hello go.mod
  2. 2 The Phrasebook: C# Concepts in Go Terms
  3. 3 You Know .NET, Now Meet the Go Toolchain
  4. 4 No Enums? No Problem (Sort Of)
  5. 5 Generics: Late to the Party
  6. 6 The Million Dollar Mistake, Differently
  7. 7 Your Class Is Now a Struct (And That's Fine)
  8. 8 Where Did My Properties Go?
  9. 9 if err != nil: Your New Reality
  10. 10 Panic and Recover: The Emergency Exit
  11. 11 The switch Statement You Always Wanted
  12. 12 Stack vs Heap: Go's Escape Analysis
  13. 13 Pointers Without the Pain
  14. 14 Slices Are Not Arrays (And Neither Is List<T>)
  15. 15 Channels: The sync You Didn't Know You Wanted
  16. 16 Context Is King
  17. 17 Async/Await vs Goroutines: A Mindset Shift
  18. 18 select: Multiplexing Like a Pro
  19. 19 Mutexes and WaitGroups: When Channels Aren't the Answer
  20. 20 The Empty Interface and Type Assertions
  21. 21 Composition Over Inheritance (For Real This Time)
  22. 22 Implicit Interfaces: Scary Then Brilliant
  23. 23 Benchmarks and Profiling Out of the Box
  24. 24 Mocking in a Language Without Mockito
  25. 25 Multi-Module Repos: Monorepo Thinking
  26. 26 Organising a Real Project
  27. 27 Testing Without a Framework
  28. 28 Configuration Without IOptions<T>
  29. 29 Database Access: database/sql vs Entity Framework
  30. 30 Debugging: Delve vs Visual Studio's Comfort
  31. 31 Generate All the Things
  32. 32 GORM and Friends: When You Do Want an ORM
  33. 33 HTTP Services: net/http vs ASP.NET Core
  34. 34 JSON: Struct Tags and the Marshal Dance
  35. 35 Linting and Formatting: gofmt Is Non-Negotiable
  36. 36 Logging: slog and the Structured Logging Story
  37. 37 Shrinking Binaries and Build Tags
  38. 38 Dockerfile for Go: Simpler Than You'd Think
  39. 39 GitHub Actions for Go Projects
  40. 40 Health Checks and Readiness Probes
  41. 41 Kubernetes and Go: A Natural Fit
  42. 42 AWS Lambda and Go: Cold Starts That Don't Hurt
  43. 43 Metrics, Traces, and Logs: The OpenTelemetry Way
  44. 44 Single Binary Deploys: The Killer Feature
  45. 45 Versioning Your Modules
  46. 46 What I Actually Miss From C#
  47. 47 What I'll Never Go Back For
  48. 48 Six Months In: Was It Worth It?
  49. 49 Forty-Eight Posts on Moving From C# to Go, in the Right Order
  50. 50 Range-Over-Func Iterators for People Who Miss LINQ
About this series

Goodbye .csproj, Hello go.mod

Right, let's talk about dependencies. In .NET land, we've got NuGet, .csproj files, PackageReference elements, version ranges, transitive dependencies, and packages.lock.json if we're being careful. It's a mature ecosystem with excellent tooling.

Go does things differently. There's no NuGet. There's no package registry at all, actually. And that sounds mental until you understand why. It works rather well.

The go.mod File

Every Go module has a go.mod file at its root. Here's a real one:

module github.com/yourname/yourproject

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/stretchr/testify v1.8.4
)

require (
    github.com/bytedance/sonic v1.9.1 // indirect
    github.com/gabriel-vasile/mimetype v1.4.2 // indirect
    // ... more indirect dependencies
)

Let's break this down.

Module Declaration

module github.com/yourname/yourproject

This is your module's identity, its import path. When someone writes import "github.com/yourname/yourproject/pkg/whatever", Go knows where to find it because of this declaration.

Unlike a .csproj where the assembly name is mostly internal, this path is the identifier. Choose it thoughtfully.

Go Version

go 1.22

This declares the minimum Go version required. Not quite the same as <TargetFramework>net8.0</TargetFramework>. You're not compiling for a specific runtime. You're just saying “this code uses features from Go 1.22, don't try to build it with something older.”

Dependencies

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/stretchr/testify v1.8.4
)

Here's where it gets interesting. These are your direct dependencies, the packages you actually import in your code.

Notice the format: module-path version. The version uses semantic versioning prefixed with v. No version ranges. No floating versions. Exactly this version, every time.

Indirect Dependencies

require (
    github.com/bytedance/sonic v1.9.1 // indirect
)

The // indirect comment marks transitive dependencies, packages that your dependencies need, but you don't import directly. Go tracks these explicitly in go.mod.

No Central Registry

This confused me coming from NuGet: Go doesn't have a package registry.

NuGet has nuget.org. npm has npmjs.com. Go has… URLs.

When you go get github.com/gin-gonic/gin, Go literally fetches from GitHub. The module path isn't an identifier that maps to a registry. It's a resolvable URL (with some clever translation rules).

This means:

  • No registry account needed to publish
  • No central point of failure
  • Dependencies are wherever their code lives

But also:

  • No central search (though pkg.go.dev indexes public modules)
  • No private registry without extra setup
  • Version discovery is… different

Adding Dependencies

Here's the workflow comparison:

In .NET

dotnet add package Newtonsoft.Json --version 13.0.3

Or edit your .csproj:

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

Then dotnet restore.

In Go

go get github.com/gin-gonic/gin@v1.9.1

Or just import it in your code:

import "github.com/gin-gonic/gin"

Then run go mod tidy. Go will fetch the dependency, resolve versions, and update go.mod automatically.

That go mod tidy command is your friend. It adds missing dependencies, removes unused ones, and generally keeps your go.mod clean. I run it roughly as often as I save files.

Version Selection

Go's approach to version selection is refreshingly simple, and it took me a while to appreciate it.

The Problem With Version Ranges

In NuGet, you might declare:

<PackageReference Include="SomeLib" Version="[1.0, 2.0)" />

Meaning “any version from 1.0 up to but not including 2.0.” The actual version you get depends on what's available, what other packages need, and the resolver's algorithm.

This flexibility is powerful but creates problems:

  • Different machines might resolve different versions
  • Lock files become essential
  • “Works on my machine” is often a version resolution issue

Go's Minimum Version Selection

Go uses something called Minimum Version Selection (MVS). The idea: given all the version constraints, pick the minimum version that satisfies everything.

If you require v1.9.1 and a dependency requires v1.8.0 of the same module, Go picks v1.9.1. The minimum version that satisfies both.

No ranges. No “latest compatible.” Just: here are the minimums everyone needs, let's use those.

The result? Given the same go.mod and go.sum files, you'll always get exactly the same versions. No lock file randomness. No surprising upgrades.

The go.sum File

Speaking of which, go.sum is Go's integrity file:

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5...
github.com/gin-gonic/gin v1.9.1/go.mod h1:RdK04...

It contains cryptographic hashes of every dependency. If a module's contents don't match the recorded hash, the build fails.

Commit this file. It's your guarantee of reproducible builds.

Updating Dependencies

The version-pinning approach means updates are explicit:

# Update a specific dependency
go get github.com/gin-gonic/gin@v1.10.0

# Update all dependencies to latest minor/patch
go get -u ./...

# Update all dependencies to latest (including major)
go get -u=patch ./...

There's no equivalent to NuGet's floating versions. When you want an update, you ask for it specifically. Some find this tedious; I find it clarifying.

Major Versions Are Different Modules

Here's where Go does something clever (and initially bewildering).

In semantic versioning, major version bumps signal breaking changes. v2.0.0 might have a completely different API from v1.9.0.

Go handles this by treating major versions as different modules:

// v1.x
import "github.com/go-redis/redis/v8"

// v9.x (yes, they jumped)
import "github.com/redis/go-redis/v9"

The import path includes the major version. v2, v3, etc. are literally different modules.

This means:

  • You can use v1 and v2 of the same library simultaneously (different import paths)
  • Breaking changes are impossible to accidentally adopt
  • Library authors must maintain separate module paths for major versions

It's awkward at first. Then you realise you've never had a build broken by an accidental major version upgrade.

The Comparison

Aspect NuGet/.csproj Go Modules
Registry Central (nuget.org) Distributed (any URL)
Version syntax Ranges allowed Exact versions only
Resolution Complex algorithm Minimum Version Selection
Lock file Optional but recommended go.sum (hashes only)
Private packages Private feeds Various options (GOPROXY)
Major versions Same package ID Different module paths

What Actually Trips You Up

After a few weeks, here's what caught me out:

Import Path Confusion

Your IDE might autocomplete an import as github.com/gin-gonic/gin/v2 when you wanted v1. Check your imports when things don't compile.

Forgetting go mod tidy

Add an import, wonder why it doesn't work, realise you never fetched the dependency. go mod tidy. Learn to love it.

Private Repositories

Public modules “just work.” Private repos need GOPROXY configuration or GOPRIVATE settings. It's not hard, but it's not automatic either.

Vendor Directory

Go can vendor dependencies (copy them into a vendor/ directory in your project). Some teams mandate this for reproducibility. If you see a vendor directory, know that go build will use it by default.

The Honest Take

Things I like better than NuGet:

  • Reproducibility. Same inputs, same outputs, always.
  • No central registry dependency. Dependencies are just code at URLs.
  • Major version handling. Breaking changes are structurally isolated.
  • Simplicity. One file, explicit versions, done.

Things I miss from NuGet:

  • Proper package search. pkg.go.dev is decent but not nuget.org.
  • Private feeds. Azure Artifacts, MyGet, etc. are more polished than GOPROXY setup.
  • .NET's tooling. dotnet add package with tab completion is lovely.
  • Version ranges. Sometimes I want “latest patch version” and Go says no.

Things that are just different:

  • Import paths being URLs. It's not better or worse, just a different model.
  • go.sum vs lock files. Similar goal, different mechanism.
  • The vendor directory. Some love it, some ignore it entirely.

The Philosophy

There's a reason Go's dependency management feels different: it was designed later, learning from problems with other systems.

The Ruby and Node ecosystems taught us that flexible version resolution leads to “works on my machine” nightmares. Go said: fine, no flexibility. Exact versions always.

The npm left-pad incident taught us that central registries are single points of failure. Go said: fine, no central registry. Your dependencies are wherever their source code lives.

Whether you prefer this philosophy is personal. But understanding why Go made these choices helps you work with the system rather than fighting it.


Next in the series: packages and imports. Why Go's package system is nothing like namespaces, and how to stop your C# brain from making it harder than it needs to be.