txeh-v1.8.0

Features

• DNS cache flush after hosts file changes (#43, #48)
  • Library: FlushDNSCache() function, AutoFlush option in HostsConfig
  • CLI: --flush / -f flag, TXEH_AUTO_FLUSH=1 env var
  • macOS: dscacheutil -flushcache + killall -HUP mDNSResponder
  • Linux: resolvectl flush-caches (systemd 239+), falls back to systemd-resolve --flush-caches
  • Windows: ipconfig /flushdns
  • Flush failures are non-fatal. The hosts file is saved, a warning is printed to stderr.

Improvements

• Refactored CLI mutation commands (add, remove host/ip/cidr/comment) to use shared saveHosts helper
• Descriptive error message when Linux has no systemd-resolved (explains that flushing isn't needed)
• Source citations in platform flush implementations (man pages, vendor docs)

Fixes

• Build-tag platform-specific tests so they only compile on the correct OS
• Bump Go from 1.24.4 to 1.24.7 (fixes GO-2025-3956 os/exec.LookPath vuln)

Documentation

• CLI reference: --flush flag, TXEH_AUTO_FLUSH, platform requirements table
• Troubleshooting: cross-reference to --flush from manual flush instructions

Changelog

Others

• 99a9be8 Add DNS cache flush support (--flush flag) (#48)
• 7e2837d housekeeping: fix OpenSSF Scorecard token permissions and pin docs deps (#42)
• e181697 housekeeping: tighten linting, testing, and verification standards (#47)

txeh-v1.7.2

Features

• Enterprise-grade CI pipeline, linting, and code quality tooling (#31)
• Fuzz tests, property-based tests, dead code detection (#37)

Improvements

• CLI cmd package test coverage: 44.7% to 81.6% (#39)
• Overall test coverage: 90.2% to 92.4% (#39)
• Documentation overhaul (#38)
• README attribution footer (#39)

Fixes

• Fix cosign signing to use --bundle flag for cosign v2.4+ (#40)
• Fix goreleaser homebrew formula push to use HOMEBREW_TAP_TOKEN (#41)

Dependencies

• Bump github.com/spf13/cobra from 1.9.1 to 1.10.2 (#33)

CI

• Bump codecov/codecov-action (#32)
• Bump github/codeql-action (#34)
• Bump ossf/scorecard-action (#35)
• Bump securego/gosec (#36)

Changelog

Others

• 50162d4 Add fuzz tests, property-based tests, dead code detection, and docs CNAME (#37)
• fe7ba4e Documentation Overhaul (#38)
• 2ca0f7c Feat/enterprise standards (#31)
• d2f988f Test Coverage, CLAUDE.md, and README Footer (#39)
• bedfe2c chore(ci): bump codecov/codecov-action (#32)
• c1d8a21 chore(ci): bump github/codeql-action (#34)
• aecd4be chore(ci): bump ossf/scorecard-action (#35)
• 2d8d0ca chore(ci): bump securego/gosec (#36)
• 319b00b chore(deps): bump github.com/spf13/cobra from 1.9.1 to 1.10.2 (#33)
• 77ad396 housekeeping: add HOMEBREW_TAP_TOKEN to .goreleaser.yml (#41)
• fa1f898 housekeeping: update .goreleaser.yml to adjust signing args and output configuration (#40)

txeh-v1.7.0

This release introduces two major features: inline comment support for organizing and tracking host entries, and MaxHostsPerLine for controlling line length (particularly important for Windows compatibility).

---

New Features

1. Inline Comment Support

Host entries can now include comments for organization, tracking, and grouping. Comments follow the standard hosts file format: IP HOSTNAME [HOSTNAME...] # comment

How Comments Work

• Grouping by comment: Hosts with the same IP AND same comment are placed on the same line
• Comment isolation: Hosts added without a comment only match lines without a comment
• Comment matching: Hosts added with a comment only match lines with the same comment
• Comment preservation: Comments are never modified on existing lines
• New line creation: If no matching line exists, a new line is created

Library API

// Add hosts with a comment (for grouping/tracking)
hosts.AddHostWithComment("127.0.0.1", "myapp", "local development")
hosts.AddHostsWithComment("127.0.0.1", []string{"svc1", "svc2"}, "my project services")

// Add hosts without a comment (original behavior)
hosts.AddHost("127.0.0.1", "myhost")
hosts.AddHosts("127.0.0.1", []string{"a", "b", "c"})

// List all hosts with a specific comment
devHosts := hosts.ListHostsByComment("local development")

// Remove all entries with specific comments
hosts.RemoveByComment("old environment")
hosts.RemoveByComments([]string{"deprecated", "temp"})

CLI Usage

# Add host with a comment
sudo txeh add 127.0.0.1 myapp --comment "local development"
# Result: 127.0.0.1        myapp # local development

# Add another host with the same comment (groups together)
sudo txeh add 127.0.0.1 myapp2 --comment "local development"
# Result: 127.0.0.1        myapp myapp2 # local development

# Add host with a different comment (new line)
sudo txeh add 127.0.0.1 api --comment "staging environment"
# Result: 127.0.0.1        api # staging environment

# List all hosts with a specific comment
sudo txeh list bycomment "local development"

# Remove all entries with a specific comment
sudo txeh remove bycomment "local development"

---

2. MaxHostsPerLine Configuration

Control the maximum number of hostnames per line. This is particularly important for Windows, which only reads the first 9 hostnames per line (additional hostnames are silently ignored).

Note: The Windows 9-host limit is empirically observed behavior, not officially documented by Microsoft. See: kubefwd#258, ddev#948, crc#2710

Configuration Values

Value	Behavior
0 (default)	Auto mode: 9 hosts per line on Windows, unlimited elsewhere
-1	Force unlimited (no wrapping)
>0	Explicit limit (e.g., 5 means max 5 hosts per line)

Library API

hosts, err := txeh.NewHosts(&txeh.HostsConfig{
    MaxHostsPerLine: 9,  // Explicit limit
})

// Or use auto mode (default)
hosts, err := txeh.NewHostsDefault()  // Uses 9 on Windows, unlimited elsewhere

CLI Usage

# Set explicit limit
sudo txeh add 127.0.0.1 host1 host2 host3 --max-hosts-per-line 2

# Use auto mode (default, 9 on Windows)
sudo txeh add 127.0.0.1 host1 host2 host3

# Force unlimited
sudo txeh add 127.0.0.1 host1 host2 host3 --max-hosts-per-line -1

---

CLI Changes

New Flags

Flag	Short	Description
--comment	-c	Add comment to host entry (for add command)
--max-hosts-per-line	-m	Max hostnames per line (0=auto, -1=unlimited, >0=explicit)

New Subcommands

Command	Description
txeh list bycomment "COMMENT"	List all hosts with a specific comment
txeh remove bycomment "COMMENT"	Remove all entries with a specific comment

---

API Additions

New Methods

Method	Description
AddHostWithComment(address, hostname, comment string)	Add a host with an inline comment
AddHostsWithComment(address string, hostnames []string, comment string)	Add multiple hosts with an inline comment
ListHostsByComment(comment string) []string	Get all hostnames with a specific comment
RemoveByComment(comment string)	Remove all entries with a specific comment
RemoveByComments(comments []string)	Remove all entries with any of the specified comments

New HostsConfig Field

Field	Type	Description
MaxHostsPerLine	int	Maximum hostnames per line (0=auto, -1=unlimited, >0=explicit)

---

Use Cases

Tracking Tool-Managed Entries

# Docker adding entries
sudo txeh add 127.0.0.1 app.local --comment "docker"

# Kubernetes port-forward (kubefwd)
sudo txeh add 127.0.0.1 myservice.mynamespace --comment "kubefwd"

# Clean up all entries from a specific tool
sudo txeh remove bycomment "docker"

Development Environment Organization

# Add dev services
sudo txeh add 127.0.0.1 api.local web.local --comment "dev services"
sudo txeh add 127.0.0.1 db.local cache.local --comment "dev services"

# Add staging services (separate line)
sudo txeh add 192.168.1.100 api.staging --comment "staging"

# List dev services
sudo txeh list bycomment "dev services"

Modifying Comments

Comments are never modified on existing lines. To change a comment, remove and re-add:

# Remove all entries with the old comment
sudo txeh remove bycomment "old comment"

# Re-add with the new comment
sudo txeh add 127.0.0.1 app1 app2 --comment "new comment"

---

Full Changelog

Features

• Add inline comment support for host entries
• Add AddHostWithComment() and AddHostsWithComment() methods
• Add ListHostsByComment() method
• Add RemoveByComment() and RemoveByComments() methods
• Add --comment / -c flag to CLI add command
• Add list bycomment CLI subcommand
• Add remove bycomment CLI subcommand
• Add MaxHostsPerLine configuration option
• Add --max-hosts-per-line / -m CLI flag
• Auto-detect Windows and apply 9-host limit by default

Testing

• Add comprehensive tests for comment functionality
• Add tests for MaxHostsPerLine and Windows 9-host limit
• Add whitespace handling tests for comments

Documentation

• Add comprehensive "Comments" section to README
• Document comment matching behavior
• Add CLI and library usage examples
• Update CLI help output with new flags

---

Installation

CLI

# Using Go install (requires Go 1.24+)
go install github.com/txn2/txeh/txeh@v1.7.0

# Using Homebrew
brew install txn2/tap/txeh

Library

go get github.com/txn2/txeh@v1.7.0

---

Checksums

See the assets below for SHA256 checksums of all release binaries.

txeh-v1.6.0

This release contains critical bug fixes addressing thread safety, parsing edge cases, and panic conditions. It also includes a breaking API change to improve data safety, enhanced Windows compatibility, and significantly expanded test coverage.

---

Breaking Changes

GetHostFileLines() Return Type Changed

GetHostFileLines() now returns HostFileLines (value) instead of *HostFileLines (pointer).

Reason: The previous implementation returned a pointer to internal state, which allowed external code to modify the Hosts struct's data without going through the mutex-protected API. This created potential data races and violated encapsulation.

Migration:

// Before (v1.5.x)
lines := hosts.GetHostFileLines()
for i := range *lines {
    line := (*lines)[i]
    // ...
}

// After (v1.6.0)
lines := hosts.GetHostFileLines()
for i := range lines {
    line := lines[i]
    // ...
}

---

Bug Fixes

1. Last Line Dropped When Hosts File Has No Trailing Newline

When parsing a hosts file that did not end with a newline character, the last line was silently dropped. This could result in missing host entries. The parser now correctly handles files regardless of whether they end with a newline.

2. GetHostFileLines Data Race Fixed

As noted in the breaking changes section, GetHostFileLines() now returns a defensive copy of the internal data. This prevents data races when the returned slice is accessed concurrently with modifications to the Hosts struct.

3. TOCTOU Race Condition in AddHost

The AddHost method had a time-of-check-to-time-of-use (TOCTOU) race condition where it would release the mutex between checking existing entries and adding new ones. The lock is now held for the entire operation, ensuring atomic read-modify-write behavior.

4. Nil Pointer Panic in ListHostsByCIDR

Calling ListHostsByCIDR with an invalid CIDR string (e.g., malformed or unparseable) would cause a nil pointer panic. The method now validates input and returns an empty result for invalid CIDR strings instead of panicking.

---

New Features and Improvements

Windows Hosts File Location

The Windows hosts file location is now determined using the SystemRoot environment variable instead of assuming C:\Windows. This improves compatibility with non-standard Windows installations where the system root is on a different drive or path.

Contributors: @errpunk (PR #27)

Code Quality Improvements

• Updated to Go 1.23
• Applied gofumpt and gofmt formatting
• Fixed all staticcheck warnings
• Improved error handling for deferred file operations in tests

Contributors: @shantanugadgil (PR #29)

---

Test Coverage

This release includes a significant expansion of the test suite:

• Over 1,500 lines of new test code
• Comprehensive CLI integration tests covering all commands
• Library unit tests for edge cases and error conditions
• Regression tests for all bug fixes listed above
• Race condition tests to verify thread safety

---

Upgrade Recommendations

All users should upgrade. The parsing bug that drops the last line when files lack a trailing newline could cause silent data loss. The thread safety fixes are important for any concurrent usage of the library.

If you have code that depends on GetHostFileLines(), see the migration guide in the Breaking Changes section above.

---

Full Changelog

Bug Fixes

• Fix last line being dropped when hosts file has no trailing newline
• Fix data race in GetHostFileLines by returning a copy
• Fix TOCTOU race condition in AddHost
• Fix nil pointer panic in ListHostsByCIDR with invalid CIDR

Enhancements

• Use SystemRoot environment variable for Windows hosts file location
• Update to Go 1.23
• Apply gofumpt/gofmt formatting
• Fix staticcheck warnings

Testing

• Add comprehensive CLI integration tests
• Add library unit tests for edge cases
• Add regression tests for all bug fixes

Documentation

• Update README with clarified Go install requirements
• Add Go Reference badge
• Add feature list and fix typos

---

Contributors

Thank you to the contributors who helped with this release:

• @errpunk - Windows SystemRoot environment variable support
• @shantanugadgil - Go version update and staticcheck fixes

---

Installation

CLI

# Using Go install (requires Go 1.23+)
go install github.com/txn2/txeh/txeh@v1.6.0

# Using Homebrew
brew install txn2/tap/txeh

Library

go get github.com/txn2/txeh@v1.6.0

---

Checksums

See the assets below for SHA256 checksums of all release binaries.

txeh-v1.5.4 craig

Changelog

• 3446338 Merge pull request #23 from txn2/add-support-for-go-install
• f9fd663 Update documentation for release
• ec2d936 Update version management
• 224ab3b Add support for 'go install' command
• 6a28df2 housekeeping

txeh-v1.5.3 craig

Changelog

• e8cdde2 small go test for each method
• f47bf69 added RemoveCIDRs
• bec8513 trim spaces for host address
• c4fba31 added locks for list methods
• 52bfc1a test update

txeh-v1.5.2 craig

Changelog

• 138208f added the ability to create a Hosts object with a string (RawText)
• ae6552a added simple test
• c879719 fixed typos and documentation cleanup
• fd6fec4 added list command to cli, along with new hosts methods ListHostsByIP, ListHostsByCIDR and ListAddressesByHost
• 171fcae housekeeping, fixed typos and deprications
• ca3571a upgrade Go to 1.20, upgrade all packages

txeh-v1.4.0 craig

Changelog

• 16104e9 housekeeping
• 6c60742 build update
• 1df13ff go 1.19
• d454958 Merge pull request #21 from girishsg24/supportdualstack
• 0c4a4f4 support dualstack entries in /etc/hosts file
• 8a33103 Merge pull request #18 from mattkasun/master
• 4d96640 remove erroneous extra blank line during parse
• b4a4cf7 Merge pull request #16 from docooler/master
• cd12e07 Update txeh.go
• 09e2953 Merge pull request #11 from chinglinwen/master
• a69484b fixes #10 handle no newline issue

txeh-v1.3.0 cjimti

Changelog

b5c7075 Merge pull request #5 from tommyblue/master
dc65154 Add 'show' argument to print the /etc/hosts file

txeh-v1.2.2 cjimti

Changelog

fd1228d Merge pull request #3 from adityadani/master
2430ff0 Handle trailing comments on a valid /etc/hosts entry.