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

[karthik nayak <karthik.188@gmail.com>]

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