"Julia Evans via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
> * Improve the storytelling in the commit messages
> * Take a different approach to the git checkout -b description (keep reset
> in -B, but simplify the description of -B a lot)
> * Make the description of git checkout [<branch>] more accurate.
> * Try a different approach to git checkout file.txt ("Discard any unstaged
> changes...")
Not just you repeat having bulleted list in your proposed log
messages (which I already said something about, remember?), now you
have them in your cover letter, too? You must be so fond of
bulletted list X-<.
> @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
> -to checkout these paths out of the index.
> +When you run `git checkout <something>`, Git tries to guess whether
> +`<something>` is intended to be a branch, a commit, or a set of file(s),
> -+and then switches branches, switches commits, or restores the files.
> ++and then either switches to that branch or commit or restores the
> ++specified files.
Much better.
> ++ Switch to _<branch>_. This sets the current branch to _<branch>_ and
> ++ updates the files in your working directory. Files which are
> ++ identical in _<branch>_ and your current commit are left unchanged
> ++ so that you can keep your uncommitted changes to those files.
Here "left unchanged" is technically correct, but somehow it gives
me a (n incorrect) connotation that they are not modified since
HEAD, which is not what you wanted to say at all. I recall that we
once explained this not as "left unchanged", but as "changes follow
you", and I found the explanation easier to absorb.
I cannot come up with a good way to remove duplicates in the
following desciption, but what we want the reader to understand are
twofold:
* For paths that are not identical between HEAD and the _<branch>_
you are switching to, you MUST NOT have a local change. After
you switch to _<branch>_, these paths in the working tree match
that of the _<branch_>. This is to avoid losing your local
changes.
* For paths that are identical between HEAD and the _<branch>_ you
are switching to, you may have local modifications, and they
follow you to the switched-to _<branch>_.
> ++`git checkout -b <new-branch> [<start-point>]`::
> ++
> ++ Create a new branch named _<new-branch>_, start it at _<start-point>_
> ++ (defaults to the current commit), and check out the new branch.
> ++ You can use the `--track` or `--no-track` options to set the branch's
> ++ upstream tracking information.
> +
> ++This fails without making any changes if there's an error checking out
> ++_<new-branch>_, for example if checking out the `<start-point>`
> ++commit would overwrite your uncommitted changes.
OK. Do people understand "making a(ny) changes" refers to creation
of the new branch, I have to wonder, but if so, the above is much
much nicer than the original text.
This fails without doing anything and without creating a new
branch, if checking out the <start-point> has to overwrite your
uncommitted changes.
might be slightly better? I dunno.
