Documentation
¶
Overview ¶
Package workdir models the various local artifacts and state we keep inside a Terraform "working directory".
The working directory artifacts and settings are typically initialized or modified by "terraform init", after which they persist for use by other commands in the same directory, but are not visible to commands run in other working directories or on other computers.
Although "terraform init" is the main command which modifies a workdir, other commands do sometimes make more focused modifications for settings which can typically change multiple times during a session, such as the currently-selected workspace name. Any command which modifies the working directory settings must discard and reload any objects which derived from those settings, because otherwise the existing objects will often continue to follow the settings that were present when they were created.
Index ¶
- Constants
- type Dir
- func (d *Dir) DataDir() string
- func (d *Dir) ForcedPluginDirs() ([]string, error)
- func (d *Dir) NormalizePath(given string) string
- func (d *Dir) OriginalWorkingDir() string
- func (d *Dir) OverrideDataDir(dataDir string)
- func (d *Dir) OverrideOriginalWorkingDir(originalPath string)
- func (d *Dir) ProviderLocalCacheDir() string
- func (d *Dir) RootModuleDir() string
- func (d *Dir) SetForcedPluginDirs(dirs []string) error
Constants ¶
const PluginPathFilename = "plugin_path"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dir ¶
type Dir struct {
// contains filtered or unexported fields
}
Dir represents a single Terraform working directory.
"Working directory" is unfortunately a slight misnomer, because non-default options can potentially stretch the definition such that multiple working directories end up appearing to share a data directory, or other similar anomolies, but we continue to use this terminology both for historical reasons and because it reflects the common case without any special overrides.
The naming convention for methods on this type is that methods whose names begin with "Override" affect only characteristics of the particular object they're called on, changing where it looks for data, while methods whose names begin with "Set" will write settings to disk such that other instances referring to the same directories will also see them. Given that, the "Override" methods should be used only during the initialization steps for a Dir object, typically only inside "package main", so that all subsequent work elsewhere will access consistent locations on disk.
We're gradually transitioning to using this type to manage working directory settings, and so not everything in the working directory "data dir" is encapsulated here yet, but hopefully we'll gradually migrate all of those settings here over time. The working directory state not yet managed in here is typically managed directly in the "command" package, either directly inside commands or in methods of the giant command.Meta type.
func NewDir ¶
NewDir constructs a new working directory, anchored at the given path.
In normal use, mainPath should be "." to reflect the current working directory, with "package main" having switched the process's current working directory if necessary prior to calling this function. However, unusual situations in tests may set mainPath to a temporary directory, or similar.
WARNING: Although the logic in this package is intended to work regardless of whether mainPath is actually the current working directory, we're currently in a transitional state where this package shares responsibility for the working directory with various command.Meta methods, and those often assume that the main path of the working directory will always be ".". If you're writing test code that spans across both areas of responsibility then you must ensure that the test temporarily changes the test process's working directory to the directory returned by RootModuleDir before using the result inside a command.Meta.
func (*Dir) DataDir ¶
DataDir returns the base path where the reciever keeps all of the settings and artifacts that must persist between consecutive commands in a single session.
This is exported only to allow the legacy behaviors in command.Meta to continue accessing this directory directly. Over time we should replace all of those direct accesses with methods on this type, and then remove this method. Avoid using this method for new use-cases.
func (*Dir) ForcedPluginDirs ¶
ForcedPluginDirs returns a list of directories to use to find plugins, instead of the default locations.
Returns an zero-length list and no error in the normal case where there are no overridden search directories. If ForcedPluginDirs returns a non-empty list with no errors then the result totally replaces the default search directories.
func (*Dir) NormalizePath ¶
NormalizePath attempts to transform the given path so that it's relative to the working directory, which is our preferred way to present and store paths to files and directories within a configuration so that they can be portable to operations in other working directories.
It isn't always possible to produce a relative path. For example, on Windows the given path might be on a different volume (e.g. drive letter or network share) than the working directory.
Note that the result will be relative to the main directory of the receiver, which should always be the actual process working directory in normal code, but might be some other temporary working directory when in test code. If you need to access the file or directory that the result refers to with functions that aren't aware of our base directory, you can use something like the following, which again should be needed only in test code which might need to inspect the filesystem in order to make assertions:
filepath.Join(d.RootModuleDir(), normalizePathResult)
The above is suitable only for situations where the given path is known to be beneath the working directory, which is the typical situation for temporary working directories created for automated tests.
func (*Dir) OriginalWorkingDir ¶
OriginalWorkingDir returns the true, operating-system-originated working directory that the current Terraform process was launched from.
This is usually the same as the main working directory, but differs in the special case where the user ran Terraform with the global -chdir=... option. This is here only for a few backward compatibility affordances from before we had the -chdir=... option, so should typically not be used for anything new.
func (*Dir) OverrideDataDir ¶
OverrideDataDir chooses a specific alternative directory to read and write the persistent working directory settings.
"package main" can call this if it detects that the user has overridden the default location by setting the relevant environment variable. Don't call this when that environment variable isn't set, in order to preserve the default setting of a dot-prefixed directory directly inside the main working directory.
func (*Dir) OverrideOriginalWorkingDir ¶
OverrideOriginalWorkingDir records a different path as the "original working directory" for the reciever.
Use this only to record the original working directory when Terraform is run with the -chdir=... global option. In that case, the directory given in -chdir=... is the "main path" to pass in to NewDir, while the original working directory should be sent to this method.
func (*Dir) ProviderLocalCacheDir ¶
ProviderLocalCacheDir returns the directory we'll use as the working-directory-specific local cache of providers.
The provider installer's job is to make sure that all providers needed for a particular working directory are available in this cache directory. No other component may write here, and in particular a Dir object itself never reads or writes into this directory, instead just delegating all of that responsibility to other components.
Typically, the caller will ultimately pass the result of this method either directly or indirectly into providercache.NewDir, to get an object responsible for managing the contents.
func (*Dir) RootModuleDir ¶
RootModuleDir returns the directory where we expect to find the root module configuration for this working directory.
func (*Dir) SetForcedPluginDirs ¶
SetForcedPluginDirs records an overridden list of directories to search to find plugins, instead of the default locations. See ForcePluginDirs for more information.
Pass a zero-length list to deactivate forced plugin directories altogether, thus allowing the working directory to return to using the default search directories.
Source Files