# Golang go.mod<no value>

// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10004;
|===

== Description

The `golang/gomod` resource reads and writes a version inside a `go.mod` file. It works in two modes depending on whether `module` is set:

`module` unset:: The **Go language version** - the `go` directive.
`module` set:: The version of that **dependency** in the `require` block.

**source**::
Returns the version found.

**condition**::
Checks that the file records the expected version.

**target**::
Writes the version. A file already holding it is reported as `go.mod already set Golang version to "x"` (or `go.mod already has Module "m" set to version "v"`) and left untouched.

== Parameters

{{< resourceparameters "sources" "golang/gomod" >}}

`file`:: Defaults to `go.mod`.
`module`:: The module path, e.g. `github.com/sirupsen/logrus`. Leave unset to act on the `go` directive.
`indirect`:: Set it to act on a dependency marked `// indirect`.
`version`:: Overrides the source output.

=== Replace directives

`replace` and `replaceversion` address a `replace` instruction rather than a `require` one. Given:

[source,go]
----
replace moduleA v1.2.3 => moduleB v1.0.0
----

set `module: moduleA` (the module being *replaced*, on the left) and `replaceversion: v1.2.3` to pin which replace instruction is meant. Leaving `replaceversion` unset matches any version of that module.

== Limitations

[IMPORTANT]
====
A `golang/gomod` target updates `go.mod` and **does not touch `go.sum`**. The repository is left in a state where `go build` fails until the checksums are refreshed, so pair the target with a `shell` target running `go mod tidy` (as the example below does).
====

== Remote files

For a source and a condition, `file` accepts `https://`, `http://` and `file://`. A target must write locally.

== Example

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/golang/gomod/updatecli.d/default.yaml">}}
----

== Links

* link:https://go.dev/ref/mod#go-mod-file[The go.mod file reference]
* link:/docs/plugins/resource/golang/[The `golang` resource] - to find the language version to write here
* link:/docs/plugins/resource/gomodule/[The `golang/module` resource] - to find a module version