Skip to content

Latest commit

 

History

History
142 lines (91 loc) · 5.81 KB

cmd_promote.rst

File metadata and controls

142 lines (91 loc) · 5.81 KB
Raw

ksconf promote

Warning

The promote command moves configuration settings between SOURCE and TARGET and therefore both files are updated. This is unlike most other commands where only TARGET is modified. Using the --keep argument will prevent SOURCE from being updated.

Modes

Promote has two different modes: batch and interactive.

Batch mode

Changes are applied automatically and the (now empty) source file is removed by default. The source file can be retained by using either the --keep or --keep-empty arguments, see descriptions above.

Interactive mode

Prompt the user to pick which stanzas and attributes to integrate. In practice, it's common that not all local changes will be ready to be promoted and committed at the same time.

Hint

This mode was inspired by git add --patch command.

Default

If you haven’t specified either batch or interactive mode, you’ll be asked to pick one at startup. You'll be given the option to show a diff, apply all changes, or be prompted to keep or reject changes interactively.

Safety checks

Moving content between files is a potentially risky operation. Here are some of the safety mechanisms that exist, because ksconf tries hard not to lose your stuff.

Tip

Pairing ksconf with a version control tool like git, while not required, does provide another layer of protection against loss or corruption. If you promote and commit changes frequently then the surface area of potential loss is reduced.

Note

Unfortunately the unit testing coverage for the promote command is quite low. This is primarily because I haven't yet figured out how to handle unit testing for interactive CLI tools (as this is the only interactive command to date.) I'm also not sure how much the UI may change; Any assistance in this area would be greatly appreciated.

Examples

A simple promotion looks like this.

ksconf promote local/props.conf default/props.conf

This is equivalent to this minor shortcut.

ksconf promote local/props.conf default

In this case, ksconf determines that default is a directory and therefore assumes that you want the same filename, props.conf in this case.

Tip

Using a directory as TARGET may seem like a trivial improvement, but in practice it greatly reduces accidental cross-promotion of content. Therefore we suggest its use.

Similarly, a shortcut for pushing between metadata files exists:

ksconf promote metadata/local.meta metadata

Interactive mode

Keyboard shortcuts

Key Meaning Description
y Yes Apply changes
n No Don't apply
d Diff Show the difference between the file or stanza.
q Quit Exit program. Don't save changes.

Limitations

  • Currently attribute-level section has not be implemented. Entire stanzas are either kept local or promoted fully.
  • Interactive mode currently lacks "help". In the meantime, see the keyboard shortcuts listed above.
  • Currently comments in the SOURCE file will not be preserved.
  • If SOURCE or TARGET is modified externally while promote is running, the entire operation will be aborted, thus loosing any custom selections you made in interactive mode. This needs improvement.
  • There's currently no way to preserve certain local settings with some kind of "never-promote" flag. It's not uncommon to have some settings in inputs.conf, for example, that you never want to promote.
  • There is no dry-run mode supported. Primarily, this is because it would only work for batch mode, and in interactive mode you explicitly see exactly what will be changed before anything is applied. (If you really need a dry-run for batch mode, use ksconf_cmd_merge to show the result of TARGET SOURCE combined.)