Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvement: Add Examples To sh Step [JENKINS-65396] #154

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Improvement: Add Examples To sh Step [JENKINS-65396] #154

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
021ec66
add examples to sh step
Queen-esther01 Apr 19, 2021
1e9657f
Update src/main/resources/org/jenkinsci/plugins/workflow/steps/durabl…
Queen-esther01 Apr 26, 2021
6cf1fce
Update src/main/resources/org/jenkinsci/plugins/workflow/steps/durabl…
Queen-esther01 May 3, 2021
1cf016f
Update src/main/resources/org/jenkinsci/plugins/workflow/steps/durabl…
Queen-esther01 May 3, 2021
0f1f9a2
Applying Mark's suggestions from code review
Queen-esther01 May 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 39 additions & 1 deletion ...in/resources/org/jenkinsci/plugins/workflow/steps/durable_task/ShellStep/help-script.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,42 @@
Otherwise the system default shell will be run, using the <code>-xe</code> flags
(you can specify <code>set +e</code> and/or <code>set +x</code> to disable those).
</p>
</div>
<p>A few examples of usage include:</p>

<b>Creating an output folder</b>
<p><code>sh 'mkdir -p output'</code></p>

<b>Reporting the current directory of the Pipeline step.</b>
<p><code>sh 'pwd'</code></p>

<b>Making HTTP requests </b>
<p><code>sh "curl -X POST --data-urlencode \'payload=${payload}\' ${slackURL}"</code></p>
Queen-esther01 marked this conversation as resolved.
Show resolved Hide resolved

<b>Running tests in the same workspace that the project was built </b>
<p><code>sh 'mvn test'</code></p>
<b>Using multi-line syntax to run several lines of script:</b>
<p>
<pre>
sh '''
echo "This is a first line of script"
# This is a script comment
echo "This is a second line"
'''
</pre>
</p>
<b>Escaping script content from groovy interpretation </b>>
Queen-esther01 marked this conversation as resolved.
Show resolved Hide resolved
<p>The triple-double-quote (""") string literal syntax allows for variable/expression substitution (interpolation), so the backslash (\) is interpreted as a special character "escape".</p>
<p>Since the first open parentheses is not such a special character, Groovy compilation fails. If your intent is to have literal backslashes in the resulting string, you need to escape the backslashes. That is, use a double-backslash (\\) to substitute for one literal backslash</p>
Comment on lines +40 to +41
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May want to use a simpler example.

Alternate example attached for you to consider.

<p><code>sh ("""
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure that we want to document scripted pipeline, any other opinions for other reviewers ? I would prefer to only have declarative pipeline in help.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this might be helpful to a few people, i specifically added it because of feedback from a user.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a mix of scripted and declarative is most helpful to readers, with preference to use declarative when we can

sed "s/(AssemblyInformationalVersion\\(\\")(.*)(\\")/\\1${productVersion}\\3/g"
AssemblyInfoGlobal/AssemblyInfoGlobal.cs -r
""")</code>
Comment on lines +43 to +45
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternate example that shows a multi-line shell script using triple double quotes.

Suggested change
sed "s/(AssemblyInformationalVersion\\(\\")(.*)(\\")/\\1${productVersion}\\3/g"
AssemblyInfoGlobal/AssemblyInfoGlobal.cs -r
""")</code>
sh """
echo 'This text is single quoted'
echo "This text is double quoted"
echo "This text doesn't contain a double quote"
echo This text doesn\\'t include an embedded double quote, it has an embedded single quote
"""
</code>

</p>

<b>Adding shell script as part of Groovy interpolation </b>>
<p>For double quoted string, Groovy will do interpolation on the string firstly.</p>
<p>Because the variables are runtime variables of the shell, rather than the variables of Groovy runtime. Groovy can't find the responding value from Groovy variable stack to replace the variables during interpolation.</p>
<p>So you need to escape all $ if you use double quotes or simply use single quotes which does not support interpolation</p>
<p><code>sh(returnStdout: true, script: "cd \$it; PLAN=\$(terragrunt plan --terragrunt-source-update | landscape);
echo \$PLAN; CHANGES=\$(echo \$PLAN | tail -2); echo \$CHANGES"</code></p>
</div>