A newbie gets the hugo executable, and runs it in a random directory. Instead of a nice message of how to use hugo, they get an ugly error message, and no information on how to proceed. They then file a bug on github.
Currently, running hugo with no arguments tries to generate a site from some expected directory structure in the current directory. This means that people who mistake hugo for an installer, or are trying to start off with it and don’t know how to use it get error messages as their first experience with Hugo.
The Solution
I think the “generate site” behavior should be moved to a subcommand like hugo gen and have the bare hugo command simply print out the help. This results in a much friendlier first experience, and gives the user a stepping stone to actually being successful with Hugo.
I think this is also good even for experienced users, because it’s a lot easier to talk about a “gen” subcommand (and easier to print out help for it) than to talk about the base command. Currently when you print out the help, you’re actually printing out help for the base command plus a listing of all subcommands. If it were its own subcommand, we could have much more extensive documentation for it without interfering with the base “how to use hugo” help.
This was a conscience decision. The earliest build had `hugo build` as the build command . It felt needless. I believe you should design and optimize for the most common use case.
Another way to think about it, the bare command run by a new user in ignorance happens once. They will run hugo build hundreds of times.
Alternatively they run bare and don’t see what they expect, run hugo help, then the bare command forever after that.
It saves tons of typing.
What I think we should do is make the experience when a bare call is made and the config file isn’t found much better.
Instead of just the error message what if hugo said “hugo can’t find the sites source directory, should hugo initialize a new site?” prompt for the name, then internally run hugo new NAME.
I’m open to discussing it further. Personally I run hugo server the most. I’ve given thought to workflows. hugo dev = hugo server --buildDrafts for example.
Well, the other problem with having the base command also be the generate command, is that it’s hard to find the help about how to generate the site. We’ve seen this with people asking “how do I just generate the site?” Notably, if you do hugo help, nowhere does it have an indication of how to generate your site.
In addition, by putting a functional command on the base hugo command, its flags dirty up all the subcommands. hugo help new for example shows all the flags for site generation, that totally don’t apply to new. That might be fixable without other changes, but it kind of goes to show that most of the time, if you have subcommands, the base command doesn’t actually do anything.
A good example is git, the canonical executable with subcommands. Running just “git” shows you the help, and that’s it.
The problem with making hugo do something is that it’s unclear what it’ll actually do. Hugo the executable does a lot of stuff, and without some other word explaining what it’s doing, you have to just know.
I do git pull and git push and git clone all the time. A few extra characters to type out really don’t bother me. It would be annoying if it were something like hugo go-generate-my-site-kthxbye … but a mere hugo gen or hugo build is trivial to type, and I think a lot more clear.
I know that for me, I also never type just hugo. I always type hugo -d production when I “really mean it”… specifically because I want to make sure that I only do that when I’m totally sure my changes are good and are ready to be pushed to production. Making that hugo build -d production is not really a big deal
But I’d love to hear from anyone else who has an opinion on the subject, too.
On the upside, the biggest problem someone is going to have is that when they do something like hugo -d production, it’ll print out the help, which will show them immediately there’s a nice new “hugo build” (or whatever) command
I jest, but I do understand that this could cause confusion for people. Hopefully we can make some big note in the release notes for a new version stating the difference. I do think this will help us in the long run, because it’s the newbies that can get most discouraged from getting weird error messages, even if we try to make them a nicer error message.
Outsiders point of view:
I also run hugo the first time and were surprised about the error.
No big deal to try hugo help or hugo --help but would be nicer to just run hugo.
I found myself using hugo server --watch most of the time. hugo is just used in the deploy script. So what I did is adding alias hd='hugo server --watch' to my .zshrc.
