You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildr.apache.org by vb...@apache.org on 2008/04/16 08:21:27 UTC
svn commit: r648544 - /incubator/buildr/trunk/doc/scripts/buildr-git.rb
Author: vborja
Date: Tue Apr 15 23:21:26 2008
New Revision: 648544
URL: http://svn.apache.org/viewvc?rev=648544&view=rev
Log:
Added optparse, use --help to get an overview.
Fixed output to 80 columns
Added more documentation
Added pager from [1]
[1] http://nex-3.com/posts/73-git-style-automatic-paging-in-ruby
Modified:
incubator/buildr/trunk/doc/scripts/buildr-git.rb
Modified: incubator/buildr/trunk/doc/scripts/buildr-git.rb
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/scripts/buildr-git.rb?rev=648544&r1=648543&r2=648544&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/scripts/buildr-git.rb (original)
+++ incubator/buildr/trunk/doc/scripts/buildr-git.rb Tue Apr 15 23:21:26 2008
@@ -1,23 +1,251 @@
+# This script helps buildr developers to obtain their own git clone from
+# github, having a set of pre-defined aliases to work with Apache's SVN.
+#
+# You dont need to have a buildr copy to use it, just execute the buildr-git balloon:
+#
+# ruby -ropen-uri -e 'eval(open("http://balloon.hobix.com/buildr-git").read)'
+
require 'yaml'
+require 'optparse'
+require 'ostruct'
+
+
+# Pager from http://nex-3.com/posts/73-git-style-automatic-paging-in-ruby
+def run_pager
+ return if PLATFORM =~ /win32/
+ return unless STDOUT.tty?
+
+ read, write = IO.pipe
+
+ unless Kernel.fork # Child process
+ STDOUT.reopen(write)
+ STDERR.reopen(write) if STDERR.tty?
+ read.close
+ write.close
+ return
+ end
+
+ # Parent process, become pager
+ STDIN.reopen(read)
+ read.close
+ write.close
+
+ ENV['LESS'] = 'FSRX' # Don't page if the input is short enough
+
+ Kernel.select [STDIN] # Wait until we have input before we start the pager
+ pager = ENV['PAGER'] || 'less'
+ exec pager rescue exec "/bin/sh", "-c", pager
+end
+
+notice = <<NOTICE
+ALIASES:
+
+ Some git aliases have been created for developer convenience:
+
+ git apache-fetch # get changes from apache/trunk without merging them
+ # you can inspect what's happening on trunk without
+ # having to worry about merging conflicts.
+ # Inspect the remote branch with `git log apache/trunk`
+ # Or if you have a git-ui like `tig` you can use that.
+
+ git apache-merge # Merge already fetched changes on the current branch
+ # Use this command to get up to date with trunk changes
+ # you can always cherry-pick from the apache/trunk
+ # branch.
+
+ git apache-pull # get apache-fetch && git apache-merge
+
+ git apache-push # Push to Apache's SVN. Only staged changes (those
+ # recorded using `git commit`) will be sent to SVN.
+ # You need not to be on the master branch.
+ # Actually you can work on a tiny-feature branch and
+ # commit directly from it.
+ #
+ # VERY IMPORTANT:
+ #
+ # Missing commits on Apache's SVN will be sent using
+ # your apache svn account. This means that you can
+ # make some commits on behalf of others (like patches
+ # comming from JIRA issues or casual contributors)
+ # Review the apache-push alias on .git/config if you
+ # want to change login-name used for commit to SVN.
+ #
+ # See the recommended workflow to avoid commiting
+ # other developers' changes and the following section.
+
+THE GITHUB MIRROR:
+
+ Buildr has an unofficial git mirror on github, maintained by Victor:
+
+ http://github.com/vic/buildr
+
+ Actually it's not Victor who manually updates it, he has a cron-job on his
+ server, that only runs
+
+ git synchronize
+
+ A command you also have configured on your .git/config file.
+
+ However there are some limitations due to the fact that git-svn cannot
+ commit as multiple authors (unless all of them provided their passwords
+ to Victor, yet he doesn't want to take over the world.)
+ This means that if a commit is pushed to vic/buildr/master and has not
+ already been pushed by YOU to Apache's SVN by using `git apache-push`
+ your change will be commited to apache/trunk having Victor as the author
+ (that's how he gains meritocratic points at Apache :P).
+
+ So, it's very important - if you care about meritocracy - to follow or at
+ least that you get an idea of the recommended workflow.
+
+RECOMMENDED WORKFLOW:
+
+ So now that you have your local buildr copy you can create topic branches
+ to work on independent features, and still merge easily with head changes.
+
+ They may seem lots of things to consider, but it's all for Buildr's healt.
+ As all things git, you can always follow your own workflow and even create
+ aliases on you .git/config file to avoid typing much. So, here they are:
-local = Dir.pwd if File.directory?(File.join('.git', Dir.pwd))
+ 1) get your buildr-git configured
+ (you have already do so, this was the most difficult part)
-local ||= ARGV.shift || File.expand_path('buildr', File.dirname(__FILE__))
+ 2) create a topic branch to work on, say.. you want to add cool-feature:
+
+ git checkout -b cool-feature master
+ # now on branch cool-feature
+
+ 3) hack hack hack.. use the source luke.
+ every time you feel you have something important like added failing
+ spec, added part of feature, or resolved some conflict from merges,
+ you can commit your current progress. If you want to be selective, use:
+
+ git commit --interactive
+
+ 3) review your changes, get ALL specs passing, repeat step 3 as needed
+
+ 4) let's see what are they doing on trunk
+
+ git apache-fetch
+ # You can inspect the upstream changes without having to merge them
+ git log apache/trunk # what are they doing!!
+
+ 5) integrate mainstream changes to your cool-feature branch, you can always
+ use `git cherry-pick` to select only some commits.
+
+ git merge apache/trunk cool-feature
+
+ 6) Go to 3 unless ALL specs are passing.
+
+ 7.a) (Skip to 7.b you have commit bit on Apache's SVN)
+ Create a patch using `git format-patch`
+ Promote your changes, create a JIRA issue and upload it granting Apache
+ license to include your code:
+
+ https://issues.apache.org/jira/browse/BUILDR
+ buildr-dev@incubator.apache.org
+
+ 7.b) Now you have everyhing on staging area and merged important changes
+ from apache/trunk, it's time to commit them to Apache's SVN.
+
+ git apache-push
+
+ 8) Optional. If you can push to vic/buildr/master mirror, you can just
+ synchronize the mirror helping others to get changes without having to
+ wait on Victor's cronjob to run every hour (useful for urgent changes).
+
+ git synchronize
+
+ 9) Pull changes from origin frequently.
+
+ git fetch origin
+ git rebase --onto origin/master master master
+
+ 10) Unconditionally, Go to step 2 ;)
+ Share your buildr-git workflow, git tips, etc.
+
+RESOURCES:
+
+ http://github.com/vic/buildr/tree/master
+ http://git.or.cz/gitwiki/GitCheatSheet
+ http://groups.google.com/group/git-users/web/git-references
+
+NOTICE
+
+options = OpenStruct.new
+opt = OptionParser.new do |opt|
+
+ if `git status 2>/dev/null`.chomp.empty?
+ options.local = File.expand_path('buildr', Dir.pwd)
+ else
+ puts "Current directory is a git repo: #{Dir.pwd}"
+ options.local = Dir.pwd
+ end
-origin = ARGV.shift || 'git@github.com:vic/buildr.git'
+ options.svn_branch = "apache/trunk"
+ options.origin = "git://github.com/vic/buildr.git"
+ options.member = false
+
+ opt.banner = "Usage: buildr-git.rb [options]"
+ opt.separator ""
+ opt.separator "OPTIONS:"
+
+ opt.on('-a', "--anonymous", "Use git://github.com/vic/buildr.git as origin") do
+ options.origin = "git://github.com/vic/buildr.git"
+ options.member = false
+ end
+ opt.on('-A', "--authenticated", "Use git@github.com:vic/buildr.git as origin") do
+ options.origin = "git@github.com/vic/buildr.git"
+ options.member = true
+ end
+ opt.on("-o", "--origin GIT_URL", "Clone from GIT_URL origin") do |value|
+ options.origin = value
+ end
+ opt.on('-l', "--local DIRECTORY", "Create local git clone on DIRECTORY") do |value|
+ options.local = value
+ end
+ opt.on('-b', "--branch GIT_SVN_BRANCH",
+ "Set the name for the remote branch tracking apache/trunk changes") do |value|
+ options.svn_branch = value
+ end
+ opt.on('-e', "--email EMAIL",
+ "Configure git to use EMAIL for commits") do |value|
+ options.email = value
+ end
+ opt.on('-h', "--help", "Show buildr-git help") do
+ puts opt
+ exit(0)
+ end
+ opt.on('-n', "--notice", "Show notice about aliases and git workflow") do
+ run_pager
+ puts notice
+ exit(0)
+ end
+end
-svn_branch = "apache/trunk"
+opt.parse!(ARGV)
-puts "Buildr official commit channel is Apache's svn repository, however some"
-puts "developers may prefer to use git while working on several features and"
-puts "merging other's changes. "
-puts
-puts "This script will configure a buildr-git copy on so you can commit to svn."
-puts "Local git copy: #{local}"
-puts
-puts "Press RETURN to continue or anything else to abort"
-print "> "
-unless gets.chomp.empty?
+origin = options.origin
+local = options.local
+svn_branch = options.svn_branch
+email = options.email
+
+puts <<HEADER
+
+Buildr official commit channel is Apache's svn repository, however some
+developers may prefer to use git while working on several features and
+merging other's changes.
+
+This script will configure a buildr-git copy on so you can commit to svn.
+Local git copy: #{local}
+
+Press <RETURN> to continue, <-h> to see options, <-n> to see the
+comments on configured aliases and git workflow.
+Ctrl+D or write anything else to abort
+HEADER
+print '> '
+input = gets
+opt.parse! [input.chomp] if input
+unless input && input.chomp.empty?
puts "Aborting."
exit(0)
end
@@ -27,7 +255,7 @@
Dir.chdir(local) do
# Load the list of git-svn committers
- svn_authors_file = File.expand_path('etc/git-svn-authors', local)
+ svn_authors_file = File.expand_path('etc/git-svn-authors', Dir.pwd)
svn_authors = File.read(svn_authors_file)
svn_authors.gsub!(/\s+=\s+/, ': ')
svn_authors = YAML.load(svn_authors)
@@ -37,7 +265,7 @@
`git config svn.authorsfile "#{svn_authors_file}"`
# Check that git is configured for the git developer
- email = `git config --get user.email`.chomp
+ email ||= `git config --get user.email`.chomp
if email.empty?
puts "Enter your email as listed on #{svn_authors_file}"
print "> "
@@ -53,8 +281,15 @@
else
fail "Invalid contact string for #{svn_user}: #{git_contact.inspect}"
end
+
+ # Start the pager
+ run_pager
+
# Configure user name and email for git sake (and github's gravatar)
- puts "You claim to be #{user_name} <#{user_email}> with apache-svn user: #{svn_user}"
+ puts
+ puts "You claim to be #{user_name} <#{user_email}> with apache-svn user"
+ puts " #{svn_user}"
+ puts
`git config user.name "#{user_name}"`
`git config user.email "#{user_email}"`
@@ -85,111 +320,13 @@
`git config alias.synchronize "!git get && git mrg && git put"`
# Final notices.
- notice = <<-NOTICE
- Your git repo #{local} has been configured, please review the .git/config file.
-
- ALIASES:
-
- Some git aliases have been created for developer's convenience:
-
- git apache-fetch # get changes from apache/trunk without merging them
- # you can inspect what's happening on trunk without
- # having to worry about merging conflicts.
- # Inspect the remote branch with `git log apache/trunk`
- # Or if you have a git-ui like `tig` you can use that.
-
- git apache-merge # Merge already fetched changes on the current branch
- # Use this command to get up to date with trunk changes
- # you can always cherry-pick from the apache/trunk branch.
-
- git apache-pull # get apache-fetch && git apache-merge
-
- git apache-push # Push to Apache's SVN. Only staged changed (commited patches)
- # will be sent to SVN. You need not to be on the master branch.
- # Actually you can work on a tiny-feature branch and commit
- # directly from it.
- #
- # VERY IMPORTANT:
- # Missing commits on Apache's SVN will be sent using
- # your #{svn_user} svn account. This means that you can make
- # some commits on behalf of others (like user-contributed patches
- # from JIRA). Review the .git/config if you want to change login-name.
- #
- # See the recommended workflow to avoid commiting other developers' changes,
- # and the notes on github mirror.
-
- THE GITHUB MIRROR:
-
- Buildr has an unofficial git mirror on github, maintained by Victor: http://github.com/vic/buildr
- Actually it's not Victor who manually updates it, he has a cron-job on his server, that only runs
- git synchronize
- A command you also have configured on your .git/config file.
-
- However there are some limitations due that git-svn cannot commit as multiple authors (unless all
- of them provided their passwords to Victor, yet he doesn't want to take over the world.)
- This means that if a commit "A" is pushed to vic/buildr/master and has not already been pushed
- by #{svn_user} using `git apache-push` your change will be commited to apache/trunk having Victor as the
- author (that's how he gains meritocratic points on Apache :P).
-
- So, it's very important - if you care about meritocracy - to follow or at least that you get an
- idea of the recommended workflow.
-
- RECOMMENDED WORKFLOW:
-
- So now that you have your local buildr copy you can create topic branches to work on
- independent features, and still merge easily with head changes.
-
- They may seem lots of things to consider, but it's all for Buildr's healt. As all things git,
- you can always follow your own workflow and even create aliases on you .git/config file to
- avoid typing much. So, here here they are:
-
- 1) get your buildr-git configured (you have already do so, this was the most difficult part)
-
- 2) create a topic branch to work on, say.. you want to add cool-feature:
-
- git checkout -b cool-feature master
- # now on branch cool-feature
-
- 3) hack hack hack.. use the source luke.
- every time you feel you have something important (added failing spec, added part of feature)
- you can commit your changes. If you want to be selective, use: git commit --interactive
-
- 3) review your changes, get ALL specs passing, repeat step 3 as needed
-
- 4) let's see what are they doing on trunk
-
- git apache-fetch
- # You can inspect the upstream changes without having to merge them
- git log apache/trunk # what are they doing!!
-
- 5) integrate mainstream changes to your cool-feature branch (you can always use cherry-pick)
+ notice = <<-NOTICE + notice
- git merge apache/trunk cool-feature
-
- 6) Go to 3 unless ALL specs are passing.
-
- 7) Now you have everyhing on stage area (git commit) and merged important changes from
- apache/trunk. It's time to commit them to Apache's SVN.
-
- git apache-push
-
- 8) (Optional)
- Now your changes are on Apache SVN, you can wait for them to get synched to vic/buildr/master
- or push them yourself. You need Victor to add you as member, just ask for it.
-
- git fetch origin
- git rebase --into origin/master master
- git push origin master:master
-
- 9) Pull changes from origin frequently.
-
- git fetch origin
- git rebase --onto origin/master master master
-
- 10) Unconditionally, Go to step 2 ;) or share your buildr-git workflow, tips, etc.
+ Your git repo #{local} has been configured, please review the
+ #{File.join(local, '.git/config')} file.
NOTICE
-
- puts notice
+ puts notice
+
end