{"record":{"id":"1ba6902200ffec87","repo":"GitoxideLabs/gitoxide","slug":"explanations-are-only-for-human-consumption","errorCode":null,"errorMessage":"Explanations are only for human consumption","messagePattern":"Explanations are only for human consumption","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"warning","filePath":"gitoxide-core/src/repository/revision/resolve.rs","lineNumber":88,"sourceCode":"                    }\n                    let spec = gix::path::os_str_into_bstr(&spec)?;\n                    let spec = repo.rev_parse(spec)?;\n                    if cat_file {\n                        return display_object(&repo, spec, tree_mode, cache.as_mut().map(|c| (blob_format, c)), out);\n                    }\n                    if let Some(r) = spec.first_reference().filter(|_| show_reference) {\n                        writeln!(out, \"{}\", r.name)?;\n                    }\n                    if let Some(r) = spec.second_reference().filter(|_| show_reference) {\n                        writeln!(out, \"{}\", r.name)?;\n                    }\n                    writeln!(out, \"{spec}\", spec = spec.detach())?;\n                }\n            }\n            #[cfg(feature = \"serde\")]\n            OutputFormat::Json => {\n                if explain {\n                    anyhow::bail!(\"Explanations are only for human consumption\")\n                }\n                serde_json::to_writer_pretty(\n                    &mut out,\n                    &specs\n                        .into_iter()\n                        .map(|spec| {\n                            gix::path::os_str_into_bstr(&spec)\n                                .map_err(anyhow::Error::from)\n                                .and_then(|spec| repo.rev_parse(spec).map_err(Into::into))\n                                .map(gix::revision::Spec::detach)\n                        })\n                        .collect::<Result<Vec<_>, _>>()?,\n                )?;\n            }\n        }\n        Ok(())\n    }\n}","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/GitoxideLabs/gitoxide/blob/e73179060badf27222d790981fac3f84c1830a7e/gitoxide-core/src/repository/revision/resolve.rs#L70-L106","documentation":"`gix revision resolve` supports pretty-printed JSON output, but the optional per-spec 'explanation' feature only works in human output, so requesting `--format json` together with explanation (`--explain`) bails. Explanations have no JSON representation implemented, making this a mutually-exclusive-options guard.","triggerScenarios":"Calling `gix revision resolve --explain --format json` (resolve in gitoxide-core/src/repository/revision/resolve.rs, serde feature enabled): `OutputFormat::Json` combined with `explain == true`.","commonSituations":"Users wanting machine-readable explanations of how specs resolve; scripts piping resolve output to jq while also enabling --explain for debugging.","solutions":["Drop `--format json` when using `--explain` (explanations are human-only)","Drop `--explain` when JSON output is needed","Run two invocations: one human with --explain for insight, one JSON without it for scripts","Request JSON explanation support upstream"],"exampleFix":"// before\ngix revision resolve --explain --format json HEAD main\n// after\ngix revision resolve --format json HEAD main","handlingStrategy":"validation","validationCode":"# refuse the invalid combination before invoking\nif [ \"$explain\" = \"1\" ] && [ \"$fmt\" = \"json\" ]; then\n  echo \"--explain cannot be combined with --format json\" >&2; exit 2\nfi","typeGuard":null,"tryCatchPattern":"if ! out=$(gix revision resolve --explain --format json HEAD 2>&1); then\n  case \"$out\" in *\"only for human consumption\") gix revision resolve --format json HEAD;; esac\nfi","preventionTips":["Treat --explain as human-only; never pair it with --format json","Split debugging (explain, human) from scripting (json, no explain) into separate calls","Validate flag combinations in wrapper scripts","Read subcommand --help for documented exclusions"],"tags":["cli","json","explain","revision"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"e73179060badf27222d790981fac3f84c1830a7e","analyzedAt":"2026-09-08T11:26:50.865Z","contentChangedAt":"2026-09-08T11:26:50.865Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}