Re: Suggested improvements to the git-p4 documentation (branch-related)

From: Pete Wyckoff <pw@padd.com>
Date: Jan 5, 2013, 21:25 UTC
Message-ID: <20130105212517.GA30315@padd.com>
In-Reply-To: <CAFXk4bqt_pMVDtVKF-JiQuGbSpy2+_rGOg5RTTE+0pNKFcZh3w@mail.gmail.com>

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.

Show 10 quoted lines

> 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 .

Show 6 quoted lines

> 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.

Show 10 quoted lines

> 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