Consider revising the README to be friendlier to new users

[gonzojive]

The first page branchless users see is the README.md. I find this page gives a disjointed view of branchless, and it would be easier for new users if organized differently.

Can a "concepts" section be added, or prominently featured, that explains as concisely as possible the things branchless users need to grasp to use it effectively? How do I as a user need to change my mental model? The current page comes across as a laundry list of features that are each individually useful; is there something more basic that branchless does to improve git workflows?

Intention here is to give some feedback about what it's like to hit the branchless web page as a new user. I hear my coworkers talk about using branchless and want to try it out, but every time I have come to the github home page for it, I don't really get what it's about and am deterred by the the long list of links. I suspect a bit of a rewrite to the home page could make it simpler to grasp & faster to get started.

[arxanas]

Thanks for your feedback. At present, this is (unfortunately) a deliberate decision. The ideology here is based on a couple of principles:

• People learn best by starting with the concrete and moving to the abstract (see e.g. https://www.ascd.org/el/articles/balancing-the-concrete-and-the-abstract). Thus, I've listed a bunch of concrete (but disjointed) features in the README, which showcase concrete workflows, even though they don't have obvious unifying themes.
• Software is adopted via "killer feature", rather than by incremental improvement. Thus, the hope is that one or two of the specific features will entice users to adopt git-branchless, and they'll organically discover some of the others.

is there something more basic that branchless does to improve git workflows

The main problem is that nobody has found a small characterization of what git-branchless (or, say, Mercurial) does to improve workflows, including the (currently) 19 respondents to the User Survey. In general, workflow enhancements are very hard to communicate, because they tend to improve "death by a thousand cuts" issues, where no individual issue is worth abandoning the previous workflow, but taken as a whole, the new workflow is substantially better.

I don't really get what it's about and am deterred by the the long list of links

The intended use-case for you is that you find a single feature you like and try it out 🙂. The easiest "killer feature" to communicate is using git undo to undo arbitrary operations on the commit graph. You can also take a look at the "Workflows" section in the sidebar of the Wiki and see if you have problems with any of those, and, if so, you can try the listed soultions.

While I'm here, I'll summarize the results of the "naming" section of the User Survey, which are pretty amusing and indicate an obvious problem. Most people think that "git-branchless" is a bad name, and I certainly agree!

• Did you find the name "git-branchless" helpful in your decision it try it?
  • Yes: 8/18 (44%)
  • No: 8/18 (44%)
  • (other): 2/18 (11%)
• Do you find the name "git-branchless" to be adequately descriptive of its functionality?
  • Yes: 4/18 (26%)
  • No: 11/18 (73%)
• Do you think the name should be changed?
  • Yes: 6/14 (43%)
  • No: 5/14 (34%)

Freeform remarks on naming:

My primary benefit of this tool is managing a stack of commits, but having 1:1 relationship between commit and branch is crucial to my review workflow.

The feature is not the absence of branches, it's the stack of (commits|branches)

To be honest, I found the "branchless" and "monorepo scale" terms confusing and potentially misleading. I recall feeling like this tool was intended for use in large organizations w/ high degrees of engineering discipline. (We are a [small team] w/ very informal engineering practices.) Basically, it set off major imposter syndrome alarms. [...] Though I think a name change would reduce some of this, it seems like no name will accurately capture the flexibility, speed and general awesomeness of these tools.

I think the way I found this tool was because I was searching for a dev workflow more similar to Mercurial (e.g. restacking commits after amending, moving entire subtrees around). Maybe googled for "git rebase subtree"

FWIW It occurred to me that I find the term "nameless branch" a more informative term than "anonymous branch", in terms of identifying what's different about the branch.. i.e. it immediately sets up the contrasting attribute..

e.g. "How does X differ from a 'normal branch""?

"nameless" --> "Oh, I guess it differs because it doesn't need/ have a name?"

"anonymous" --> "Oh, I guess it differs because it wears a fake nose & mustache?" :D

I don't like the current name - it's a bit confusing for newcomers, but I'm not sure whether a new name would help or hinder. I feel like git-branchless has developed a reputation of "that really good tool with a misleading name" :P

My understanding of git-branchless is that it is a combination of tools that provide the following:

• an implementation of changeset evolution / patch stacks like Facebook/Google Mercurial (the commit hooks, restack, hide/unhide)
• convenient (and fast!) ways of doing Git things which fit into the patch stack workflow, which are often useful outside of it (sync, sl, amend/reword, next/prev, sl, move)
• revsets (surprisingly useful!)
• a time machine (undo)

It's very difficult to summarize all of this into one simple understandable name. "changeset evolution/patch stack" is probably the main focus here, and I can't think of a name which is less confusing than "branchless". Additionally, there's a few tools here which are very useful outside of a changeset evolution / patch stack workflow. A completely unrelated name could work - and out of the names given, git-quantum feels the best.

Some of the names suggested above seem nondescriptive (e.g. git-velocity sounds like a tool to calculate commit rate or something) or even misleading (git-centralized makes it sound like a central server is required, whereas I actually use the tool to make decentralized mailing list workflows easier; and git-monorepo makes it sound like benefits are only for large repos). Basically, don't sell the tool short in terms of how widely applicable/useful it is! I don't have any better suggestions, but maybe something that indicates it's good for working with independent/stacked patches?

So you can see that mostly everyone agrees that the name is bad, but also that it's hard to come up with an accurate description of what the tool does 😄.

[amardeep]

It is just my opinion, and ymmv, but I agree with original comment that the readme / documentation is not great and could be improved a lot.

Also, a concrete suggestion about documentation - I would love to have something similar to Overview pages in sapling docs, for eg. Navigation. Though this would probably belong in the wiki and not in the README.