# Suggested improvements to the git-p4 documentation (branch-related) 6 messages from 2013-01-03 to 2013-02-23. Participants: Olivier Delalleau, Pete Wyckoff, Junio C Hamano. Thread: https://gitlist.dev/t/32521 ## Olivier Delalleau, 2013-01-03 20:58 Subject: Suggested improvements to the git-p4 documentation (branch-related) Message-ID: URL: https://gitlist.dev/e/CAFXk4bqt_pMVDtVKF-JiQuGbSpy2%2B_rGOg5RTTE%2B0pNKFcZh3w%40mail.gmail.com ``` Hi, While struggling to get git-p4 to work properly with branches, I thought the documentation on http://git-scm.com/docs/git-p4 could use some improvements: 1. At the end of the "Branch detection" section, the following commands are provided (for when you want to explicitly provide branch mappings to git-p4): git config git-p4.branchList main:branch1 git p4 clone --detect-branches //depot@all The second command should end with a dot (".") because the first command only works if you are already in a git-initialized folder. Thus I would also suggest to add "git init" as first command to type. 2. Even though having a "main" branch is standard in Perforce, it would be worth mentioning what happens when you don't: there is a message "Could not detect main branch. No checkout/master branch created" output by the "git p4 clone" command. However, it will still work if you manually set the master branch ("git checkout -b master remotes/p4/my_custom_main_branch"). 3. I don't know what I missed for that one, but I haven't been able to get the example for the --branch option to work. It says that after "git init", we can import a p4 branch with: git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 However, after doing this, followed by "git checkout -b proj2 remotes/p4/proj2", I am unable to properly use "git p4 sync" or "git p4 submit" from this branch, as git complains about a missing refs/remotes/p4/master. Maybe it only works if "git clone" has been used before? But then why have "git init" first? NB: it's quite possible some of my problems were caused by me not properly understanding the doc / how git/p4 works. My apologies if that's the case. -=- Olivier ``` ## Pete Wyckoff, 2013-01-05 21:25 Subject: Re: Suggested improvements to the git-p4 documentation (branch-related) Message-ID: <20130105212517.GA30315@padd.com> URL: https://gitlist.dev/e/20130105212517.GA30315%40padd.com In-Reply-To: ``` shish@keba.be wrote on Thu, 03 Jan 2013 15:58 -0500: > While struggling to get git-p4 to work properly with branches, I > thought the documentation on http://git-scm.com/docs/git-p4 could use > some improvements: Thanks, I definitely appreciate the constructive comments here. > 1. At the end of the "Branch detection" section, the following > commands are provided (for when you want to explicitly provide branch > mappings to git-p4): > > git config git-p4.branchList main:branch1 > git p4 clone --detect-branches //depot@all > > The second command should end with a dot (".") because the first > command only works if you are already in a git-initialized folder. > Thus I would also suggest to add "git init" as first command to type. That is confusing. I'll make it this: git init depot cd depot git config git-p4.branchList main:branch1 git p4 clone --detect-branches //depot@all . > 2. Even though having a "main" branch is standard in Perforce, it > would be worth mentioning what happens when you don't: there is a > message "Could not detect main branch. No checkout/master branch > created" output by the "git p4 clone" command. However, it will still > work if you manually set the master branch ("git checkout -b master > remotes/p4/my_custom_main_branch"). This feels like a bug to me, and indeed I had an old patch series that planned to fix it. Let me knock that into shape, instead of changing the documentation. It will automatically do the checkout step you did. > 3. I don't know what I missed for that one, but I haven't been able to > get the example for the --branch option to work. It says that after > "git init", we can import a p4 branch with: > > git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 > > However, after doing this, followed by "git checkout -b proj2 > remotes/p4/proj2", I am unable to properly use "git p4 sync" or "git > p4 submit" from this branch, as git complains about a missing > refs/remotes/p4/master. Yes, also annoying. I have a failing test case for this, but haven't fixed it yet. The idea is that "git p4 sync --branch=proj2" will sync refs/remotes/p4/proj2. If there is no p4/master, and you don't specify --branch, it will fail with a more useful error message. For submit, there is code that walks from your current branch back in history until it finds a commit on a known p4 remote branch. This is sort of like the merge-base calculation in git, but restricted to a linear history. I haven't tested that recently, but will add a test and fix it if needed too. Please do feel welcome to to rearrange or expand the documentation so it makes more sense, if you are so inspired. -- Pete ``` ## Olivier Delalleau, 2013-01-07 02:00 Subject: Re: Suggested improvements to the git-p4 documentation (branch-related) Message-ID: URL: https://gitlist.dev/e/CAFXk4bp0MBNxOD7w1zn7peN-ufWmV%3DDthMdHmjmj%2BSci4MGneg%40mail.gmail.com In-Reply-To: <20130105212517.GA30315@padd.com> ``` 2013/1/5 Pete Wyckoff : > shish@keba.be wrote on Thu, 03 Jan 2013 15:58 -0500: >> While struggling to get git-p4 to work properly with branches, I >> thought the documentation on http://git-scm.com/docs/git-p4 could use >> some improvements: > > Thanks, I definitely appreciate the constructive comments here. > >> 1. At the end of the "Branch detection" section, the following >> commands are provided (for when you want to explicitly provide branch >> mappings to git-p4): >> >> git config git-p4.branchList main:branch1 >> git p4 clone --detect-branches //depot@all >> >> The second command should end with a dot (".") because the first >> command only works if you are already in a git-initialized folder. >> Thus I would also suggest to add "git init" as first command to type. > > That is confusing. I'll make it this: > > git init depot > cd depot > git config git-p4.branchList main:branch1 > git p4 clone --detect-branches //depot@all . Sounds good, thanks. > >> 2. Even though having a "main" branch is standard in Perforce, it >> would be worth mentioning what happens when you don't: there is a >> message "Could not detect main branch. No checkout/master branch >> created" output by the "git p4 clone" command. However, it will still >> work if you manually set the master branch ("git checkout -b master >> remotes/p4/my_custom_main_branch"). > > This feels like a bug to me, and indeed I had an old patch series > that planned to fix it. Let me knock that into shape, instead of > changing the documentation. It will automatically do the > checkout step you did. Sounds good as well. > >> 3. I don't know what I missed for that one, but I haven't been able to >> get the example for the --branch option to work. It says that after >> "git init", we can import a p4 branch with: >> >> git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 >> >> However, after doing this, followed by "git checkout -b proj2 >> remotes/p4/proj2", I am unable to properly use "git p4 sync" or "git >> p4 submit" from this branch, as git complains about a missing >> refs/remotes/p4/master. > > Yes, also annoying. I have a failing test case for this, but > haven't fixed it yet. The idea is that "git p4 sync --branch=proj2" > will sync refs/remotes/p4/proj2. If there is no p4/master, and > you don't specify --branch, it will fail with a more useful error > message. Good too! > For submit, there is code that walks from your current branch > back in history until it finds a commit on a known p4 remote > branch. This is sort of like the merge-base calculation in git, > but restricted to a linear history. I haven't tested that > recently, but will add a test and fix it if needed too. > > > Please do feel welcome to to rearrange or expand the > documentation so it makes more sense, if you are so inspired. I'm afraid I'm not familiar enough with git documentation to dig into it myself, but anyway that's about what I had for now. I'll send more comments to the mailing list if I have more suggestions in the future. Thanks for a great tool! :) -=- Olivier ``` ## Junio C Hamano, 2013-02-23 00:42 Subject: Re: Suggested improvements to the git-p4 documentation (branch-related) Message-ID: <7va9qvc13r.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7va9qvc13r.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Olivier Delalleau writes: > 2013/1/5 Pete Wyckoff : >> shish@keba.be wrote on Thu, 03 Jan 2013 15:58 -0500: > ... >> Please do feel welcome to to rearrange or expand the >> documentation so it makes more sense, if you are so inspired. > > I'm afraid I'm not familiar enough with git documentation to dig into > it myself, but anyway that's about what I had for now. I'll send more > comments to the mailing list if I have more suggestions in the future. > > Thanks for a great tool! :) Did anything come out of this thread? If neither of you two are inclined to conclude the discussion with a final patch, I'd appreciate anybody else who does the honors ;-) We'll be in deep pre-release freeze for a few weeks, so there is no need to rush. Thanks. ``` ## Pete Wyckoff, 2013-02-23 14:48 Subject: Re: Suggested improvements to the git-p4 documentation (branch-related) Message-ID: <20130223144803.GA5444@padd.com> URL: https://gitlist.dev/e/20130223144803.GA5444%40padd.com In-Reply-To: <7va9qvc13r.fsf@alter.siamese.dyndns.org> ``` gitster@pobox.com wrote on Fri, 22 Feb 2013 16:42 -0800: > Olivier Delalleau writes: > > > 2013/1/5 Pete Wyckoff : > >> shish@keba.be wrote on Thu, 03 Jan 2013 15:58 -0500: > > ... > >> Please do feel welcome to to rearrange or expand the > >> documentation so it makes more sense, if you are so inspired. > > > > I'm afraid I'm not familiar enough with git documentation to dig into > > it myself, but anyway that's about what I had for now. I'll send more > > comments to the mailing list if I have more suggestions in the future. > > > > Thanks for a great tool! :) > > Did anything come out of this thread? If neither of you two are > inclined to conclude the discussion with a final patch, I'd > appreciate anybody else who does the honors ;-) > > We'll be in deep pre-release freeze for a few weeks, so there is no > need to rush. Two of Olivier's suggestions were best classified as code, not documentation, bugs. I finished off some ongoing work that fixed those along the way. The third led to a fix to the documentation, 182edef (git p4 doc: fix branch detection example, 2013-01-14), that I added as part of that series. All of it is in master now, via 801cbd7 (Merge branch 'pw/p4-branch-fixes', 2013-01-21). I should have commented on this thread too. Thanks for following up! -- Pete ``` ## Junio C Hamano, 2013-02-23 19:11 Subject: Re: Suggested improvements to the git-p4 documentation (branch-related) Message-ID: <7v1uc6977b.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v1uc6977b.fsf%40alter.siamese.dyndns.org In-Reply-To: <20130223144803.GA5444@padd.com> ``` Pete Wyckoff writes: > All of it is in master now, via 801cbd7 (Merge branch > 'pw/p4-branch-fixes', 2013-01-21). > > I should have commented on this thread too. Thanks for following > up! Thanks. ```