Chromium Code Reviews
|
|
Chromium Code Reviews
Issue
1875063002:
Clarify how `new-branch` is different for --help (Closed)
|
Created:
4 years, 8 months ago by anatoly techtonik Modified:
4 years, 8 months ago CC:
chromium-reviews, dpranke+depot_tools_chromium.org, iannucci+depot_tools_chromium.org Base URL:
https://chromium.googlesource.com/chromium/tools/depot_tools.git@master Target Ref:
refs/heads/master Project:
depot_tools Visibility:
Public. |
DescriptionClarify how `new-branch` is different for --help
BUG=
Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=300032
Patch Set 1 #
Total comments: 3
Patch Set 2 : Stick to one line description #Messages
Total messages: 12 (4 generated)
Description was changed from ========== Clarify how `new-branch` is different for --help BUG= ========== to ========== Clarify how `new-branch` is different for --help BUG= ==========
techtonik@gmail.com changed reviewers: + agable@chromium.org, iannucci@chromium.org, pgervais@chromium.org
https://codereview.chromium.org/1875063002/diff/1/git_new_branch.py File git_new_branch.py (right): https://codereview.chromium.org/1875063002/diff/1/git_new_branch.py#newcode9 git_new_branch.py:9: """ This description isn't strictly correct. In particular, you mean `git checkout`, not `git branch`; and new-branch can create branches tracking the current one as well with the -t flag. Also, we want to keep the description 1 line, to match the others. The best idea here is to crib the first line of the man page: "Create a new branch with correct tracking information". Or if you want to be slightly more descriptive, it could be "Create a new branch correctly tracking origin/master".
https://codereview.chromium.org/1875063002/diff/1/git_new_branch.py File git_new_branch.py (right): https://codereview.chromium.org/1875063002/diff/1/git_new_branch.py#newcode9 git_new_branch.py:9: """ Yes, I constantly forgot that `git branch` for removing branches, not creating them. As for 1 line description `glient` help is more nicely formatted and doesn't stick to this standard. For me it is important to understand how is the command different from standard git way of creating branches, so I'd wish that command line help reflected that. "branch tracking" concept is rather confusing for people with CVS, SVN, HG background, so I'd simplify this for people without understanding how git really works.
https://codereview.chromium.org/1875063002/diff/1/git_new_branch.py File git_new_branch.py (right): https://codereview.chromium.org/1875063002/diff/1/git_new_branch.py#newcode9 git_new_branch.py:9: """ On 2016/04/12 at 20:19:24, anatoly techtonik wrote: > Yes, I constantly forgot that `git branch` for removing branches, not creating them. As for 1 line description `glient` help is more nicely formatted and doesn't stick to this standard. Yeah, I meant the other git-extensions, not gclient. > > For me it is important to understand how is the command different from standard git way of creating branches, so I'd wish that command line help reflected that. Note that all of these tools have big man pages, as does depot_tools itself. `man depot_tools` and `git help new-branch` provide a lot more documentation. I think it is appropriate in this case for the short doc to be a single line. > "branch tracking" concept is rather confusing for people with CVS, SVN, HG background, so I'd simplify this for people without understanding how git really works. The point is that it isn't just "on top of". `git checkout -b foo` creates a branch "on top of" the current branch. `git new-branch` creates a branch *tracking* origin/master. This is an important distinction, and one that should be pointed to in this help string.
Updated CL. On 2016/04/13 16:41:55, agable wrote: > > Yeah, I meant the other git-extensions, not gclient. Why not to stick to gclient standard? Most git command don't have one line help. And those who do, don't have this awkward "positional arguments" paragraph. > Note that all of these tools have big man pages, as does depot_tools itself. > `man depot_tools` and `git help new-branch` provide a lot more documentation. I > think it is appropriate in this case for the short doc to be a single line. Neither of which works on Windows - https://bugs.chromium.org/p/chromium/issues/detail?id=604018 I usually try to avoid launching browser, because my default browser maybe different from the one that I currently use, and if I testing things in anonymous session, opening non-anonymous page kills my previously opened pages. Launching browser is also slow on my 32-bit machine with 3.2Gb of memory. Chrome eats a lot. > > "branch tracking" concept is rather confusing for people with CVS, SVN, HG > background, so I'd simplify this for people without understanding how git really > works. > > The point is that it isn't just "on top of". `git checkout -b foo` creates a > branch "on top of" the current branch. `git new-branch` creates a branch > *tracking* origin/master. This is an important distinction, and one that should > be pointed to in this help string. So what does "tracking" means then? If I do traditional checkout and then I pull changes, git merges them with top or rebases them (of -r specified) on top of the branch that was current. It is the same as tracking?
On 2016/04/15 at 21:03:08, techtonik wrote: > Updated CL. > > On 2016/04/13 16:41:55, agable wrote: > > > > Yeah, I meant the other git-extensions, not gclient. > > Why not to stick to gclient standard? Most git command don't have one line help. And those who do, don't have this awkward "positional arguments" paragraph. > > > Note that all of these tools have big man pages, as does depot_tools itself. > > `man depot_tools` and `git help new-branch` provide a lot more documentation. I > > think it is appropriate in this case for the short doc to be a single line. > > Neither of which works on Windows - https://bugs.chromium.org/p/chromium/issues/detail?id=604018 > > I usually try to avoid launching browser, because my default browser maybe different from the one that I currently use, and if I testing things in anonymous session, opening non-anonymous page kills my previously opened pages. Launching browser is also slow on my 32-bit machine with 3.2Gb of memory. Chrome eats a lot. > > > > "branch tracking" concept is rather confusing for people with CVS, SVN, HG > > background, so I'd simplify this for people without understanding how git really > > works. > > > > The point is that it isn't just "on top of". `git checkout -b foo` creates a > > branch "on top of" the current branch. `git new-branch` creates a branch > > *tracking* origin/master. This is an important distinction, and one that should > > be pointed to in this help string. > > So what does "tracking" means then? If I do traditional checkout and then I pull changes, git merges them with top or rebases them (of -r specified) on top of the branch that was current. It is the same as tracking? No, "git pull" always only acts upon the currently checked out branch and a single remote repository. "git pull origin master" is almost exactly equivalent to "git fetch origin && git merge origin/master" (with the exception that the former leaves your other refs/remotes/origin/* refs alone). Tracking lets you do more complex things. For example: > git checkout origin/master # we're now "headless" > git checkout -b my_new_branch > git fetch origin # assume some new commits showed up in origin, that we now want to incorporate into my_new_branch > git rebase # this fails It fails because there's nothing to rebase against. It doesn't know where to look. Tracking info solves that: > git checkout -b my_new_branch -t origin/master # create branch *tracking* origin/master > git fetch origin > git rebase # this succeeds And "git checkout -b foo -t origin/master" is exactly what "git new_branch" does. And "git fetch origin && git rebase" is a simplified version of what "git rebase-update" does. Try creating a bunch of branches using "git new_branch" and "git new_branch -t". Then run "git map-branches". It will show you the full tree structure of your branches, showing which ones track origin/master, which ones track each other, etc. That's what tracking info gets you. Anyway, thanks for creating this CL, and thanks for updating the doc. LGTM!
The CQ bit was checked by techtonik@gmail.com
CQ is trying da patch. Follow status at https://chromium-cq-status.appspot.com/patch-status/1875063002/20001 View timeline at https://chromium-cq-status.appspot.com/patch-timeline/1875063002/20001
Message was sent while issue was closed.
Description was changed from ========== Clarify how `new-branch` is different for --help BUG= ========== to ========== Clarify how `new-branch` is different for --help BUG= Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=300032 ==========
Message was sent while issue was closed.
Committed patchset #2 (id:20001) as http://src.chromium.org/viewvc/chrome?view=rev&revision=300032 |
