[RFC/GSoC] Proposal Draft: Unifying git branch -l, git tag -l, and git for-each-ref

Hello, I have completed the micro project[1] and have also been working on adding a "--literally" option for cat-file[2]. I have left out the personal information part of the proposal here, will fill that in while submitting my final proposal.

Currently, I have been reading about how "branch -l", “tag -l” and “for-each-refs” work and how they implement the selection and formatting options.

Since this is a draft for my final proposal I would love to hear from you all about :

* Suggestions on my take of this idea and how I could improve it or 
modify it.
* Anything more I might have missed out on, in the proposal.

GSOC Proposal : Unifying git branch -l, git tag -l, and git for-each-ref ---------------------------------------------------------------------------------------------------------------------------------------- # Main objectives of the project:

* Build a common library for which can handle both selection and 
formatting of refs.

* Use this library throughout ‘branch -l’, ‘tag -l’ and ‘for-each-ref’.

* Implement options available in some of these commands onto others.

----------------------------------------------------------------------------------------------------------------------------------------

# Amongst  ‘branch -l’, ‘tag -l’ and ‘for-each-ref’ :

* ‘git branch -l’ and ‘git tag -l’ share  the ‘--contains’ option.

* 'git tag' and 'git branch' could use a formatting option (This could 
also be used to implement the verbose options)
	For eg: git branch -v could be implemented using :
	git for-each-ref refs/heads --format='%(refname:short) 
%(objectname:short) %(upstream:track) %(contents:subject)'
	This shows that having a formatting option for these two would mean 
that the verbose options could be implemented using the formatting 
option itself.

  * 'git for-each-refs' could use all the selection options. This would 
enhance the uses of for-each-refs itself. Users can then view only refs 
based on what they may be looking for.

* formatting options for ‘git branch -l’ and ‘git tag -l’. This would 
enable the user to view information as per the users requirements and 
format.

---------------------------------------------------------------------------------------------------------------------------------------- # Approach

All three commands select a subset of the repository’s refs and print the result. There has been an attempt to unify these commands by Jeff King[3]. I plan on continuing his work[4] and using his approach to tackle this project.

As per the common library for ‘branch -l’, ‘tag -l’ and ‘for-each-ref’ I plan on creating a file (mostly as ref-filter.c in terms with what Jeff has already done) which will provide API’s to add refs to get a list of all refs. This will be used along with ‘for_each_*_ref’ for obtaining the refs required. This gives us the basic functionality of obtaining the refs required by the command.

Here we could have a basic data structure (struct ref_filter_item) which would denote a particular ref and have another data structure to hold a list of these refs (struct ref_filter). Then after getting the required refs, we could print the information.

For extended selection behaviour such as ‘--contains’ or ‘--merged’ we could implement these within the library by providing functions which closely mimic the current methods used individually by ‘branch -l’ and ‘tag -l’. For eg to implement ‘--merged’ we implement a ‘compute_merge()’ function, which with the help of the revision API’s will be able to perform the same function as ‘branch -l --merged’.

For formatting functionality provided by ‘for-each-ref’ we replicate the ‘show_ref’ function in ‘for-each-ref.c’ where the format is given to the function and the function uses the format to obtain atom values and prints the corresponding atom values to the screen. This feature would allow us to provide format functionality which could act as a base for the ‘-v’ option also.

As Jeff has already done, we could also add parse options. Although Jeff has built a really good base to build upon, I shall use his work as more of a reference and work on unification of the three commands from scratch. I plan on coding for this project using a test driven development, where I will write tests (initially failing) which will be based on the objectives of the project and then write code to pass those tests.

----------------------------------------------------------------------------------------------------------------------------------------

# Timeline

This is a rough plan of how I will spend the summer working on this project.

Community bonding period:
	Work on understanding how all three commands work in total detail. And 
build up on the design of unification of the three commands. Read 
through Jeff’s attempt at unification and get a grasp of what to do.

Week 1 :
	Write tests and documentation which will the goal of this project. This 
will set the deliverables of the project and what the code will try to 
achieve in the project.

Week 2 :
	Build a basic library which will function to get the required refs.

Week 3 :
	Since ‘tag -l’ has the least options to be satisfied initially, modify 
‘tag -l’ to use the newly created library.

Week 4 - 5 :
	Implement ‘--merged’ and other selection options to the library.

Week 6 :
	Modify ‘branch -l’ to use the library created as this can be done 
without implementing the ‘--format’ options.

Week 7 :
	Implement ‘--format’ options in the library, by using the 
implementation used by ‘for-each-ref’ as a reference.

Week 8 :
	Modify ‘for-each-ref’ to use the library.

Week 9 - 10 :
	Modify all three commands to include most of the selection and 
formatting options.

Week 11 - 12 :
	Polishing of code.
	Write more tests and Documentation as and if required.
	Resolve any issues, if generated.

References : [1] http://thread.gmane.org/gmane.comp.version-control.git/264911 [2] http://article.gmane.org/gmane.comp.version-control.git/265604 [3] http://thread.gmane.org/gmane.comp.version-control.git/230694/focus=2308 [4] https://github.com/peff/git/commits/jk/for-each-ref-contains-wip