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 + [EMAIL PROTECTED] + + 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 || '[EMAIL PROTECTED]: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 [EMAIL PROTECTED]:vic/buildr.git as origin") do + options.origin = "[EMAIL PROTECTED]/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
