Skip to content
This repository

Humbly suggesting improvements to workflow document #166

Open
wants to merge 1 commit into from

3 participants

Junio C Hamano Duke Leto Alvis Yardley
Junio C Hamano

This is not really a patch, but more of a "code review" in the form of additional in-line comments
to the documentation.

Junio C Hamano Humbly suggesting improvements to workflow document
This is not really a patch, but more of a "code review" in the form of additional in-line comments
to the documentation.
27a9f10
Duke Leto
Owner

Thank you for these humble suggestions, @gitster. Still brooding on them, but you have definitely pointed out some issues that need fixing.

Alvis Yardley
Collaborator

@leto, are you still brooding on these suggestions? Or can we close this as ... well, something we're not gonna do?
Thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 1 unique commit by 1 author.

Sep 15, 2011
Junio C Hamano Humbly suggesting improvements to workflow document
This is not really a patch, but more of a "code review" in the form of additional in-line comments
to the documentation.
27a9f10
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 39 additions and 4 deletions. Show diff stats Hide diff stats

  1. 43  docs/project/git_workflow.pod
43  docs/project/git_workflow.pod
Source Rendered
@@ -101,6 +101,10 @@ To get the latest updates:
101 101
 
102 102
 This copies the index from your default remote (origin) and saves it to your
103 103
 local index. This does not effect your working copy, so it doesn't matter
  104
+# Using the word "index" here is confusing to people who know Git terminology, as
  105
+# git fetch never touches any "index". The operation fetches the contents of the
  106
+# branches from the remote (in this case, "origin"), and remembers the tips of
  107
+# these remote branches so that you can later refer them as "origin/user/branch"
104 108
 what branch you are on when you run this command. To sync up your working
105 109
 copy, you can use C<git rebase>
106 110
 
@@ -114,7 +118,10 @@ This is a common action, so there is also a simpler way to do it:
114 118
 Whenever you don't specify a remote or branch to a git command, they default
115 119
 to the remote called "origin" and the master branch, so the previous command
116 120
 means exactly the same as:
117  
-
  121
+# Not really. Especially because you are encouraging people to use -t origin/user/branch
  122
+# when your developers fork their work off of others' work, "pull --rebase" run while on
  123
+# user/branch most likely to mean "git pull --rebase origin origin/user/branch", which is
  124
+# more desirable thing to happen than "git pull --rebase origin master".
118 125
   git pull --rebase origin master
119 126
 
120 127
 This is important to note when you are working with remotes other than origin,
@@ -179,7 +186,10 @@ a good idea.
179 186
 =head2 Maintaining a Branch
180 187
 
181 188
 To update your local git index from origin:
182  
-
  189
+# Again, "index" is confusing here. It is updating the local copy you keep to
  190
+# remember which commits the "origin" repository had at tips of its branches
  191
+# when you last updated the record by running "git fetch". They are called
  192
+# "remote tracking branches".
183 193
     git fetch
184 194
 
185 195
 If you are following multiple remotes, you can fetch updates from all of them
@@ -418,7 +428,7 @@ Then you will follow this procedure:
418 428
 
419 429
     # 4) let's make a patch of the difference between this branch and master
420 430
     git format-patch master --stdout > foo.patch
421  
-
  431
+# "foo.patch" does not match the following description. Should read "gci.patch", I think.
422 432
     # 5) Switch back to the master branch
423 433
     git checkout master
424 434
 
@@ -446,7 +456,32 @@ of C<git log> and finding the most recent SHA1 before your
446 456
 branch, then doing:
447 457
 
448 458
     git reset --hard $sha1
449  
-
  459
+# This is a workflow suggestion, but because you are requiring your
  460
+# developers to merge with --no-ff to _always_ create a merge commit,
  461
+# you can avoid the above complexity and risk of confusion coming from
  462
+# reset by instead requiring your trusted developers to sign off these
  463
+# merges. I.e. this procedure
  464
+# 1. git checkout -b someguy-newbranch master
  465
+# 2. git pull --no-ff https://github.com/someguy/parrot.git newbranch
  466
+# 3. EDITOR=: git commit --amend -s
  467
+# will create a merge commit that is signed by the person who is responding
  468
+# to a pull request (if the step 2 fails in conflict, conclude the merge
  469
+# resolution with "git commit -s" instead and you can omit the third step).
  470
+# When auditing the overall project history, use "git log --first-parent"
  471
+# to traverse the mainline of the history, and any and all merges you would
  472
+# find would be a merge from a side branch. For such a merge commit $M,
  473
+# git log $M^1..$M would give you the commits the merge brought into the
  474
+# history from the side branch (they may not be signed off by the authorized
  475
+# "committers") but a sign-off on the merge commit $M already indicates that
  476
+# the person who responded to the pull-request VOUCHES FOR all these commits
  477
+# from the side branch, and no auditing trail is lost.
  478
+# Again, the above is a workflow suggestion, and it may go against the
  479
+# project policy of having sign-off by authorized "committers" on ALL commits;
  480
+# I am just pointing out that the project may realize that such a policy is
  481
+# suboptimal, if it reconsiders what the policy tries to achieve.
  482
+# By loosening the policy the way I outlined above, you do not have to worry
  483
+# about changing the SHA-1 of the third-party commits, hence you do not have
  484
+# to worry about using "git reset".
450 485
 Be careful with C<git reset>! Make sure there are no untracked
451 486
 files that you care about BEFORE YOUR RUN C<git reset>.
452 487
 
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.