Stdout behaviour of `tuist graph`

Ideas
1

While using tuist graph --format json I noticed that it does not play nicely with expected CLI behaviour:

  1. It does automatically pipe the graph JSON content into a file. It would be great if the graph content can be piped to stdout in order to also play nicely with existing CLI tools. We could then also pipe the content into tools like jq
  2. When running tuist graph --format JSON it does output additional log messages which would mess up piping the data. E.g. it logs things like warnings in the project setup.

What you think about this things ? Are they valid and worth to change ?

Looking forward to your opinions !

1 Like
2

Hi @alexanderwe

We changed our approach to logging recently, and that might have caused a regression.

  1. It does automatically pipe the graph JSON content into a file. It would be great if the graph content can be piped to stdout in order to also play nicely with existing CLI tools. We could then also pipe the content into tools like jq

I’m on board with this. Three ides for how we can go about it:

  • Adjust the default behavior to output to stdout. One can then pipe that to a file using pipe operators. It’s a breaking change, and I’d expect some users to be using this feature already.
  • Add a new option to force the output to go to standard output --output stdout. I personally don’t like this one because there are some formats like image for which that option doesn’t apply.
  • Add a new format type, stdout-json, tuist graph --format stdout-json
  1. When running tuist graph --format JSON it does output additional log messages which would mess up piping the data. E.g. it logs things like warnings in the project setup.

We shouldn’t output anything else when the format is json. We have some generic logic that sets a logger when it detects a --json argument, but it doesn’t work with the above scenario. Two options here:

  • We can revisit the presentation of GraphCommand to ensure nothing is output to the user if the format is json.
  • Adjust this logic to work if any argument contains the string json.

I lean on the former.

3

Adjust the default behavior to output to stdout. One can then pipe that to a file using pipe operators. It’s a breaking change, and I’d expect some users to be using this feature already.

I personally would prefer to use stdout per default, even though it’s maybe a breaking change. It would emphasise the existing “industry standards” for writing CLI applications. Especially supporting piping etc. Following e.g. Command Line Interface Guidelines

We can revisit the presentation of GraphCommand to ensure nothing is output to the user if the format is json.

Would it be possible to only show log messages when explicitly requested ? For example in the graph command I am not sure how important it is to have the logs per default. I also read that most of the logging should go to stderr (Command Line Interface Guidelines). But I am also not too familiar with the current logging mechanisms in the CLI.

4

We have technically speaking made a breaking change already when changing the tuist graph --format json output to be in the format of XcodeGraph instead of ProjectAutomation. So, I’m in favor of updating the behavior now and keeping the old behavior for the --legacyJSON format option.

There should be no extra output when --json is passed (see here, but as @pepicrft mentioned, a regression might have snuck in.

5

We have a plan. @alexanderwe would you like to take it on?

6

@pepicrft Sure ! What is the plan exactly ?

  1. Introduce the legacyJSON option
  2. Fix the bug with unwanted output

Or something else ?

7

Leave —legacyJSON as it is, and apply the changes and the fix to the —json flag. @marekfort introduced that one recently (breaking change) to output an XcodeGraph instead of the schema that we previously output (hence the rename of that one to —legacyJSON)

8

Okay, so basically just change --format json to output to stdout and only to file if --output-path is specified. Addtionally remove that the log messages appearing on stdout.

Did I understand that correctly ?

9

Yes, that’s correct. And preserve the current behavior when --legacyJSON is used. Note the non-JSON content for that option should be stripped, too.

10

@marekfort @pepicrft alright understood - I am going to tackle it :slight_smile:

Is there any timeline for it?

11

The sooner, the better before folks start to depend on the new tuist graph --format json. But of course, we understand you’d be doing this in your free time, so don’t feel pressured to rush onto this. Just let us know if you don’t have time to look into this in the following weeks. Ideally, I’d love to see this shipped in the next two weeks or so.

12

As of now this should be fine. I will start taking a look at the code to get an overview. In case of code discussions, I guess we will handle this in a PR or Slack then and not here ?

13

Yup! Feel free to create a draft PR and ping us there :slightly_smiling_face: