From: "Junio C Hamano" <gitster@xxxxxxxxx>
Philip Oakley <philipoakley@xxxxxxx> writes:
Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch
used
'origin' as the upstream branch name. That name is now used as the
nominal
name for the upstream remote.
While 'origin' would be DWIMmed (do what I mean) to be that remote's
primary branch, do not assume the reader is ready for such magic.
Good thinking.
Likewise, do not use 'origin/master' which may not be up to date with
the
remote, nor reflect the reader's master branch. The patch series
should be
relative to the reader's view of 'git show-branch HEAD master'.
This however is backwards, no? The history on 'origin/master' may
not be up-to-date in the sense that if you run 'git fetch' you might
get more, but it absolutely is up-to-date in the sense that it shows
what the origin has to the best of your repository's current
knowledge.
I still think that the user/reader shouldn't be creating patches based
on wherever someone else had got to, rather it should just be patches
from their own feature branch. However the rest of your argument still
stands with regard to accidental/unexpected conflicts with other
upstream work, and the reader should ensure they are already up to
date - maybe it needs a comment line to state that.
Compared to that, what the user's local 'master' has is much less
relevant. For one thing, if a more recent commit that is on the
remote repository is missing on 'origin/master' because you haven't
fetched recently, by definition that commit will not be on your
'master' either, so you have the same staleness issue to the exact
degree. Even worse, when you are developing a topic to upstream, it
is a good practice to merge your topic to your own 'master' to check
it with the wider project codebase that is more recent than where
your topic earlier forked from, and it makes little sense to tell
'exclude what I have on my master' to format-patch when extracting
changes to upstream out of such a topic. You send what the other
side has, not what you do not have on your local 'master' branch.
Use the more modern 'master' as the reference branch name.
There is nothing 'modern' in 'master'.
Noted.
I think the original description was written before we switched to
the separate remote layout. What is in 'refs/remote/origin/master'
these days was stored and updated at 'refs/heads/origin' and no
other branch from the remote repository was tracked back then. The
changes to be upstreamed are output by grabbing what are not in
'origin', whose modern equivalent is 'origin/master'.
In short, if your patch were s|origin|origin/master|, instead of
s|origin|master|, that would be an adjustment to the more modern
world that is still faithful to the intent of the original.
I think we would need to clarify that (the intent) for the reader. I'll
see what I can do. (suggestion below)
Signed-off-by: Philip Oakley <philipoakley@xxxxxxx>
---
Documentation/git-format-patch.txt | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-format-patch.txt
b/Documentation/git-format-patch.txt
index c0fd470..b0f041f 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -523,25 +523,25 @@ $ git format-patch -k --stdout R1..R2 | git
am -3 -k
------------
* Extract all commits which are in the current branch but not in the
-origin branch:
+master branch:
+
------------
-$ git format-patch origin
+$ git format-patch master
------------
+
For each commit a separate file is created in the current directory.
Perhaps insert "Note: Your 'master' should be up to date with respect to
'origin/master' before creating and sending patches upstream to avoid
unexpected conflicts." ?
-* Extract all commits that lead to 'origin' since the inception of
the
+* Extract all commits that lead to 'master' since the inception of
the
project:
+
------------
-$ git format-patch --root origin
+$ git format-patch --root master
------------
* The same as the previous one:
+
------------
-$ git format-patch -M -B origin
+$ git format-patch -M -B master
------------
+
Additionally, it detects and handles renames and complete rewrites
--
Philip
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html