PD-3637: set-contexts/set-labels: more examples, fixes

liquibase · Aug 10, 2023 · 83b9f86 · 83b9f86
1 parent e024d46
commit 83b9f86
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 7 deletions.
diff --git a/Content/Z_Resources/Snippets/text/command-set-contexts-set-labels.flsnp b/Content/Z_Resources/Snippets/text/command-set-contexts-set-labels.flsnp
@@ -4,16 +4,30 @@
     </head>
     <body>
         <MadCap:snippetBlock src="../note/command-pro.flsnp" />
-        <p>The <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> command set or replace <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts"><a href="../../../concepts/changelogs/attributes/contexts.html">contexts</a></MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels"><a href="../../../concepts/changelogs/attributes/labels.html">labels</a></MadCap:conditionalText> on your <MadCap:variable name="General.changeset" />s <b>using your command line</b>. This is an alternative to setting <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText>&#160;<b>directly in your <MadCap:variable name="General.changelog" /></b>. You can use these <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> to specify which <MadCap:variable name="General.changeset" />s to deploy in a later update.</p>
-        <p>The command works with any SQL, XML, YAML, or JSON&#160;<MadCap:variable name="General.changelog" />. It also works with <MadCap:variable name="General.changelog" />s specified with the <code><MadCap:xref href="../../../change-types/include.html">include</MadCap:xref></code> or <code><MadCap:xref href="../../../change-types/includeall.html">includeAll</MadCap:xref></code> tags. You can choose which <MadCap:variable name="General.changeset" />s to target by specifying a <MadCap:variable name="General.changeset" /> author, ID, path, or an existing context or label filter. <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> is available in <MadCap:variable name="General.Liquibase" /> 4.23.1+.</p>
+        <p>The <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> command sets or replaces <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts"><a href="../../../concepts/changelogs/attributes/contexts.html">contexts</a></MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels"><a href="../../../concepts/changelogs/attributes/labels.html">labels</a></MadCap:conditionalText> on your <MadCap:variable name="General.changeset" />s <b>using your command line</b>. This is an alternative to setting <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText>&#160;<b>directly in your <MadCap:variable name="General.changelog" /></b>.</p>
+        <p>You can choose which <MadCap:variable name="General.changeset" />s to target by specifying a <MadCap:variable name="General.changeset" /> author, ID, path, or an existing context or label filter.</p>
+        <p>The command works with any SQL, XML, YAML, or JSON&#160;<MadCap:variable name="General.changelog" />. It also works with multiple <MadCap:variable name="General.changelog" />s specified with the <code><MadCap:xref href="../../../change-types/include.html">include</MadCap:xref></code> or <code><MadCap:xref href="../../../change-types/includeall.html">includeAll</MadCap:xref></code> tags.  <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> is available in <MadCap:variable name="General.Liquibase" /> 4.23.1+.</p>
         <h2>Uses</h2>
         <p>If you need to apply <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> to many <MadCap:variable name="General.changeset" />s, manually inserting them into your <MadCap:variable name="General.changelog" /> is slow and can lead to errors. Instead, <b>use <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> to quickly add or replace <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> in bulk</b>.</p>
         <p>By default, <MadCap:variable name="General.Liquibase" /> appends any <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> you specify with <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> to the list of <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> already on your <MadCap:variable name="General.changeset" />s. However, if you set <code>--force-replace</code> to <code>true</code>, <MadCap:variable name="General.Liquibase" /> drops existing <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> before adding the new ones.</p>
         <p>The command is also useful if you want to standardize multiple similar <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> or replace deprecated ones. You can specify command arguments to control the formatting <MadCap:variable name="General.Liquibase" /> uses when it inserts the <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> into your <MadCap:variable name="General.changelog" />.</p>
         <p>After setting your <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> with <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code>, you can deploy your changes with the <code><MadCap:xref href="../../../commands/update/update.html">update</MadCap:xref></code> command. While deploying, specify the <code MadCap:conditions="command-set-contexts-set-labels.contexts">--<a href="../../../concepts/changelogs/attributes/contexts.html">context-filter</a></code><code MadCap:conditions="command-set-contexts-set-labels.labels">--<a href="../../../concepts/changelogs/attributes/labels.html">labels</a></code> command argument to control which <MadCap:variable name="General.changeset" />s are run.</p>
         <h2>Syntax</h2>
         <p>To run the <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> command, specify the driver, classpath, and URL in <MadCap:variable name="General.Liquibase" /> properties file. For more information, see <MadCap:xref href="../../../concepts/connections/creating-config-properties.html">Create and Configure a [%=General.liquiPropFile%] File</MadCap:xref>. You can also specify these properties in your command line.</p>
-        <p>Then run the <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> command:</p><pre MadCap:conditions="command-set-contexts-set-labels.contexts"><code class="language-text">liquibase set-contexts --changelog-file=example-changelog.xml --set-as=dev,test</code></pre><pre MadCap:conditions="command-set-contexts-set-labels.labels"><code class="language-text">liquibase set-labels --changelog-file=example-changelog.xml --set-as=dev,test</code></pre>
+        <p>Then run the <code MadCap:conditions="command-set-contexts-set-labels.contexts">set-contexts</code><code MadCap:conditions="command-set-contexts-set-labels.labels">set-labels</code> command:</p><pre><code class="language-text">liquibase set-<MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> --changelog-file=example-changelog.xml --set-as=dev,test</code></pre>
+        <p>For example, targeting <MadCap:variable name="General.changeset" />s by author and existing label filter:</p><pre xml:space="preserve"><code class="language-text">liquibase set-<MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText>
+    --set-as="<MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">"dev, stage"</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">rel-02-final</MadCap:conditionalText>"
+    --changelog-file=release-02.sql
+    --changeset-author="bob"
+    --label-filter="rel-02"</code></pre>
+        <p>Replacing existing <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> with <code>--force-replace</code> instead of appending them:</p><pre xml:space="preserve"><code class="language-text">liquibase set-<MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText>
+    --set-as=<MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">dev, stage</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">rel-02-final</MadCap:conditionalText>
+    --changelog-file=release-02.sql
+    --changeset-author="bob"
+    --context-filter="dev,uat,stage"
+    --label-filter="rel-02"
+    --force-replace=true</code></pre>
+        <p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">Even though you're setting <MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.contexts">contexts</MadCap:conditionalText><MadCap:conditionalText MadCap:conditions="command-set-contexts-set-labels.labels">labels</MadCap:conditionalText> with this command, you can still target <MadCap:variable name="General.changeset" />s using both <code>context-filter</code> and <code>label-filter</code>.</p>
         <h2>Global arguments</h2>
         <MadCap:snippetBlock src="../note/command-parameter-kebab.flsnp" />
         <table>

diff --git a/Content/commands/change-tracking/set-contexts.htm b/Content/commands/change-tracking/set-contexts.htm
@@ -2,7 +2,7 @@
 <html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
     <head><title><MadCap:variable name="Heading.Level1" /></title>
         <link rel="canonical" href="https://docs.liquibase.com/commands/change-tracking/set-contexts.html" />
-        <meta name="description" content="Reference information and use cases for the set-contexts command. The set-contexts command lets you set or replace contexts on your changesets at runtime using your command line." />
+        <meta name="description" content="Reference information and use cases for the set-contexts command. The set-contexts command sets or replaces contexts on your changesets at runtime using your command line." />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
     </head>
     <body>

diff --git a/Content/commands/change-tracking/set-labels.htm b/Content/commands/change-tracking/set-labels.htm
@@ -2,7 +2,7 @@
 <html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
     <head><title><MadCap:variable name="Heading.Level1" /></title>
         <link rel="canonical" href="https://docs.liquibase.com/commands/change-tracking/set-labels.html" />
-        <meta name="description" content="Reference information and use cases for the set-labels command. The set-labels command lets you set or replace labels on your changesets at runtime using your command line." />
+        <meta name="description" content="Reference information and use cases for the set-labels command. The set-labels command sets or replaces labels on your changesets at runtime using your command line." />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
     </head>
     <body>

diff --git a/Content/commands/home.htm b/Content/commands/home.htm
@@ -282,13 +282,13 @@ <h2 id="change-tracking-commands"><a name="change-tracking-commands"></a>Change
                     <td>
                         <MadCap:xref href="change-tracking/set-contexts.htm">set-contexts<MadCap:snippetText src="../Z_Resources/Snippets/images/icon-pro-inline.flsnp" /></MadCap:xref>
                     </td>
-                    <td>Lets you set or replace <a href="../concepts/changelogs/attributes/contexts.html">contexts</a> on your <MadCap:variable name="General.changeset" />s using your command line. This is an alternative to setting contexts directly in your <MadCap:variable name="General.changelog" />. <MadCap:variable name="General.Liquibase" /> 4.23.1+.</td>
+                    <td>Sets or replaces <a href="../concepts/changelogs/attributes/contexts.html">contexts</a> on your <MadCap:variable name="General.changeset" />s using your command line. This is an alternative to setting contexts directly in your <MadCap:variable name="General.changelog" />. <MadCap:variable name="General.Liquibase" /> 4.23.1+.</td>
                 </tr>
                 <tr>
                     <td>
                         <MadCap:xref href="change-tracking/set-labels.htm">set-labels<MadCap:snippetText src="../Z_Resources/Snippets/images/icon-pro-inline.flsnp" /></MadCap:xref>
                     </td>
-                    <td>Lets you set or replace <a href="../concepts/changelogs/attributes/labels.html">labels</a> on your <MadCap:variable name="General.changeset" />s using your command line. This is an alternative to setting labels directly in your <MadCap:variable name="General.changelog" />. <MadCap:variable name="General.Liquibase" /> 4.23.1+.</td>
+                    <td>Sets or replaces <a href="../concepts/changelogs/attributes/labels.html">labels</a> on your <MadCap:variable name="General.changeset" />s using your command line. This is an alternative to setting labels directly in your <MadCap:variable name="General.changelog" />. <MadCap:variable name="General.Liquibase" /> 4.23.1+.</td>
                 </tr>
                 <tr>
                     <td>