Overrides & documentation

[thomaseizinger]

Problem Description

We have found cargo-make to be very useful, thanks for making it!

The override concept is pretty powerful but at the same time requires developers to be aware of what the defaults are in order to understand/predict, which tasks will be executed.

I've got some ideas on how cargo-make could help here. Some of them are orthogonal. Overall, the goal is make it possible for a developer that has basic understanding of cargo-make + is new to a project that uses it to understand, how the local configuration works.

1. A more concise output of --print-steps. The current output doesn't fit on one terminal screen, which makes it basically unusable if I want to get a quick overview of what a command will do. Maybe just print the task name + description? I think it would also add value if --print-steps could highlight somehow, which of the tasks were modified by the local config.
2. A --diff flag to see, how the current config modifies the built-in one. Since cargo-make is most likely invoked from an interactive-terminal, the output could be similar to git-diff. (Maybe even with some nice colors?)
3. A required attribute overridden_because that forces you to specify a small sentence on why the local config has to override the default task.

If there would be other ways to configure certain things, we could also get rid of some of the overrides. For example, we wanted to remove the --verbose flag from the build + test arguments because it just spams our logs and doesn't really add value. Maybe there could be a way to modify the argument list of a task without having to replace it?
The issue with replacing is that it is not self-documenting: A developer coming across the configuration file will not know, what the original arguments were without searching through the documentation of cargo-make.

[sagiegurari]

I think overall the problem you are stating is very real and I totally agree that cargo-make should provide the tools to help and make extending files more understandable.
I'll definitely think of something and work on it.

• its very interesting point. I agree print steps can be improved much and maybe add 'human readable' output and not huge structure.
• diff might be too complex so we could do print steps with your custom makefile.toml and without... need to think about this one. but its very interesting.
• adding required attributes is definitely going to break cargo-make for many and i'm not sure if we want to force people to document things. its really up to the person/team/project. I do have a documentation attribute that you can use for that and its integrated with those cli flags.

[thomaseizinger]

Thanks for your quick response.

The diff part might actually not be too hard because you don't have to do the diffing yourself. git diff can be invoked with --no-index outside of a git-repository. So all you would have to add is printing the default configuration to a file + the final configuration and invoking git-diff. I think the rust toml library automatically formats/sorts the keys in a toml file upon serialization so the diff should already be quite meaningful :)

[sagiegurari]

@thomaseizinger I just added a new output format option which should help and partially resolve some of the issues you listed in here.
--output-format <OUTPUT FORMAT> The print steps format [default: default] [possible values: default, short-description]

it would basically print a list of tasks with name and description only which give high level overview of what is going to executed.
i'll think of other things you mentioned in this task like diff later on.

[sagiegurari]

@thomaseizinger diff flows is now also supported via new cli command.
Example:

[cargo-make] INFO - cargo make 0.16.0
[cargo-make] INFO - Using Build File: ./examples/override_core.toml
[cargo-make] INFO - Task: post-build
[cargo-make] INFO - Setting Up Env.
[cargo-make] INFO - Printing diff...
[cargo-make] INFO - Execute Command: "git" "diff" "--no-index" "/tmp/cargo-make/nIcv9f5Mur.toml" "/tmp/cargo-make/qfZeaxVN3R.toml"
diff --git a/tmp/cargo-make/nIcv9f5Mur.toml b/tmp/cargo-make/qfZeaxVN3R.toml
index 5152290..ba0ef1d 100644
--- a/tmp/cargo-make/nIcv9f5Mur.toml
+++ b/tmp/cargo-make/qfZeaxVN3R.toml
@@ -42,7 +42,9 @@
         name: "post-build",
         config: Task {
             clear: None,
-            description: None,
+            description: Some(
+                "Overide description"
+            ),
             category: Some(
                 "Build"
             ),
[cargo-make] INFO - Done

Using git as you recommended so it has the normal git colors for the diff.
its available in the 0.16.1 development branch.

[thomaseizinger]

Awesome! Thanks a lot :)

[sagiegurari]

@thomaseizinger 0.16.1 has just been published with all changes.
closing this issue. if you need anything more, feel free to open a new issue.