A Go code reordering tool that organizes declarations according to configurable conventions.

# Install
go install github.com/toejough/go-reorder/cmd/go-reorder@latest

# Check which files need reordering
go-reorder -c ./...

# Fix all files in place
go-reorder -w ./...

import "github.com/toejough/go-reorder"

// Reorder source code with default config
result, err := reorder.Source(sourceCode)

// Or with custom config
cfg, _ := reorder.LoadConfig(".go-reorder.toml")
result, err := reorder.SourceWithConfig(sourceCode, cfg)

Before - declarations scattered throughout the file:

package user

func validateEmail(email string) bool { return email != "" }

type User struct { ID int; Name string }

const MaxUsers = 100

func NewUser(name string) *User { return &User{Name: name} }

var defaultUser = &User{Name: "guest"}

func (u *User) String() string { return u.Name }

After - organized by convention:

package user

// Exported constants.
const (
    MaxUsers = 100
)

// Exported variables.
var (
    defaultUser = &User{Name: "guest"}
)

type User struct { ID int; Name string }

func NewUser(name string) *User { return &User{Name: name} }

func (u *User) String() string { return u.Name }

func validateEmail(email string) bool { return email != "" }

• Configurable ordering via TOML config files
• CLI tool for processing files and directories
• Library API for programmatic use
• Preserves all comments and documentation
• Groups types with their constructors and methods
• Handles enum types (iota blocks paired with their type definitions)
• Merges scattered const/var declarations into organized blocks
• Safety modes to prevent accidental code loss

go install github.com/toejough/go-reorder/cmd/go-reorder@latest

go get github.com/toejough/go-reorder

# Process a single file (output to stdout)
go-reorder main.go

# Process and write back to file
go-reorder -w main.go

# Process all Go files in a directory recursively
go-reorder -w ./...

# Check if files need reordering (exit 1 if changes needed)
go-reorder -c ./...

# Show diff of what would change
go-reorder -d main.go

# Read from stdin, write to stdout
cat main.go | go-reorder -

# Use explicit config file
go-reorder --config=.go-reorder.toml -w .

# Verbose output (shows config file, mode, file count)
go-reorder -v -w ./...

When --check finds files that need reordering, it shows details:

config: .go-reorder.toml

pkg/server/handler.go
  found:    Imports -> unexported functions -> Exported Types
  expected: Imports -> Exported Types -> unexported functions

pkg/server/utils.go
  sections: Imports -> Exported Functions
  issue:    within-section reordering needed (e.g., alphabetizing, type grouping)

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/toejough/go-reorder
    rev: main  # or specific version
    hooks:
      - id: go-reorder        # Auto-fix files
      # OR
      - id: go-reorder-check  # Check only (CI-friendly)

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]

jobs:
  reorder-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.23'
      - run: go install github.com/toejough/go-reorder/cmd/go-reorder@latest
      - run: go-reorder -c ./...

.PHONY: reorder reorder-check

reorder:
	go-reorder -w ./...

reorder-check:
	go-reorder -c ./...

// Reorder fixes declaration ordering in all Go files.
func Reorder() error {
    return sh.Run("go-reorder", "-w", "./...")
}

// ReorderCheck verifies declaration ordering without modifying files.
func ReorderCheck() error {
    return sh.Run("go-reorder", "-c", "./...")
}

Add to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "go-reorder: fix",
      "type": "shell",
      "command": "go-reorder",
      "args": ["-w", "${file}"],
      "problemMatcher": [],
      "presentation": { "reveal": "silent" }
    },
    {
      "label": "go-reorder: check all",
      "type": "shell",
      "command": "go-reorder",
      "args": ["-c", "./..."],
      "problemMatcher": []
    }
  ]
}

Run with Ctrl+Shift+P → "Tasks: Run Task" → select task.

The CLI automatically discovers config files by walking up from the processed file's directory. It stops when it finds:

1. .go-reorder.toml - uses this config
2. .git directory - stops searching, uses defaults
3. go.mod file - stops searching, uses defaults

This means you can have different configs for different modules in a monorepo.

[sections]
order = [
  "imports",
  "main",
  "init",
  "exported_consts",
  "exported_enums",
  "exported_vars",
  "exported_types",
  "exported_funcs",
  "unexported_consts",
  "unexported_enums",
  "unexported_vars",
  "unexported_types",
  "unexported_funcs",
  "uncategorized",
]

[types]
type_layout = ["typedef", "constructors", "exported_methods", "unexported_methods"]
enum_layout = ["typedef", "iota", "exported_methods", "unexported_methods"]

[behavior]
mode = "strict"  # strict | warn | append | drop

For type_layout:

• typedef - The type definition itself
• constructors - Constructor functions (functions named NewTypeName or NewXxxTypeName)
• exported_methods - Exported methods on the type
• unexported_methods - Unexported methods on the type

For enum_layout:

• typedef - The enum type definition (e.g., type Status int)
• iota - The associated iota const block
• exported_methods / unexported_methods - Methods on the enum type

Default config works well. Types grouped with constructors and methods.

[sections]
order = [
  "imports",
  "exported_consts",
  "exported_vars",
  "exported_types",      # Models, services
  "unexported_types",    # Internal helpers
  "unexported_funcs",    # Internal helpers
  "exported_funcs",      # Handlers last - easy to find
  "uncategorized",
]

[sections]
order = [
  "imports",
  "main",                # Entry point at top
  "init",
  "exported_types",      # Command structs
  "exported_funcs",      # Command implementations
  "unexported_funcs",
  "uncategorized",
]

[behavior]
mode = "append"  # Don't error on uncategorized code

package main

import (
    "os"
    "github.com/toejough/go-reorder"
)

func main() {
    content, _ := os.ReadFile("example.go")

    // Reorder with default config
    reordered, err := reorder.Source(string(content))
    if err != nil {
        panic(err)
    }

    os.WriteFile("example.go", []byte(reordered), 0644)
}

// Load config from file
cfg, err := reorder.LoadConfig(".go-reorder.toml")
if err != nil {
    panic(err)
}

// Or use default and modify
cfg := reorder.DefaultConfig()
cfg.Behavior.Mode = "append"

// Reorder with config
reordered, err := reorder.SourceWithConfig(string(content), cfg)

For advanced use cases, work directly with parsed AST files using dave/dst:

import (
    "go/token"
    "github.com/dave/dst/decorator"
    "github.com/toejough/go-reorder"
)

// Parse source to DST
dec := decorator.NewDecorator(token.NewFileSet())
file, err := dec.Parse(sourceCode)
if err != nil {
    panic(err)
}

// Reorder in place
err = reorder.File(file)  // or FileWithConfig(file, cfg)
if err != nil {
    panic(err)
}

// Modify the AST further if needed
// ...

// Print back to source
res := decorator.NewRestorer()
var buf bytes.Buffer
res.Fprint(&buf, file)
result := buf.String()

Without a config file, declarations are ordered as:

1. Imports
2. main() function
3. init() functions (original order preserved)
4. Exported constants
5. Exported enums (type + iota block + methods)
6. Exported variables
7. Exported types (type + constructors + methods)
8. Exported functions
9. Unexported constants
10. Unexported enums
11. Unexported variables
12. Unexported types
13. Unexported functions
14. Uncategorized (catch-all)

Within each section, declarations are sorted alphabetically. Types group their constructors (functions matching New*TypeName) and methods together.

go-reorder --init              # Create config
go-reorder -d ./...            # Preview changes
go-reorder -w ./...            # Apply changes

go-reorder -c ./...            # Exit 1 if changes needed

[sections]
order = [
  "imports",
  "exported_types",      # Models first
  "unexported_types",
  "unexported_funcs",
  "exported_funcs",      # Handlers last
  "uncategorized",
]

• Import ordering - Use goimports or gci for that
• Code formatting - Use gofmt or gofumpt
• Linting - Use golangci-lint
• Build constraint handling - Files with //go:build are processed normally
• cgo export comments - //export comments are preserved but not specially handled
• Cross-file analysis - Each file is processed independently

Your config doesn't include a section for some code. Options:

1. Add the missing section to your config's order array
2. Add uncategorized to catch everything else
3. Use mode = "append" to be lenient

The ./... pattern uses Go's package discovery. For non-Go directories, specify paths explicitly:

go-reorder -w ./scripts/*.go ./tools/*.go

Use -v (verbose) to see which config is loaded:

go-reorder -v -c ./...
# Output: config: /path/to/.go-reorder.toml
# Or:     config: using defaults

1. Check your config file syntax (TOML)
2. Verify section names are spelled correctly
3. Use -d to see what would change before -w

Constructors must match the pattern New*TypeName where TypeName is exact. Examples:

• NewUser matches User
• NewMockUser matches User
• CreateUser does NOT match (no New prefix)

MIT - See LICENSE file for details.

Built with dave/dst for AST manipulation that preserves comments.

Originally developed as part of the imptest project.