{"thread":{"id":"38890","subject":"[RFC/GSoC] Proposal Draft: Unifying git branch -l, git tag -l, and git for-each-ref","startedAt":"2015-03-23T13:09:20Z","lastAt":"2015-03-28T18:44:58Z","messageCount":3,"participants":["karthik nayak","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"258360","messageId":"55101080.90805@gmail.com","threadId":"38890","inReplyTo":null,"subject":"[RFC/GSoC] Proposal Draft: Unifying git branch -l, git tag -l, and git for-each-ref","fromName":"karthik nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2015-03-23T13:09:20Z","receivedAt":"2015-03-23T13:09:20Z","isPatch":false,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Hello,\nI have completed the micro project[1] and have also been working on \nadding a \"--literally\" option\nfor cat-file[2]. I have left out the personal information part of the \nproposal here, will fill that in while submitting my final proposal.\n\nCurrently, I have been reading about how \"branch -l\", “tag -l” and \n“for-each-refs” work and how they implement the selection and formatting \noptions.\n\nSince this is a draft for my final proposal I would love to hear from \nyou all about :\n\n* Suggestions on my take of this idea and how I could improve it or \nmodify it.\n* Anything more I might have missed out on, in the proposal.\n\nGSOC Proposal : Unifying git branch -l, git tag -l, and git for-each-ref\n----------------------------------------------------------------------------------------------------------------------------------------\n# Main objectives of the project:\n\n* Build a common library for which can handle both selection and \nformatting of refs.\n\n* Use this library throughout ‘branch -l’, ‘tag -l’ and ‘for-each-ref’.\n\n* Implement options available in some of these commands onto others.\n\n----------------------------------------------------------------------------------------------------------------------------------------\n\n# Amongst  ‘branch -l’, ‘tag -l’ and ‘for-each-ref’ :\n\n* ‘git branch -l’ and ‘git tag -l’ share  the ‘--contains’ option.\n\n* 'git tag' and 'git branch' could use a formatting option (This could \nalso be used to implement the verbose options)\n\tFor eg: git branch -v could be implemented using :\n\tgit for-each-ref refs/heads --format='%(refname:short) \n%(objectname:short) %(upstream:track) %(contents:subject)'\n\tThis shows that having a formatting option for these two would mean \nthat the verbose options could be implemented using the formatting \noption itself.\n\n  * 'git for-each-refs' could use all the selection options. This would \nenhance the uses of for-each-refs itself. Users can then view only refs \nbased on what they may be looking for.\n\n* formatting options for ‘git branch -l’ and ‘git tag -l’. This would \nenable the user to view information as per the users requirements and \nformat.\n\n----------------------------------------------------------------------------------------------------------------------------------------\n# Approach\n\nAll three commands select a subset of the repository’s refs and print \nthe result. There has been an attempt to unify these commands by Jeff \nKing[3]. I plan on continuing his work[4] and using his approach to \ntackle this project.\n\nAs per the common library for ‘branch -l’, ‘tag -l’ and ‘for-each-ref’ I \nplan on creating a file (mostly as ref-filter.c in terms with what Jeff \nhas already done) which will provide API’s to add refs to get a list of \nall refs. This will be used along with ‘for_each_*_ref’ for obtaining \nthe refs required. This gives us the basic functionality of obtaining \nthe refs required by the command.\n\nHere we could have a basic data structure (struct ref_filter_item) which \nwould denote a particular ref and have another data structure to hold a \nlist of these refs (struct ref_filter). Then after getting the required \nrefs, we could print the information.\n\nFor extended selection behaviour such as ‘--contains’ or ‘--merged’ we \ncould implement these within\nthe library by providing functions which closely mimic the current \nmethods used individually by ‘branch -l’ and ‘tag -l’. For eg to \nimplement ‘--merged’ we implement a ‘compute_merge()’ function, which \nwith the help of the revision API’s will be able to perform the same \nfunction as ‘branch -l --merged’.\n\nFor formatting functionality provided by ‘for-each-ref’ we replicate the \n‘show_ref’ function in ‘for-each-ref.c’ where the format is given to the \nfunction and the function uses the format to obtain atom values and \nprints the corresponding atom values to the screen. This feature would \nallow us to provide format functionality which could act as a base for \nthe ‘-v’ option also.\n\nAs Jeff has already done, we could also add parse options. Although Jeff \nhas built a really good base to build upon, I shall use his work as more \nof a reference and work on unification of the three commands from \nscratch. I plan on coding for this project using a test driven \ndevelopment, where I will write tests (initially failing) which will be \nbased on the objectives of the project and then write code to pass those \ntests.\n\n----------------------------------------------------------------------------------------------------------------------------------------\n\n# Timeline\n\nThis is a rough plan of how I will spend the summer working on this project.\n\nCommunity bonding period:\n\tWork on understanding how all three commands work in total detail. And \nbuild up on the design of unification of the three commands. Read \nthrough Jeff’s attempt at unification and get a grasp of what to do.\n\nWeek 1 :\n\tWrite tests and documentation which will the goal of this project. This \nwill set the deliverables of the project and what the code will try to \nachieve in the project.\n\nWeek 2 :\n\tBuild a basic library which will function to get the required refs.\n\nWeek 3 :\n\tSince ‘tag -l’ has the least options to be satisfied initially, modify \n‘tag -l’ to use the newly created library.\n\nWeek 4 - 5 :\n\tImplement ‘--merged’ and other selection options to the library.\n\nWeek 6 :\n\tModify ‘branch -l’ to use the library created as this can be done \nwithout implementing the ‘--format’ options.\n\nWeek 7 :\n\tImplement ‘--format’ options in the library, by using the \nimplementation used by ‘for-each-ref’ as a reference.\n\nWeek 8 :\n\tModify ‘for-each-ref’ to use the library.\n\nWeek 9 - 10 :\n\tModify all three commands to include most of the selection and \nformatting options.\n\nWeek 11 - 12 :\n\tPolishing of code.\n\tWrite more tests and Documentation as and if required.\n\tResolve any issues, if generated.\n\nReferences :\n[1] http://thread.gmane.org/gmane.comp.version-control.git/264911\n[2] http://article.gmane.org/gmane.comp.version-control.git/265604\n[3] http://thread.gmane.org/gmane.comp.version-control.git/230694/focus=2308\n[4] https://github.com/peff/git/commits/jk/for-each-ref-contains-wip\n"},{"id":"258556","messageId":"20150326163748.GF6564@peff.net","threadId":"38890","inReplyTo":"55101080.90805@gmail.com","subject":"Re: [RFC/GSoC] Proposal Draft: Unifying git branch -l, git tag -l, and git for-each-ref","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-03-26T16:37:49Z","receivedAt":"2015-03-26T16:37:49Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Mar 23, 2015 at 06:39:20PM +0530, karthik nayak wrote:\n\n> All three commands select a subset of the repository’s refs and print the\n> result. There has been an attempt to unify these commands by Jeff King[3]. I\n> plan on continuing his work[4] and using his approach to tackle this\n> project.\n\nI would be cautious about the work in my for-each-ref-contains-wip\nbranch. At one point it was reasonably solid, but it's now a year and a\nhalf old, and I've been rebasing it without paying _too_ much attention\nto correctness. I think some subtle bugs have been introduced as it has\nbeen carried forward.\n\nAlso, the very first patch (factoring out the contains traversal) is\nprobably better served by this series:\n\n  http://thread.gmane.org/gmane.comp.version-control.git/252472\n\nI don't remember all of the issues offhand that need to be addressed in\nit, but there were plenty of review comments.\n\n> For extended selection behaviour such as ‘--contains’ or ‘--merged’ we could\n> implement these within\n> the library by providing functions which closely mimic the current methods\n> used individually by ‘branch -l’ and ‘tag -l’. For eg to implement\n> ‘--merged’ we implement a ‘compute_merge()’ function, which with the help of\n> the revision API’s will be able to perform the same function as ‘branch -l\n> --merged’.\n\nOne trick with making a library-like interface is that some of the\nselection routines can work on a \"streaming\" list of refs (i.e., as we\nsee each ref we can say \"yes\" or \"no\") and some must wait until the end\n(e.g., --merged does a single big merge traversal). It's probably not\nthe end of the world to just always collect all the refs, then filter\nthem, then sort them, then print them. It may delay the start of output\nin some minor cases, but I doubt that's a big deal (and anyway, the\npacked-refs code will load them all into an array anyway, so collecting\nthem in a second array is probably not a big deal).\n\n> For formatting functionality provided by ‘for-each-ref’ we replicate the\n> ‘show_ref’ function in ‘for-each-ref.c’ where the format is given to the\n> function and the function uses the format to obtain atom values and prints\n> the corresponding atom values to the screen. This feature would allow us to\n> provide format functionality which could act as a base for the ‘-v’ option\n> also.\n\nYeah, I'd really like to see \"--format\" for \"git branch\", and have \"-v\"\njust feed that a hard-coded format string (or even a configurable one).\n\n> Although Jeff has built a really good base to build upon, I shall use\n> his work as more of a reference and work on unification of the three\n> commands from scratch.\n\nGood. :)\n\n-Peff\n"},{"id":"258639","messageId":"5516F6AA.50103@gmail.com","threadId":"38890","inReplyTo":"20150326163748.GF6564@peff.net","subject":"Re: [RFC/GSoC] Proposal Draft: Unifying git branch -l, git tag -l, and git for-each-ref","fromName":"karthik nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2015-03-28T18:44:58Z","receivedAt":"2015-03-28T18:44:58Z","isPatch":false,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"\nOn 03/26/2015 10:07 PM, Jeff King wrote:\n> On Mon, Mar 23, 2015 at 06:39:20PM +0530, karthik nayak wrote:\n>\n> > All three commands select a subset of the repository’s refs and print the\n> > result. There has been an attempt to unify these commands by Jeff King[3]. I\n> > plan on continuing his work[4] and using his approach to tackle this\n> > project.\n>\n> I would be cautious about the work in my for-each-ref-contains-wip\n> branch. At one point it was reasonably solid, but it's now a year and a\n> half old, and I've been rebasing it without paying _too_ much attention\n> to correctness. I think some subtle bugs have been introduced as it has\n> been carried forward.\n>\n> Also, the very first patch (factoring out the contains traversal) is\n> probably better served by this series:\n>\n>    http://thread.gmane.org/gmane.comp.version-control.git/252472\n>\n> I don't remember all of the issues offhand that need to be addressed in\n> it, but there were plenty of review comments.\nThanks for the link, will go through that.\n>\n> > For extended selection behaviour such as ‘--contains’ or ‘--merged’ we could\n> > implement these within\n> > the library by providing functions which closely mimic the current methods\n> > used individually by ‘branch -l’ and ‘tag -l’. For eg to implement\n> > ‘--merged’ we implement a ‘compute_merge()’ function, which with the help of\n> > the revision API’s will be able to perform the same function as ‘branch -l\n> > --merged’.\n>\n> One trick with making a library-like interface is that some of the\n> selection routines can work on a \"streaming\" list of refs (i.e., as we\n> see each ref we can say \"yes\" or \"no\") and some must wait until the end\n> (e.g., --merged does a single big merge traversal). It's probably not\n> the end of the world to just always collect all the refs, then filter\n> them, then sort them, then print them. It may delay the start of output\n> in some minor cases, but I doubt that's a big deal (and anyway, the\n> packed-refs code will load them all into an array anyway, so collecting\n> them in a second array is probably not a big deal).\nI think I noted this down while going through your implementation also.\nYou even mentioned this on the mailing list if I'm not wrong.\nWill have to work out a design around this and think about it more.\n>\n> > For formatting functionality provided by ‘for-each-ref’ we replicate the\n> > ‘show_ref’ function in ‘for-each-ref.c’ where the format is given to the\n> > function and the function uses the format to obtain atom values and prints\n> > the corresponding atom values to the screen. This feature would allow us to\n> > provide format functionality which could act as a base for the ‘-v’ option\n> > also.\n>\n> Yeah, I'd really like to see \"--format\" for \"git branch\", and have \"-v\"\n> just feed that a hard-coded format string (or even a configurable one).\n>\n> > Although Jeff has built a really good base to build upon, I shall use\n> > his work as more of a reference and work on unification of the three\n> > commands from scratch.\n>\n> Good. :)\n>\n> -Peff\n>\nThanks for the Review/Tips.\n\nRegards\n-Karthik\n"}]}