Allow multiline commit messages when using a custom .cz.toml

[FelixAbrahamsson]

Description

I would like to be able to write multiline commit messages, however this does not seem to be possible when configuring commitizen using .cz.toml.

Possible Solution

Based off of #74 it seems to work when you customize commitizen via a class, however the filter parameter in .cz.toml doesn't seem to work for this use case currently (it gives me ValueError: 'filter' needs to be function that accepts an argument no matter what I input).

One suggestion would be if you could enclose your commit message in double quotes, and any enter keypress within those double quotes would just input a newline to the commit message instead of ending the text input. Another suggestion would be if you could specify a parameter multiline or similar which upon asking the question opens up a default editor (nano/vim) where the user writes their message, just like how git does with git commit.

[Lee-W]

If you add | to your body (but not scope), it will be turned into a break line. This feature is not well documented at this moment.

[josix]

Probably we should add some notes to the prompt information? If it is possible, please feel free to assign this issue to me. And I can also try to enhance this feature by enclosing the commit messages in single/double quotes so that it could accept the multiline messages more intuitivly.

[Lee-W]

Yes, we definitely should improve the message. Thanks for your help 🙂

I'm not sure the idea of the quote is what we wanted. What is the expected behavior if we have a This "line" should not break message?

[josix]

IMO, I image the behavior of using quotes should work like entering value contain multi-line words in echo parameter. So, if the message body is This "line" should not break, the body message will display as the same words but removing the quotes, like This line should not break. And it is required to add a backslash before the quote so that we could identify the quotes should be contained in the body message. On the other hand, if there is a newline character entering between the quotes. we should allow the user keep typing in the new line. Just like following screenshot:

[Lee-W]

I'm neutral to this one since multiple-line does not bother me at all recently haha. I'm curious whether there's tool that can help us make this echo behavior happen easier.

[josix]

Yeah, I also have concern about it. I should make some survey.

[FelixAbrahamsson]

If you add | to your body (but not scope), it will be turned into a break line.

I assume this is something that needs to be configured manually if you're using a customized config? That's what I'm doing, and the | character is not being translated into a newline character for me.

[Lee-W]

@FelixAbrahamsson Yes, it uses the filter here

[FelixAbrahamsson]

Right, that's what I was trying to do with the filter parameter in the .toml config, but it didn't seem to be possible. Does this only work via the custom class configuration?

[Lee-W]

I think custom class configuration should work in this case

[blaggacao]

Wouldn't it just be possible to work with a proper heredoc for this? Using | still is very uncomfortable to properly format a paragraph.

[marier-nico]

I was also curious about this feature and I did a little bit of digging around and found that Questionary was used to prompt the user to input commit information. So I had a look at Questionary and it looks like there's an option to enable multiline input there!

Relevant Questionary docs: https://questionary.readthedocs.io/en/stable/pages/types.html#type-text

@Lee-W Do you think it would be possible to use that option in commitizen? I haven't tested this feature of Questionary myself though, so it might not be what I think it is either :thinking:

[Lee-W]

Thanks @marier-nico ! Didn't notice this cool new feature.

But the behavior would change a bit. If we apply this, we'll need to type Esc, Enter or Alt, Enter when we type the message. Another idea is making it configurable. If not enabled, we'll keep the original | behavior. @Woile What do you think?

[woile]

For a normal flow it may be too disruptive, you want to move fast by pressing enter, I think the multiline should be enabled as a config indeed, set to False by default.

[Lee-W]

Same thought. I'll work on this one 💪

[Lee-W]

It seems we'd better wait for the latest questionary version. https://github.com/tmbo/questionary/issues/109 Otherwise, we'll need to bound the python version to ">=3.6.1,<3.10"

[Lee-W]

I think to implement this feature we'll need to make cz configurable which might related this issue https://github.com/commitizen-tools/commitizen/issues/395

[arunanshub]

One solution would be to allow passing of flags used by git commit via git cz commit (eg. git cz commit -e or git cz commit -- -e). This is what I've been using for cz-cli.

[Lee-W]

Hi @arunanshub , the feature you propose was actually discussed on https://github.com/commitizen-tools/commitizen/issues/248. But the problem of this issue I that we did not make our cz rules highly configurable except cz_cutsomize.

[ciscoski]

Hello there, Is there any news on this ? Thanks

[Lee-W]

Hi @ciscoski , unfortunately, 'm out of bandwidth. Feel free to send us a PR. Thanks!

[marcosdotme]

@ciscoski @FelixAbrahamsson @Lee-W

I'm creating an custom plugin as a Python module as mentioned on documentation here.

So, since commitizen is based on questionary we can pass the keyword argument multiline=True for each question that we have. For example:

class JiraCz(BaseCommitizen):
    def questions(self) -> Questions:
        questions = [
            {
                "type": "text",
                "name": "issue_title",
                "message": "Issue title:",
                "multiline": False
            },
            {
                "type": "text",
                "name": "issue_description",
                "message": "Issue description:",
                "multiline": True
            },
        ]
        return questions

    ...

I also tested the same behavior configuring the questions through a file:

[tool.commitizen]
name = "cz_customize"

[tool.commitizen.customize]
# ...

[[tool.commitizen.customize.questions]]
type = "text"
name = "issue_title"
message = "Issue title:"
multiline = false

[[tool.commitizen.customize.questions]]
type = "text"
name = "issue_description"
message = "Issue description:"
multiline = true

Using this plugin:

cz --name cz_customize commit --dry-run

This is the result:

? Issue title: My issue title
? Issue description:  (Finish with 'Alt+Enter' or 'Esc then Enter')
> My long
 
  long
 
  description