I surveyed 16 Git users about the git push man page. Here's a rewrite of the DESCRIPTION section and the definition of <refspec> based on the feedback. The goal is to clarify it while communicating the same information. The most common piece of feedback was that folks didn't understand what the term "ref" means. Most of the users who said they did not understand the term "ref" have been using Git for 10+ years. The rewrite of the <refspec> section is more invasive than I usually prefer: I've tried to keep as much of the original text as possible, but if there are too many issues with it then I'll drop that patch from this series. Julia Evans (4): doc: git-push: update intro doc: git-push: clarify "where to push" doc: git-push: clarify "what to push" doc: git-push: rewrite refspec specification Documentation/git-push.adoc | 204 ++++++++++++++++++------------------ 1 file changed, 103 insertions(+), 101 deletions(-) base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/1964 -- gitgitgadget
