1
1
mirror of https://github.com/casey/just.git synced 2024-11-22 18:34:06 +03:00
just/man/chapter_22.html
2022-05-04 06:28:56 +00:00

288 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Settings - Just Programmer&#x27;s Manual</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="chapter_1.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_2.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_3.html"><strong aria-hidden="true">1.1.1.</strong> Prerequisites</a></li><li class="chapter-item expanded "><a href="chapter_4.html"><strong aria-hidden="true">1.1.2.</strong> Packages</a></li><li class="chapter-item expanded "><a href="chapter_5.html"><strong aria-hidden="true">1.1.3.</strong> Pre-Built Binaries</a></li><li class="chapter-item expanded "><a href="chapter_6.html"><strong aria-hidden="true">1.1.4.</strong> GitHub Actions</a></li><li class="chapter-item expanded "><a href="chapter_7.html"><strong aria-hidden="true">1.1.5.</strong> Release RSS Feed</a></li></ol></li><li class="chapter-item expanded "><a href="chapter_8.html"><strong aria-hidden="true">1.2.</strong> Backwards Compatibility</a></li><li class="chapter-item expanded "><a href="chapter_9.html"><strong aria-hidden="true">1.3.</strong> Editor Support</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_10.html"><strong aria-hidden="true">1.3.1.</strong> Vim and Neovim</a></li><li class="chapter-item expanded "><a href="chapter_11.html"><strong aria-hidden="true">1.3.2.</strong> Emacs</a></li><li class="chapter-item expanded "><a href="chapter_12.html"><strong aria-hidden="true">1.3.3.</strong> Visual Studio Code</a></li><li class="chapter-item expanded "><a href="chapter_13.html"><strong aria-hidden="true">1.3.4.</strong> Kakoune</a></li><li class="chapter-item expanded "><a href="chapter_14.html"><strong aria-hidden="true">1.3.5.</strong> Sublime Text</a></li><li class="chapter-item expanded "><a href="chapter_15.html"><strong aria-hidden="true">1.3.6.</strong> Other Editors</a></li></ol></li><li class="chapter-item expanded "><a href="chapter_16.html"><strong aria-hidden="true">1.4.</strong> Quick Start</a></li><li class="chapter-item expanded "><a href="chapter_17.html"><strong aria-hidden="true">1.5.</strong> Examples</a></li><li class="chapter-item expanded "><a href="chapter_18.html"><strong aria-hidden="true">1.6.</strong> Features</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_19.html"><strong aria-hidden="true">1.6.1.</strong> The Default Recipe</a></li><li class="chapter-item expanded "><a href="chapter_20.html"><strong aria-hidden="true">1.6.2.</strong> Listing Available Recipes</a></li><li class="chapter-item expanded "><a href="chapter_21.html"><strong aria-hidden="true">1.6.3.</strong> Aliases</a></li><li class="chapter-item expanded "><a href="chapter_22.html" class="active"><strong aria-hidden="true">1.6.4.</strong> Settings</a></li><li class="chapter-item expanded "><a href="chapter_23.html"><strong aria-hidden="true">1.6.5.</strong> Documentation Comments</a></li><li class="chapter-item expanded "><a href="chapter_24.html"><strong aria-hidden="true">1.6.6.</strong> Dotenv Integration</a></li><li class="chapter-item expanded "><a href="chapter_25.html"><strong aria-hidden="true">1.6.7.</strong> Variables and Substitution</a></li><li class="chapter-item expanded "><a href="chapter_26.html"><strong aria-hidden="true">1.6.8.</strong> Strings</a></li><li class="chapter-item expanded "><a href="chapter_27.html"><strong aria-hidden="true">1.6.9.</strong> Ignoring Errors</a></li><li class="chapter-item expanded "><a href="chapter_28.html"><strong aria-hidden="true">1.6.10.</strong> Functions</a></li><li class="chapter-item expanded "><a href="chapter_29.html"><strong aria-hidden="true">1.6.11.</strong> Command Evaluation Using Backticks</a></li><li class="chapter-item expanded "><a href="chapter_30.html"><strong aria-hidden="true">1.6.12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="chapter_31.html"><strong aria-hidden="true">1.6.13.</strong> Stopping execution with error</a></li><li class="chapter-item expanded "><a href="chapter_32.html"><strong aria-hidden="true">1.6.14.</strong> Setting Variables from the Command Line</a></li><li class="chapter-item expanded "><a href="chapter_33.html"><strong aria-hidden="true">1.6.15.</strong> Getting and Setting Environment Variables</a></li><li class="chapter-item expanded "><a href="chapter_34.html"><strong aria-hidden="true">1.6.16.</strong> Recipe Parameters</a></li><li class="chapter-item expanded "><a href="chapter_35.html"><strong aria-hidden="true">1.6.17.</strong> Running Recipes at the End of a Recipe</a></li><li class="chapter-item expanded "><a href="chapter_36.html"><strong aria-hidden="true">1.6.18.</strong> Running Recipes in the Middle of a Recipe</a></li><li class="chapter-item expanded "><a href="chapter_37.html"><strong aria-hidden="true">1.6.19.</strong> Writing Recipes in Other Languages</a></li><li class="chapter-item expanded "><a href="chapter_38.html"><strong aria-hidden="true">1.6.20.</strong> Safer Bash Shebang Recipes</a></li><li class="chapter-item expanded "><a href="chapter_39.html"><strong aria-hidden="true">1.6.21.</strong> Setting Variables in a Recipe</a></li><li class="chapter-item expanded "><a href="chapter_40.html"><strong aria-hidden="true">1.6.22.</strong> Changing the Working Directory in a Recipe</a></li><li class="chapter-item expanded "><a href="chapter_41.html"><strong aria-hidden="true">1.6.23.</strong> Indentation</a></li><li class="chapter-item expanded "><a href="chapter_42.html"><strong aria-hidden="true">1.6.24.</strong> Multi-Line Constructs</a></li><li class="chapter-item expanded "><a href="chapter_43.html"><strong aria-hidden="true">1.6.25.</strong> Command Line Options</a></li><li class="chapter-item expanded "><a href="chapter_44.html"><strong aria-hidden="true">1.6.26.</strong> Private Recipes</a></li><li class="chapter-item expanded "><a href="chapter_45.html"><strong aria-hidden="true">1.6.27.</strong> Quiet Recipes</a></li><li class="chapter-item expanded "><a href="chapter_46.html"><strong aria-hidden="true">1.6.28.</strong> Selecting Recipes to Run With an Interactive Chooser</a></li><li class="chapter-item expanded "><a href="chapter_47.html"><strong aria-hidden="true">1.6.29.</strong> Invoking justfiles in Other Directories</a></li><li class="chapter-item expanded "><a href="chapter_48.html"><strong aria-hidden="true">1.6.30.</strong> Hiding justfiles</a></li><li class="chapter-item expanded "><a href="chapter_49.html"><strong aria-hidden="true">1.6.31.</strong> Just Scripts</a></li><li class="chapter-item expanded "><a href="chapter_50.html"><strong aria-hidden="true">1.6.32.</strong> Dumping justfiles as JSON</a></li><li class="chapter-item expanded "><a href="chapter_51.html"><strong aria-hidden="true">1.6.33.</strong> Falling back to parent justfiles</a></li></ol></li><li class="chapter-item expanded "><a href="chapter_52.html"><strong aria-hidden="true">1.7.</strong> Changelog</a></li><li class="chapter-item expanded "><a href="chapter_53.html"><strong aria-hidden="true">1.8.</strong> Miscellanea</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_54.html"><strong aria-hidden="true">1.8.1.</strong> Companion Tools</a></li><li class="chapter-item expanded "><a href="chapter_55.html"><strong aria-hidden="true">1.8.2.</strong> Shell Alias</a></li><li class="chapter-item expanded "><a href="chapter_56.html"><strong aria-hidden="true">1.8.3.</strong> Shell Completion Scripts</a></li><li class="chapter-item expanded "><a href="chapter_57.html"><strong aria-hidden="true">1.8.4.</strong> Grammar</a></li><li class="chapter-item expanded "><a href="chapter_58.html"><strong aria-hidden="true">1.8.5.</strong> just.sh</a></li><li class="chapter-item expanded "><a href="chapter_59.html"><strong aria-hidden="true">1.8.6.</strong> User justfiles</a></li><li class="chapter-item expanded "><a href="chapter_60.html"><strong aria-hidden="true">1.8.7.</strong> Node.js package.json Script Compatibility</a></li><li class="chapter-item expanded "><a href="chapter_61.html"><strong aria-hidden="true">1.8.8.</strong> Alternatives and Prior Art</a></li></ol></li><li class="chapter-item expanded "><a href="chapter_62.html"><strong aria-hidden="true">1.9.</strong> Contributing</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_63.html"><strong aria-hidden="true">1.9.1.</strong> Janus</a></li><li class="chapter-item expanded "><a href="chapter_64.html"><strong aria-hidden="true">1.9.2.</strong> Minimum Supported Rust Version</a></li></ol></li><li class="chapter-item expanded "><a href="chapter_65.html"><strong aria-hidden="true">1.10.</strong> Frequently Asked Questions</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="chapter_66.html"><strong aria-hidden="true">1.10.1.</strong> What are the idiosyncrasies of Make that Just avoids?</a></li><li class="chapter-item expanded "><a href="chapter_67.html"><strong aria-hidden="true">1.10.2.</strong> Whats the relationship between Just and Cargo build scripts?</a></li></ol></li><li class="chapter-item expanded "><a href="chapter_68.html"><strong aria-hidden="true">1.11.</strong> Further Ramblings</a></li></ol></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Just Programmer&#x27;s Manual</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h3 id="settings"><a class="header" href="#settings">Settings</a></h3>
<p>Settings control interpretation and execution. Each setting may be specified at most once, anywhere in the <code>justfile</code>.</p>
<p>For example:</p>
<pre><code class="language-make">set shell := [&quot;zsh&quot;, &quot;-cu&quot;]
foo:
# this line will be run as `zsh -cu 'ls **/*.txt'`
ls **/*.txt
</code></pre>
<h4 id="table-of-settings"><a class="header" href="#table-of-settings">Table of Settings</a></h4>
<table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody>
<tr><td><code>allow-duplicate-recipes</code></td><td>boolean</td><td>Allow recipes appearing later in a <code>justfile</code> to override earlier recipes with the same name.</td></tr>
<tr><td><code>dotenv-load</code></td><td>boolean</td><td>Load a <code>.env</code> file, if present.</td></tr>
<tr><td><code>export</code></td><td>boolean</td><td>Export all variables as environment variables.</td></tr>
<tr><td><code>positional-arguments</code></td><td>boolean</td><td>Pass positional arguments.</td></tr>
<tr><td><code>shell</code></td><td><code>[COMMAND, ARGS…]</code></td><td>Set the command used to invoke recipes and evaluate backticks.</td></tr>
<tr><td><code>windows-powershell</code></td><td>boolean</td><td>Use PowerShell on Windows as default shell.</td></tr>
</tbody></table>
<p>Boolean settings can be written as:</p>
<pre><code class="language-mf">set NAME
</code></pre>
<p>Which is equivalent to:</p>
<pre><code class="language-mf">set NAME := true
</code></pre>
<h4 id="allow-duplicate-recipes"><a class="header" href="#allow-duplicate-recipes">Allow Duplicate Recipes</a></h4>
<p>If <code>allow-duplicate-recipes</code> is set to <code>true</code>, defining multiple recipes with the same name is not an error and the last definition is used. Defaults to <code>false</code>.</p>
<pre><code class="language-make">set allow-duplicate-recipes
@foo:
echo foo
@foo:
echo bar
</code></pre>
<pre><code class="language-sh">$ just foo
bar
</code></pre>
<h4 id="dotenv-load"><a class="header" href="#dotenv-load">Dotenv Load</a></h4>
<p>If <code>dotenv-load</code> is <code>true</code>, a <code>.env</code> file will be loaded if present. Defaults to <code>false</code>.</p>
<h4 id="export"><a class="header" href="#export">Export</a></h4>
<p>The <code>export</code> setting causes all <code>just</code> variables to be exported as environment variables. Defaults to <code>false</code>.</p>
<pre><code class="language-make">set export
a := &quot;hello&quot;
@foo b:
echo $a
echo $b
</code></pre>
<pre><code class="language-sh">$ just foo goodbye
hello
goodbye
</code></pre>
<h4 id="positional-arguments"><a class="header" href="#positional-arguments">Positional Arguments</a></h4>
<p>If <code>positional-arguments</code> is <code>true</code>, recipe arguments will be passed as positional arguments to commands. For linewise recipes, argument <code>$0</code> will be the name of the recipe.</p>
<p>For example, running this recipe:</p>
<pre><code class="language-make">set positional-arguments
@foo bar:
echo $0
echo $1
</code></pre>
<p>Will produce the following output:</p>
<pre><code class="language-sh">$ just foo hello
foo
hello
</code></pre>
<p>When using an <code>sh</code>-compatible shell, such as <code>bash</code> or <code>zsh</code>, <code>$@</code> expands to the positional arguments given to the recipe, starting from one. When used within double quotes as <code>&quot;$@&quot;</code>, arguments including whitespace will be passed on as if they were double-quoted. That is, <code>&quot;$@&quot;</code> is equivalent to <code>&quot;$1&quot; &quot;$2&quot;</code>… When there are no positional parameters, <code>&quot;$@&quot;</code> and <code>$@</code> expand to nothing (i.e., they are removed).</p>
<p>This example recipe will print arguments one by one on separate lines:</p>
<pre><code class="language-make">set positional-arguments
@test *args='':
bash -c 'while (( &quot;$#&quot; )); do echo - $1; shift; done' -- &quot;$@&quot;
</code></pre>
<p>Running it with <em>two</em> arguments:</p>
<pre><code class="language-sh">$ just test foo &quot;bar baz&quot;
- foo
- bar baz
</code></pre>
<h4 id="shell"><a class="header" href="#shell">Shell</a></h4>
<p>The <code>shell</code> setting controls the command used to invoke recipe lines and backticks. Shebang recipes are unaffected.</p>
<pre><code class="language-make"># use python3 to execute recipe lines and backticks
set shell := [&quot;python3&quot;, &quot;-c&quot;]
# use print to capture result of evaluation
foos := `print(&quot;foo&quot; * 4)`
foo:
print(&quot;Snake snake snake snake.&quot;)
print(&quot;{{foos}}&quot;)
</code></pre>
<p><code>just</code> passes the command to be executed as an argument. Many shells will need an additional flag, often <code>-c</code>, to make them evaluate the first argument.</p>
<h5 id="windows-powershell"><a class="header" href="#windows-powershell">Windows PowerShell</a></h5>
<p><code>just</code> uses <code>sh</code> on Windows by default. To use PowerShell instead, set <code>windows-powershell</code> to true.</p>
<pre><code class="language-make">set windows-powershell := true
hello:
Write-Host &quot;Hello, world!&quot;
</code></pre>
<h5 id="python-3"><a class="header" href="#python-3">Python 3</a></h5>
<pre><code class="language-make">set shell := [&quot;python3&quot;, &quot;-c&quot;]
</code></pre>
<h5 id="bash"><a class="header" href="#bash">Bash</a></h5>
<pre><code class="language-make">set shell := [&quot;bash&quot;, &quot;-uc&quot;]
</code></pre>
<h5 id="z-shell"><a class="header" href="#z-shell">Z Shell</a></h5>
<pre><code class="language-make">set shell := [&quot;zsh&quot;, &quot;-uc&quot;]
</code></pre>
<h5 id="fish"><a class="header" href="#fish">Fish</a></h5>
<pre><code class="language-make">set shell := [&quot;fish&quot;, &quot;-c&quot;]
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="chapter_21.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="chapter_23.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="chapter_21.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="chapter_23.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>