"use strict";(self.webpackChunktaskfile_dev=self.webpackChunktaskfile_dev||[]).push([[552],{3905:function(e,n,t){t.d(n,{Zo:function(){return u},kt:function(){return k}});var a=t(7294);function r(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function i(e,n){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);n&&(a=a.filter((function(n){return Object.getOwnPropertyDescriptor(e,n).enumerable}))),t.push.apply(t,a)}return t}function o(e){for(var n=1;n<arguments.length;n++){var t=null!=arguments[n]?arguments[n]:{};n%2?i(Object(t),!0).forEach((function(n){r(e,n,t[n])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(t)):i(Object(t)).forEach((function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(t,n))}))}return e}function l(e,n){if(null==e)return{};var t,a,r=function(e,n){if(null==e)return{};var t,a,r={},i=Object.keys(e);for(a=0;a<i.length;a++)t=i[a],n.indexOf(t)>=0||(r[t]=e[t]);return r}(e,n);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)t=i[a],n.indexOf(t)>=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var s=a.createContext({}),p=function(e){var n=a.useContext(s),t=n;return e&&(t="function"==typeof e?e(n):o(o({},n),e)),t},u=function(e){var n=p(e.components);return a.createElement(s.Provider,{value:n},e.children)},m="mdxType",d={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},c=a.forwardRef((function(e,n){var t=e.components,r=e.mdxType,i=e.originalType,s=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),m=p(t),c=r,k=m["".concat(s,".").concat(c)]||m[c]||d[c]||i;return t?a.createElement(k,o(o({ref:n},u),{},{components:t})):a.createElement(k,o({ref:n},u))}));function k(e,n){var t=arguments,r=n&&n.mdxType;if("string"==typeof e||r){var i=t.length,o=new Array(i);o[0]=c;var l={};for(var s in n)hasOwnProperty.call(n,s)&&(l[s]=n[s]);l.originalType=e,l[m]="string"==typeof e?e:r,o[1]=l;for(var p=2;p<i;p++)o[p]=t[p];return a.createElement.apply(null,o)}return a.createElement.apply(null,t)}c.displayName="MDXCreateElement"},2926:function(e,n,t){t.r(n),t.d(n,{assets:function(){return s},contentTitle:function(){return o},default:function(){return m},frontMatter:function(){return i},metadata:function(){return l},toc:function(){return p}});var a=t(3117),r=(t(7294),t(3905));const i={slug:"/taskfile-versions/",sidebar_position:14},o="Taskfile Versions",l={unversionedId:"taskfile_versions",id:"taskfile_versions",title:"Taskfile Versions",description:"The Taskfile syntax and features changed with time. This document explains what",source:"@site/docs/taskfile_versions.md",sourceDirName:".",slug:"/taskfile-versions/",permalink:"/taskfile-versions/",draft:!1,tags:[],version:"current",sidebarPosition:14,frontMatter:{slug:"/taskfile-versions/",sidebar_position:14},sidebar:"tutorialSidebar",previous:{title:"Releasing",permalink:"/releasing/"},next:{title:"Donate",permalink:"/donate/"}},s={},p=[{value:"What the Taskfile version mean",id:"what-the-taskfile-version-mean",level:2},{value:"Version 3 latest",id:"version-3-latest",level:2},{value:"Version 2.6",id:"version-26",level:2},{value:"Version 2.2",id:"version-22",level:2},{value:"Version 2.1",id:"version-21",level:2},{value:"Version 2.0",id:"version-20",level:2},{value:"Version 1",id:"version-1",level:2}],u={toc:p};function m(e){let{components:n,...t}=e;return(0,r.kt)("wrapper",(0,a.Z)({},u,t,{components:n,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"taskfile-versions"},"Taskfile Versions"),(0,r.kt)("p",null,"The Taskfile syntax and features changed with time. This document explains what\nchanged on each version and how to upgrade your Taskfile."),(0,r.kt)("h2",{id:"what-the-taskfile-version-mean"},"What the Taskfile version mean"),(0,r.kt)("p",null,"The Taskfile version follows the Task version. E.g. the change to Taskfile\nversion ",(0,r.kt)("inlineCode",{parentName:"p"},"2")," means that Task ",(0,r.kt)("inlineCode",{parentName:"p"},"v2.0.0")," should be release to support it."),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"version:")," key on Taskfile accepts a semver string, so either ",(0,r.kt)("inlineCode",{parentName:"p"},"2"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"2.0")," or\n",(0,r.kt)("inlineCode",{parentName:"p"},"2.0.0")," is accepted. If you choose to use ",(0,r.kt)("inlineCode",{parentName:"p"},"2.0")," Task will not enable future\n",(0,r.kt)("inlineCode",{parentName:"p"},"2.1")," features, but if you choose to use ",(0,r.kt)("inlineCode",{parentName:"p"},"2"),", then any ",(0,r.kt)("inlineCode",{parentName:"p"},"2.x.x")," features will be\navailable, but not ",(0,r.kt)("inlineCode",{parentName:"p"},"3.0.0+"),"."),(0,r.kt)("h2",{id:"version-3-latest"},"Version 3 ",(0,r.kt)("img",{parentName:"h2",src:"https://img.shields.io/badge/latest-brightgreen",alt:"latest"})),(0,r.kt)("p",null,"These are some major changes done on ",(0,r.kt)("inlineCode",{parentName:"p"},"v3"),":"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Task's output will now be colored"),(0,r.kt)("li",{parentName:"ul"},"Added support for ",(0,r.kt)("inlineCode",{parentName:"li"},".env")," like files"),(0,r.kt)("li",{parentName:"ul"},"Added ",(0,r.kt)("inlineCode",{parentName:"li"},"label:")," setting to task so one can override how the task name appear in\nthe logs"),(0,r.kt)("li",{parentName:"ul"},"A global ",(0,r.kt)("inlineCode",{parentName:"li"},"method:")," was added to allow setting the default method, and Task's\ndefault changed to ",(0,r.kt)("inlineCode",{parentName:"li"},"checksum")),(0,r.kt)("li",{parentName:"ul"},"Two magic variables were added when using ",(0,r.kt)("inlineCode",{parentName:"li"},"status:"),": ",(0,r.kt)("inlineCode",{parentName:"li"},"CHECKSUM")," and\n",(0,r.kt)("inlineCode",{parentName:"li"},"TIMESTAMP")," which contains, respectively, the md5 checksum and greatest\nmodification timestamp of the files listed on ",(0,r.kt)("inlineCode",{parentName:"li"},"sources:")),(0,r.kt)("li",{parentName:"ul"},"Also, the ",(0,r.kt)("inlineCode",{parentName:"li"},"TASK")," variable is always available with the current task name"),(0,r.kt)("li",{parentName:"ul"},"CLI variables are always treated as global variables"),(0,r.kt)("li",{parentName:"ul"},"Added ",(0,r.kt)("inlineCode",{parentName:"li"},"dir:")," option to ",(0,r.kt)("inlineCode",{parentName:"li"},"includes")," to allow choosing on which directory an\nincluded Taskfile will run:")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"includes:\n  docs:\n    taskfile: ./docs\n    dir: ./docs\n")),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Implemented short task syntax. All below syntaxes are equivalent:")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '3'\n\ntasks:\n  print:\n    cmds:\n      - echo \"Hello, World!\"\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '3'\n\ntasks:\n  print:\n    - echo \"Hello, World!\"\n")),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '3'\n\ntasks:\n  print: echo \"Hello, World!\"\n")),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"There was a major refactor on how variables are handled. They're now easier to\nunderstand. The ",(0,r.kt)("inlineCode",{parentName:"li"},"expansions:")," setting was removed as it became unnecessary.\nThis is the order in which Task will process variables, each level can see the\nvariables set by the previous one and override those.",(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},"Environment variables"),(0,r.kt)("li",{parentName:"ul"},"Global + CLI variables"),(0,r.kt)("li",{parentName:"ul"},"Call variables"),(0,r.kt)("li",{parentName:"ul"},"Task variables")))),(0,r.kt)("h2",{id:"version-26"},"Version 2.6"),(0,r.kt)("admonition",{type:"caution"},(0,r.kt)("p",{parentName:"admonition"},"v2 schema support is ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/issues/1197"},"deprecated")," and will be\nremoved in a future release.")),(0,r.kt)("p",null,"Version 2.6 comes with ",(0,r.kt)("inlineCode",{parentName:"p"},"preconditions")," stanza in tasks."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '2'\n\ntasks:\n  upload_environment:\n    preconditions:\n      - test -f .env\n    cmds:\n      - aws s3 cp .env s3://myenvironment\n")),(0,r.kt)("p",null,"Please check the ",(0,r.kt)("a",{parentName:"p",href:"/usage/#including-other-taskfiles"},"documentation")),(0,r.kt)("h2",{id:"version-22"},"Version 2.2"),(0,r.kt)("admonition",{type:"caution"},(0,r.kt)("p",{parentName:"admonition"},"v2 schema support is ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/issues/1197"},"deprecated")," and will be\nremoved in a future release.")),(0,r.kt)("p",null,"Version 2.2 comes with a global ",(0,r.kt)("inlineCode",{parentName:"p"},"includes")," options to include other Taskfiles:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '2'\n\nincludes:\n  docs: ./documentation # will look for ./documentation/Taskfile.yml\n  docker: ./DockerTasks.yml\n")),(0,r.kt)("h2",{id:"version-21"},"Version 2.1"),(0,r.kt)("admonition",{type:"caution"},(0,r.kt)("p",{parentName:"admonition"},"v2 schema support is ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/issues/1197"},"deprecated")," and will be\nremoved in a future release.")),(0,r.kt)("p",null,"Version 2.1 includes a global ",(0,r.kt)("inlineCode",{parentName:"p"},"output")," option, to allow having more control over\nhow commands output are printed to the console (see ",(0,r.kt)("a",{parentName:"p",href:"/usage/#output-syntax"},"documentation")," for\nmore info):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '2'\n\noutput: prefixed\n\ntasks:\n  server:\n    cmds:\n      - go run main.go\n  prefix: server\n")),(0,r.kt)("p",null,"From this version it's also possible to ignore errors of a command or task\n(check documentation ",(0,r.kt)("a",{parentName:"p",href:"/usage/#ignore-errors"},"here"),"):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},'version: \'2\'\n\ntasks:\n  example-1:\n    cmds:\n      - cmd: exit 1\n        ignore_error: true\n      - echo "This will be print"\n\n  example-2:\n    cmds:\n      - exit 1\n      - echo "This will be print"\n    ignore_error: true\n')),(0,r.kt)("h2",{id:"version-20"},"Version 2.0"),(0,r.kt)("admonition",{type:"caution"},(0,r.kt)("p",{parentName:"admonition"},"v2 schema support is ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/issues/1197"},"deprecated")," and will be\nremoved in a future release.")),(0,r.kt)("p",null,"At version 2, we introduced the ",(0,r.kt)("inlineCode",{parentName:"p"},"version:")," key, to allow us to evolve Task with\nnew features without breaking existing Taskfiles. The new syntax is as follows:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '2'\n\ntasks:\n  echo:\n    cmds:\n      - echo \"Hello, World!\"\n")),(0,r.kt)("p",null,"Version 2 allows you to write global variables directly in the Taskfile, if you\ndon't want to create a ",(0,r.kt)("inlineCode",{parentName:"p"},"Taskvars.yml"),":"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '2'\n\nvars:\n  GREETING: Hello, World!\n\ntasks:\n  greet:\n    cmds:\n      - echo \"{{.GREETING}}\"\n")),(0,r.kt)("p",null,"The variable priority order changed to the following:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},"Task variables"),(0,r.kt)("li",{parentName:"ol"},"Call variables"),(0,r.kt)("li",{parentName:"ol"},"Taskfile variables"),(0,r.kt)("li",{parentName:"ol"},"Taskvars file variables"),(0,r.kt)("li",{parentName:"ol"},"Environment variables")),(0,r.kt)("p",null,"A new global option was added to configure the number of variables expansions\n(which default to 2):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"version: '2'\n\nexpansions: 3\n\nvars:\n  FOO: foo\n  BAR: bar\n  BAZ: baz\n  FOOBAR: '{{.FOO}}{{.BAR}}'\n  FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'\n\ntasks:\n  default:\n    cmds:\n      - echo \"{{.FOOBARBAZ}}\"\n")),(0,r.kt)("h2",{id:"version-1"},"Version 1"),(0,r.kt)("admonition",{type:"caution"},(0,r.kt)("p",{parentName:"admonition"},"v1 schema support was removed in Task >= v3.0.0.")),(0,r.kt)("p",null,"In the first version of the ",(0,r.kt)("inlineCode",{parentName:"p"},"Taskfile"),", the ",(0,r.kt)("inlineCode",{parentName:"p"},"version:")," key was not available,\nbecause the tasks was in the root of the YAML document. Like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},'echo:\n  cmds:\n    - echo "Hello, World!"\n')),(0,r.kt)("p",null,"The variable priority order was also different:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},"Call variables"),(0,r.kt)("li",{parentName:"ol"},"Environment"),(0,r.kt)("li",{parentName:"ol"},"Task variables"),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("inlineCode",{parentName:"li"},"Taskvars.yml")," variables")))}m.isMDXComponent=!0}}]);