From 5e4361579653a035b254aea35f8e1e7545c46d50 Mon Sep 17 00:00:00 2001 From: Steven Schattenberg Date: Wed, 9 Apr 2025 10:43:04 -0500 Subject: [PATCH] copy edits of comments and docs --- Makefile | 10 +-- cmd/commands.go | 2 +- cmd/root.go | 2 +- docs/commands-quick-reference.md | 4 +- docs/configuration-reference.md | 115 +++++++++++++++--------------- docs/index.md | 1 - docs/running-from-source.md | 16 ++--- docs/working-with-repositories.md | 15 ++-- 8 files changed, 78 insertions(+), 87 deletions(-) diff --git a/Makefile b/Makefile index 747dd340..466f94ae 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ export CGO_ENABLED := 0 coverage \ licenses \ snapshot \ - test + test # The help target displays a help message that includes the avialable targets # in this `Makefile`. It is the default target if `make` is run without any @@ -33,9 +33,9 @@ help: @echo " test - Run test suite" @echo "" -# The config target shows the current configured values that are enforce when +# The config target shows the current configured values that are enforced when # any `make` target is run. -config: +config: @echo "GOOS=${GOOS}" @echo "GOARCH=${GOARCH}" @echo "CGO_ENABLED=${CGO_ENABLED}" @@ -54,7 +54,7 @@ coverage: @scripts/test.sh coverage # The licenses target is used to make sure that all source code files have the -# appropriate license header in them. It will also generate a license file +# appropriate license header in them. It will also generate a license file # that includes all of the applicable licenses for any 3rd party libraries that # have been included in this project. To use this target, you must have the # `go-licenses` tool installed and available in your path. See @@ -84,7 +84,7 @@ build: install -o bin/ipctl \ -ldflags="-X 'github.com/itential/ipctl/internal/metadata.Build=$$(git rev-parse --short HEAD)' -X 'github.com/itential/ipctl/internal/metadata.Version=$$(git tag | sort -V | tail -1)'" -# The test target runs the unit tests for this project. All unit tests are +# The test target runs the unit tests for this project. All unit tests are # based on mock data for the various services it connects to. The target # should run without error before making any pull requests to this project. test: diff --git a/cmd/commands.go b/cmd/commands.go index 7ba4e0db..6e3074d8 100644 --- a/cmd/commands.go +++ b/cmd/commands.go @@ -132,7 +132,7 @@ func platformCommands(r handlers.Runtime, id string) []*cobra.Command { }) } -// dataserCommands provide a set of commands for performing batch operations on +// datasetCommands provide a set of commands for performing batch operations on // specific asset types func datasetCommands(r handlers.Runtime, id string) []*cobra.Command { h := handlers.NewHandler(r) diff --git a/cmd/root.go b/cmd/root.go index 1e1be98e..f795f9e0 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -38,7 +38,7 @@ func loadCommands(cmd *cobra.Command, runtime handlers.Runtime) { addRootCommand(cmd, runtime, "Plugin Commands:", pluginCommands) } -// versionCommand is a top level command that display's the current application +// versionCommand is a top level command that displays the current application // version. func versionCommand() *cobra.Command { var cmd = &cobra.Command{ diff --git a/docs/commands-quick-reference.md b/docs/commands-quick-reference.md index d5df110b..93caca9d 100644 --- a/docs/commands-quick-reference.md +++ b/docs/commands-quick-reference.md @@ -1,7 +1,7 @@ # Command Table -The table below provides a quick reference for that shows which commands are -support for which assets. +The table below provides a quick reference that shows which commands are +supported for which assets. | Asset | get | describe | create | delete | copy | clear | import | export | |------------------------------------|-----|----------|--------|--------|------|-------|--------|--------| diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 78a02c05..b417b2d9 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -1,7 +1,7 @@ -# Configuration Reference. +# Configuration Reference This document provides details about the available configuration options -available to configure `ipctl`. All configuration options can be specified +available to configure `ipctl`. All configuration options can be specified either in a configuration file and/or as environment variables. Values configured using environment variables take precedence over the same @@ -21,10 +21,10 @@ one or more key=value settings that can be used to configure the application. ## Avoiding security risks The `ipctl` configuration file may contain senstive configuration values used -to authenticate to services. The configuration file should be secured such +to authenticate to services. The configuration file should be secured such that only the current user has access to the configuration directory and file. -The following example commands would security the directory and file when +The following example commands would secure the directory and file when running `ipctl` from a Linux host. ```bash @@ -36,20 +36,20 @@ Please consult your OS documentation for specific commands. ## Using profiles -The application configuration flie supports configuring multiple profiles A -profile defines the connection settings for a given server. When `iapctl` +The application configuration file supports configuring multiple profiles. A +profile defines the connection settings for a given server. When `ipctl` attempts to conect to a server, it will look up the profile settings in the conifguraiton file based on the profile name. The profile name can be passed to any command using the `--profile ` command line argument. A default profile can also be set in the configuration file. See `default_profile` in the [Applicaiton Settings}(#Application -Settings) section for a descrption. +Settings) section for a description. ## Configuration options The entries below provide the set of available configuration options that can -be used with`ipctl`. +be used with `ipctl`. ### Application Settings @@ -57,23 +57,23 @@ The `application` settings can be used to configure application level settings for `ipctl`. The following values are configurable within `[application]`. All values in this section can be overridden with environment variables. -For instance to override the `default_profile` value, the environment variable -would be `IPCTL_APPLICATION_DEFAULT_PROFILE` +For instance, to override the `default_profile` value, the environment variable +would be `IPCTL_APPLICATION_DEFAULT_PROFILE`. #### `default_profile` Configures the name of the profile to use if not explicitly set using the -command line option `--profile` +command line option `--profile`. -The default value for `default_profile` is `null` +The default value for `default_profile` is `null`. #### working_dir -Configures the working directory for the application. The working directory +Configures the working directory for the application. The working directory is the default directory where the application will look for the configuration file. -The default value for `working_dir` is `~/.platform.d` +The default value for `working_dir` is `~/.platform.d`. ### Log Settings @@ -85,11 +85,11 @@ where `` is the key name. #### level -Configures the level of detail sent to the logging facility. This -configuration value accepts one of the following values: `INFO`, `DEBUG`, -`TRACE`. +Configures the level of detail sent to the logging facility. This +configuration value accepts one of the following values: `info`, `debug`, +`trace`. -The default value for `level` is `info` +The default value for `level` is `info`. #### file_json @@ -102,9 +102,9 @@ The default value for `level` is `info` ### Terminal Settings The terminal settings section provides configuration values for managing the -terminal environment. All configuration settings are maintained under the +terminal environment. All configuration settings are maintained under the `[terminal]` section and can be overridded using environment variables -prefaced with `IPCTL_TERMINAL_` +prefaced with `IPCTL_TERMINAL_`. #### no_color @@ -114,7 +114,7 @@ is `false`, the output may use color in the output. This configuration value only applies to `human` output. -The default value for `no_color` is `false` +The default value for `no_color` is `false`. #### default_output @@ -122,9 +122,9 @@ Sets the default output format for commands. Currently, the application supports three output formats `human`,`json` and `yaml`. Use this configuration to define the default output format for all commands. -This setting can be override for any command using `--output ` +This setting can be override for any command using `--output `. -The default value for `default_output` is `human` +The default value for `default_output` is `human`. #### pager @@ -132,7 +132,7 @@ Enables or disables the pager feature in the application. The pager feature will pass the returned output through `less`, which must be available on your system, to paginate the output. -The default value for `pager` is `true` +The default value for `pager` is `true`. #### timestamp_timezone @@ -140,11 +140,11 @@ Configures the timezone to use when converting log timestamp messages from the application. This setting can be used to automatiocally translate the log messages to any desired timezone. -The default value for `timestamp_timezone` is `utc` +The default value for `timestamp_timezone` is `utc`. ### Git settings -Whenw working with git repositories, there are some global settings that should +When working with git repositories, there are some global settings that should be configured. This section provides a configuration settings for setting global git options. @@ -153,14 +153,14 @@ global git options. Configures the name to use when making commits using git. The name configured here will be displayed in the commit message. -The default value for `name` is `null` +The default value for `name` is `null`. #### `email` Configures the email address to use when making git commits. The email address will be used in commit messages. -The default value for `email` is `null` +The default value for `email` is `null`. #### `user` @@ -173,7 +173,7 @@ The default value for `user` is `git`. ### Profiles Profiles provide server specific configuration settings for working with -Itential Platform servers. The configuration file format suppors creating one +Itential Platform servers. The configuration file format supports creating one or more named profiles. To create a named profile, start the section with `[profile ]`. For @@ -192,13 +192,13 @@ accomplished by setting `IPCTL_PROFILE__PASSWORD` to the desired value. For instance, to set the password for a profile callend `prod`, the environment variable would be `IPCTL_PROFILE_PROD_PASSWORD`. The value would override any -value in the connfiguration file. +value in the configuration file. #### `host` Sets the hostname or IP address of the Itential Platform server to connect to. -The default value for `host` is `localhost` +The default value for `host` is `localhost`. #### `port` @@ -215,11 +215,10 @@ The default value for `port` is `0`. Enables or disables the use of TLS for the connecton. When this value is set to `true`, the application will attempt to establish a TLS connecton to the -server. When this value is set to `false` the application will not attempt to +server. When this value is set to `false` the application will not attempt to use TLS when connecting to the server. -The default value for `use_tls` is `true` - +The default value for `use_tls` is `true`. #### `verify` @@ -228,30 +227,30 @@ this value is set to `true`, certificates received from the server are validated. When this value is set to `false`, certifcates are assumed valid. This feature is useful when using self-signed certificates for TLS connections. -The default value for `verify` is `true` +The default value for `verify` is `true`. #### `username` -Cnfigures the name of the user to use when authenticating to the Itential +Configures the name of the user to use when authenticating to the Itential Platform server. This should be the username used to login to the server and determines the level of authorzation. -The default value for `username` is `admin@pronghorn` +The default value for `username` is `admin@pronghorn`. #### `password` Configures the password to use when authenticating the connection to Itential Platform server. -The default value for `password` is `admin` +The default value for `password` is `admin`. #### client_id Sets the client identifier for working with Itential Platform running in the -cloud at itential.io. The client id can be obtained when creating a service -acoount in Itential Cloud +cloud at itential.io. The client id can be obtained when creating a service +account in Itential Cloud. -The default vlaue for `client_id` is `null` +The default value for `client_id` is `null`. #### client_secret @@ -259,33 +258,32 @@ Configures the client secret for working with Iential Platform running in Itential Cloud. The client secret can be obtained when creating a service account in Itential Cloud. -The default value for `client_secret` is `null` +The default value for `client_secret` is `null`. #### timeout Configure the timeout value in seconds for request messages sent to the server. -The default value for `timeout` is `5` +The default value for `timeout` is `5`. #### mongo_url Configures the URL to use to make calls directly to the Mongo database. This is primarily used by plugins. -The default value for `mongo_url` is `null` - +The default value for `mongo_url` is `null`. ### Repository settings Repositories allow for the configuration of named repository configurations for -working with the `push` and `pull` commands. The configuration file supports +working with the `push` and `pull` commands. The configuration file supports creating one or more repository configuration entries in the configuration file. Repository configurations are sections prefixed with `repository`. For instance, to create a repository named `assets`, the section would be -`[repository assets]`. Once configured, the repository can be referenced by +`[repository assets]`. Once configured, the repository can be referenced by name in various commands. Any configuration value included in the `repository` section can be overridden @@ -294,55 +292,54 @@ instance, to override the `reference` configuration value for the repository named `assets`, the environment variable would be `IPCTL_REPOSITORY_ASSETS_REFERENCE`. - #### url Provides the full URL to the git repository to use for this named repository -object. This cofniguration setting accepts any valid git URL format including: +object. This configuration setting accepts any valid git URL format including: - SSH Transport URLs - Git Transport URLs - HTTP/S Transport URLs - Local Transport URLs -The default value for `url` is `null` +The default value for `url` is `null`. #### private_key Configures the private key to use when authenticating to the git repository -over SSH. This value contains the actual private key. +over SSH. This value contains the actual private key. -Note: This configuration setting is mutually exclusive with `private_key_file` +Note: This configuration setting is mutually exclusive with `private_key_file`. -The default value for `private_key` is `null` +The default value for `private_key` is `null`. #### private_key_file -Conifgures the path to the file containing the private key to use when +Configures the path to the file containing the private key to use when authenticating to the repository over SSH. Note: This configuration setting is mutually exclusive with `private_key`. -The default value for `private_key_file` is `null` +The default value for `private_key_file` is `null`. #### reference Configures the git reference to use with this named repository. The git -reference can be a git branch, tag or specific SHA. If this value is not +reference can be a git branch, tag or specific SHA. If this value is not configured, the default branch configured on the server will be used. -The default value for `reference` is `null` +The default value for `reference` is `null`. #### name Configures the name to be included in commit messages when using the `push` command. -The default value for `name` is `null` +The default value for `name` is `null`. #### email Configures the email address to include in commit messages created when using the `push` command. -The default value for `email` is `null` +The default value for `email` is `null`. diff --git a/docs/index.md b/docs/index.md index e197b014..9b9d0b81 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,4 +8,3 @@ The `ipctl` project provides a command line interface for working with Itential - [Running from source](running-from-source.md) - [Command Quick Reference](commands-quick-reference.md) - [Configuration Reference](configuration-reference.md) - diff --git a/docs/running-from-source.md b/docs/running-from-source.md index 82afae4c..75f6d423 100644 --- a/docs/running-from-source.md +++ b/docs/running-from-source.md @@ -1,8 +1,8 @@ -# Running from source +# Running ipctl -The `ipctl` application can be direclty run from a git checkout. In order to +The `ipctl` application can be directly run from a git checkout. In order to run the application directly from the source tree, you must have `golang` -installed and available on in your local environment. +installed and available on your local environment. To get started, first install `golang` 1.22 on your local system. Installation instruction can be found [here](https://go.dev/doc/install). @@ -13,24 +13,24 @@ The repository includes a `Makefile` with targets to allow installing and building the application. Be sure to install `make` into your local environment as well. -Once installed and from the root directory where you have cloned the -repository, and run `make install`. This will install of the `golang` +Once installed, go to the root directory where you have cloned the +repository, and run `make install`. This will install all of the `golang` dependencies and prepare your system to run the code from source. -Finally to execute the code from source run `go run main.go` which will run +Finally, to execute the code from source run `go run main.go` which will run the application directly from source code. ## Building the executable You can also build the application executable using the `build` make target. To build the application simply run `make build` from the root folder of the -repository. This will build the executable and place it into the `bin/` +repository. This will build the executable and place it into the `bin/` folder. ## Building snapshots Finally, the `Makefile` also supports building snapshots. Snapshots will build -the binary for all supported platforms. To create a snapshot build, you will +the binary for all supported platforms. To create a snapshot build, you will need to have `goreleaser` installed and available in your local environment. See [here](https://goreleaser.com/) for details on how to install `goreleaser`. diff --git a/docs/working-with-repositories.md b/docs/working-with-repositories.md index 64d8d598..95268ad7 100644 --- a/docs/working-with-repositories.md +++ b/docs/working-with-repositories.md @@ -1,7 +1,7 @@ # Working with repositories One of the key features of `ipctl` is the opportunity to work natively with -`git` repositories. This integration allows you to directly push and pull +`git` repositories. This integration allows you to directly push and pull Itential Platform assets to and from git repositories using the `import` and `export` commands with command line options. @@ -98,7 +98,7 @@ push it into a Git repository. The file will be stored in the root of the repository. In some cases, it may be desirable to store the file in a specific folder -within the repository. In order to do that, use the `--path` command line +within the repository. In order to do that, use the `--path` command line option. For example, assume the same project as before needs to be stored in folder @@ -117,8 +117,8 @@ path does not exist in the repository, it will be created. ## Pulling assets from repositories using `import` The `import` command can be used to pull an asset directly from a Git -repository and import it into an Itential Platform server. The `import` -command accepts the following command line options for performing this task. +repository and import it into an Itential Platform server. The `import` +command accepts the following command line options for performing this task: - `--repository` - `--reference` @@ -132,7 +132,7 @@ directly from a Git repository. ```bash ipctl import project "My Test Project.project.json" \ - --repository git@github.com:itential/assets.git \ + --repository git@github.com:itential/assets.git ``` When run, the command will connect to the Git repository defined by @@ -148,8 +148,3 @@ repository. ipctl import project "test/projects/My Test Project.project.json" \ --repository git@github.com:itential/assets.git ``` - - - - -