karthik nayakHello, 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
