feat: specify --init filename/path (#2018)

* feat: specify init filename with --taskfile flag

previously, it was not possible to specify which filename to use when initializing a new Taskfile as it was hardcoded as "Taskfile.yml".

now the --taskfile flag specifies where to write the file to, and the first * contained in it will be replaced by "Taskfile", so `task -it *.yaml` will create a `Taskfile.yaml` file.

* docs: update CLI reference

* fix Flags header being inside tip admonition
* change -t flag's default column and add a description
* add Default Filenames section

* docs: revert adding Default Filenames section

I didn't realize it already existed elsewhere.

* refactor: use path instead of filepath on InitTaskFile

as requested to prevent ambiguity with the stdlib package.

* fix TestInit (incorrectly merged)

* docs: remove outdated info on --taskfile flag

* refactor task initialization changes

- remove const DefaultTaskInitFilename from taskfile/taskfile.go
- revert description of Entrypoint flag
- make InitTaskfile accept a path to either a file or a directory, and join the default Taskfile name+ext to it if it is a directory
- take the target file path from the first argument instead of the Entrypoint flag
- detect extension-only filenames (".yaml") instead of replacing "*" with "Taskfile"
- use different format in success log so that it makes sense at different paths than the current dir

* print colon instead of "at"

it's a lot cleaner in most cases.

* rewrite init tests

test both initializing to a directory path and a file path

* return final path from InitTaskfile

...and print it's relative representation

* fix lint error (ineffassign)

* use filepathext.TryAbsToRel() instead

* define and use filepathext.IsExtOnly()

* link to default filenames list in cli ref docs

(specifically in the --taskfile flag description)

init.go

@@ -24,17 +24,29 @@ tasks:
 
 const DefaultTaskFilename = "Taskfile.yml"
 
-// InitTaskfile creates a new Taskfile
-func InitTaskfile(w io.Writer, dir string) error {
-	f := filepathext.SmartJoin(dir, DefaultTaskFilename)
-
-	if _, err := os.Stat(f); err == nil {
-		return errors.TaskfileAlreadyExistsError{}
+// InitTaskfile creates a new Taskfile at path.
+//
+// path can be either a file path or a directory path.
+// If path is a directory, path/Taskfile.yml will be created.
+//
+// The final file path is always returned and may be different from the input path.
+func InitTaskfile(w io.Writer, path string) (string, error) {
+	fi, err := os.Stat(path)
+	if err == nil && !fi.IsDir() {
+		return path, errors.TaskfileAlreadyExistsError{}
 	}
 
-	if err := os.WriteFile(f, []byte(DefaultTaskfile), 0o644); err != nil {
-		return err
+	if fi != nil && fi.IsDir() {
+		path = filepathext.SmartJoin(path, DefaultTaskFilename)
+		// path was a directory, so check if Taskfile.yml exists in it
+		if _, err := os.Stat(path); err == nil {
+			return path, errors.TaskfileAlreadyExistsError{}
+		}
 	}
 
-	return nil
+	if err := os.WriteFile(path, []byte(DefaultTaskfile), 0o644); err != nil {
+		return path, err
+	}
+
+	return path, nil
 }