{"thread":{"id":"66807","subject":"[Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed","startedAt":"2026-11-09T05:21:36Z","lastAt":"2026-11-17T18:49:12Z","messageCount":5,"participants":["Fien Dora","Richard Kerry","Junio C Hamano","Okhuomon Ajayi"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"557872","messageId":"CACWAS-UqbkgfzsJ2283=OgoUHRs-FeRNYc0zkBR2y0XD4jTWsw@mail.gmail.com","threadId":"66807","inReplyTo":null,"subject":"[Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed","fromName":"Fien Dora","fromEmail":"fiendora5@gmail.com","sentAt":"2026-11-09T05:21:36Z","receivedAt":"2026-11-09T05:21:36Z","isPatch":false,"sender":{"key":"fiendora5@gmail.com","avatar":null},"body":"Applicant: Fien Dora\nCommunity: Git\nProject: Improve how command arguments and options are scanned and parsed\nMentors: Christian Couder and Siddharth Asthana\nInternship period: December 7, 2026 – March 8, 2027\n1. About Me\nHello everyone,\nI'm Fien Dora, a Computer Engineer with an interest in C programming,\nsystems programming, and understanding how things work in the\nbackground.\nI've always enjoyed mathematics and solving problems. I’ve always been\ncurious about compilers, and what happens when a command is sent. That\ncuriosity pushed me to start learning programming. In 2023, I joined\nthe ALX learning program, where I was introduced to C, shell\nscripting, and systems programming. Of everything I was learning, C\ncaught my attention the most.\nI liked that C helped me understand what was happening closer to the\ncomputer itself like compilers, interpreters, memory, and how software\ncommunicates with hardware.\nI am still growing as a C programmer, especially when it comes to\nunderstanding large codebases, but I enjoy taking time to understand a\nproblem and working through it until things become clearer.\nThat is one of the reasons I was drawn to Git's Outreachy project.\nAvailability: 30 hours per week from 7 December 2026 to 8 March 2027.\n2. Why Git and Outreachy?\nTo me, Git is the reason behind successful software development. I\nusually use Git mainly as a tool for tracking changes or versions,\nworking with branches, and collaborating with other developers.\nThe project on argument-parsing was particularly interesting to me\nbecause It combines my interest in C and systems programming with the\nopportunity to understand and improve software that many developers\ndepend on.\nAnother thing I have come to appreciate about Git is its community.\nDuring this contribution period, it was very strange to me that the\ngit community was a mailing list but I discovered how much attention\nGit contributors give to reviewing changes. Reviewers do not simply\ntell you that something is wrong. They explain why it is a problem and\nsuggest a better way to approach it, which was very amazing.\nI experienced this during my first contribution, when Junio reviewed\nmy patch and pointed out weaknesses in how I explained its purpose.\nHis feedback helped me understand that a patch should not only work;\nit should also have a clear reason for existing.\nI also learned Git's mailing-list conventions through that process.\nI value this experience as I learn from experienced developers while\ncontributing to a real project, rather than learning programming\nconcepts only through exercises.\nI have also been encouraged by previous Outreachy interns who have\ncontributed to Git's internal code and testing infrastructure. Their\nexperiences show that meaningful contributions can begin with small,\ncarefully understood changes.\nI look forward to this internship to help me become more confident\nworking with C and participating in open-source development.\nMost importantly, I want to continue contributing to open source after\nOutreachy.\n3. My Git Contributions and What I Have Learned\n3.1 My first contribution: git check-ref-format\nPatch: t1402: test --no-allow-onelevel option precedence\nDiscussion: https://lore.kernel.org/git/20261029121715.3845-1-fiendora5@gmail.com/\nCommit: 0110f33aa8\nStatus: Queued by Junio and integrated into Git's next branch during\nthe contribution period.\nFor my microproject, I worked on the tests for git check-ref-format.\nWhile reading its code, I learned that it uses a manually written loop\nto handle some command-line options instead of the shared\nparse_options() API.\nI focused on two options: --allow-onelevel and --no-allow-onelevel.\nThese options determine whether Git accepts a refname containing only\none component. When both options are supplied, the last one determines\nthe result.\nI added two tests to t/t1402-check-ref-format.sh to protect that\nbehavior in both argument orders.\nThe code change itself was small, but getting the patch ready for\nreview taught me a lot.\nMy first commit message explained what the tests did, but Junio\npointed out that it did not sufficiently explain why those tests were\nuseful.\nHe helped me see that check-ref-format was worth testing specifically\nbecause it used a handcrafted parser and its behavior could matter\nduring future parsing changes.\nIn another review, he questioned a statement I made about a planned\nconversion. I had described possible future work as though it had\nalready been decided.\nThat was an important lesson: I should distinguish between something\nthat already exists, something another contributor is doing, and\nsomething I am only proposing.\nI revised the patch explanation, and the contribution went through\nthree versions.\nJunio eventually replied that the changes were well explained and\nwould be queued.\nI also learned about Git's email conventions, including replying below\nrelevant quoted text and keeping quotes short enough for others to\nfollow a discussion.\nLooking back, the most valuable part of this contribution was not just\nhaving a patch accepted. It was learning how to explain my reasoning,\nrespond to feedback, and improve my work through review.\n3. My Git Contribution Experience\n3.1 First microproject: Testing option precedence in git check-ref-format\nPatch: t1402: test --no-allow-onelevel option precedence\nMailing-list discussion:\nhttps://lore.kernel.org/git/20261029121715.3845-1-fiendora5@gmail.com/\nCommit: 0110f33aa8\nMy first contribution involved investigating the behavior of two\nconflicting options in git check-ref-format:\n• --allow-onelevel\n• --no-allow-onelevel\nThese options control whether a refname with only one component is accepted.\nI examined the existing implementation and test coverage and added two\nregression tests to t/t1402-check-ref-format.sh.\nThe tests verify that when both options are supplied, the last one\ndetermines the effective behavior, regardless of their order.\nAfter building Git locally and running the relevant tests, I submitted\nthe signed-off patch to the Git mailing list.\nThe contribution went through three versions following feedback from\nJunio C Hamano.\nOne of the most important things I learned was that a patch should\nexplain not only what a change does, but also why the change is\nuseful.\nJunio's feedback helped me recognize weaknesses in my initial\nexplanation, particularly where I made assumptions about possible\nfuture parser changes.\nI revised the commit message to explain the reason for protecting the\nexisting behavior more accurately.\nAfter reviewing the revised patch, Junio indicated that it was well\nexplained and would be queued. The contribution subsequently reached\nGit's next integration branch.\nThe review process was especially valuable to me. It showed me how\nmuch thought goes into even a small contribution and encouraged me to\nbecome more careful with technical explanations, assumptions, and\ntests.\n3.2 Independent testing of another contributor's check-ref-format conversion\nAfter my first contribution, I intended for a follow up contribution\nof git check-ref-format conversion and how it behaves when its manual\nargument parsing were replaced with Git's shared parse_options() API.\nI studied a conversion proposed by fellow contributor Hussain Sitamouwala.\nI checked out the proposed changes locally, built Git, and ran the\nrelevant test suites.\nIn that testing environment:\n• All 107 tests in t1402-check-ref-format.sh passed.\n• All 96 tests in t0040-parse-options.sh passed.\nI also manually tested cases involving option precedence, repeated\noptions, abbreviated names, unsupported option forms, and the --\nseparator.\nI did not identify unexpected regressions in the cases tested.\nThis was an independent testing exercise, not a patch I authored or a\nformal review submitted to the mailing list.\nIt helped me understand that changing a command's parser requires\nexamining more than its normal use cases. Even when existing\nfunctionality continues working, a new parser may recognize additional\nargument forms or produce different errors.\nThis reinforced the importance of understanding existing behavior\nbefore implementing a conversion.\n3.3 Studying early_scan_options() and git fast-import\nI also studied Christian Couder's early_scan_options() series and\nexamined how the API is used in fast-import.\nThis helped me understand why certain commands need to inspect\nparticular options before normal argument parsing begins.\nI learned about PARSE_OPT_EARLY and how early scanning can help\ncommands process options that influence configuration or\ninitialization.\nStudying this implementation led me to investigate another possible\nuse of the API.\n3.4 Investigating git column\nWhile examining other built-in commands, I noticed that\nbuiltin/column.c manually checks for --command= before invoking\nparse_options().\nI studied the implementation and tested several argument forms,\nincluding attached values, separate values, abbreviated option names,\noption ordering, and repeated options.\nThe investigation raised a compatibility question: should replacing\nthe manual check with early_scan_options() preserve the current\nrestrictions or accept additional forms recognized by the shared\nparser?\nI prepared a technical proposal explaining the findings and requesting feedback.\nDiscussion:\nhttps://gitlist.dev/t/66794\nI also became aware that another Outreachy applicant had identified\ngit column as a potential future conversion target.\nBecause Git development is collaborative, I believe coordinating\nrelated work is important. I therefore consider this an investigated\ncandidate rather than an implementation task already assigned to me.\n3.5 Investigating other Git commands\nTo understand the broader project, I searched Git's built-in C\ncommands for manual argument-processing code.\nMy initial searches identified several candidates, including git hook,\ngit ls-remote, git name-rev, git archive, git hash-object, and git\ndiff-index.\nAfter examining their implementations, I learned that not every loop\nover argv represents manual option parsing.\nFor example, git ls-remote already uses parse_options() and processes\nref patterns afterward. Similarly, git name-rev processes object\nnames, while git hash-object processes filenames after option parsing.\nThese investigations taught me to distinguish normal argument\nprocessing from code that might genuinely benefit from a shared\nparsing API.\nA conversion should address a meaningful problem rather than simply\nreplace existing code.\nThis process eventually led me to git diff-index, which I would like\nto explore as an initial internship candidate.\n4. Understanding of the Internship Project\nGit provides shared parsing APIs, including parse_options() and\nearly_scan_options().\nHowever, some built-in commands still use manually written code to\nrecognize and process command-line options.\nThese implementations can sometimes duplicate functionality, create\ninconsistent behavior, or make future maintenance more difficult.\nI understand the goal of this project as identifying suitable\nopportunities to replace manual parsing with shared APIs while\npreserving the command's expected behavior.\nA successful conversion involves more than replacing string comparisons.\nIt requires understanding the existing command, identifying why the\nchange would be useful, studying how other parsing mechanisms interact\nwith it, and establishing regression tests.\nI would like to approach the work incrementally, beginning with an\ninvestigated candidate and expanding to additional suitable tasks with\nmentor guidance.\n5. Proposed Technical Work\nDuring the contribution period, I investigated how Git commands\nprocess their arguments and identified two possible areas for further\nwork: git diff-index and git diff-tree.\nBoth commands use setup_revisions() to process common revision and\ndiff arguments before handling some command-specific options manually.\nI would like to investigate whether these remaining options could be\nhandled through Git's shared parse_options() API, provided the change\nimproves maintainability without affecting existing behavior.\n5.1 Primary candidate: git diff-index\nFile: builtin/diff-index.c\ngit diff-index uses setup_revisions() to process revision-related and\ncommon diff arguments. It then manually handles three command-specific\noptions:\nargc = setup_revisions(argc, argv, &rev, NULL);\n\nfor (i = 1; i < argc; i++) {\n    const char *arg = argv[i];\n\n    if (!strcmp(arg, \"--cached\"))\n        option |= DIFF_INDEX_CACHED;\n    else if (!strcmp(arg, \"--merge-base\"))\n        option |= DIFF_INDEX_MERGE_BASE;\n    else if (!strcmp(arg, \"-m\"))\n        rev.match_missing = 1;\n    else\n        usage(diff_cache_usage);\n}\nThe options are --cached, --merge-base, and -m.\nI examined this loop and the relevant parts of setup_revisions() in\nrevision.c. I found that setup_revisions() processes shared arguments\nwhile preserving certain unrecognized options for the calling command.\nAnother detail is that git diff-index calls\ndiff_merges_suppress_m_parsing() before setup_revisions(). This\nprevents the common diff-merges parser from interpreting -m, allowing\ndiff-index to preserve its command-specific meaning.\nWhy investigate this code?\nThe command has a small manual parser that may benefit from Git's\nshared parsing infrastructure. However, its interaction with\nsetup_revisions() means a conversion is not as simple as replacing the\nstring comparisons with a struct option array.\nA useful conversion should reduce command-specific parsing code\nwithout making the implementation more complicated or changing\nestablished behavior.\nProposed approach\nI would:\n1. Document how the three options are preserved and handled after\nsetup_revisions().\n2. Examine how diff_merges_suppress_m_parsing() protects the meaning of -m.\n3. Establish the existing behavior of option ordering, repeated\noptions, invalid arguments, and pathspecs.\n4. Compare this behavior with a possible parse_options() implementation.\n5. Discuss compatibility concerns and the proposed design with my mentors.\n6. Implement a focused conversion if the shared API provides a clear benefit.\nTesting\nI have already examined relevant tests in:\n• t/t4002-diff-basic.sh\n• t/t4013-diff-various.sh\n• t/t4068-diff-symmetric-merge-base.sh\nOne interesting finding was that t4068 runs several --merge-base tests\nagainst both git diff and git diff-index using a shared test loop.\nMy initial search missed this coverage because the test script used a\nvariable instead of writing the command name directly.\nI would use the existing tests as a baseline and add focused\nregression tests only where they protect important behavior or address\nidentified gaps.\nExpected deliverable\nIf the design is appropriate, I would prepare a small, tested patch\nseries improving the command-specific parsing in git diff-index and\nsubmit it for upstream review.\nIf a conversion introduces unnecessary complexity, I would discuss an\nalternative approach or another suitable candidate with my mentors.\n5.2 Secondary candidate: git diff-tree\nFile: builtin/diff-tree.c\nI also investigated git diff-tree, which uses setup_revisions() before\nmanually handling two command-specific options: --stdin and\n--merge-base.\nIts implementation contains the following loop:\nwhile (--argc > 0) {\n    const char *arg = *++argv;\n\n    if (!strcmp(arg, \"--stdin\")) {\n        read_stdin = 1;\n        continue;\n    }\n    if (!strcmp(arg, \"--merge-base\")) {\n        merge_base = 1;\n        continue;\n    }\n    usage(diff_tree_usage);\n}\nWhile examining this code, I discovered that the manual parser is\ndeliberately connected to Git's revision-processing infrastructure.\nBefore calling setup_revisions(), git diff-tree sets disable_stdin =\n1. I traced this into revision.c and found that it causes\nsetup_revisions() to preserve --stdin for the command instead of\nprocessing it through the revision parser.\nI also examined how handle_revision_opt() uses diff_opt_parse() and\noverwrite_argv() to preserve unrecognized options. At the end of\nsetup_revisions(), Git returns the remaining argument count and\nterminates the argument list with NULL.\nThis helped me understand how diff-tree receives its command-specific\noptions after revision processing.\nBehavior verified during my investigation\nI tested the command using my locally built Git executable and confirmed that:\n• --stdin and --merge-base cannot be used together.\n• --merge-base requires exactly two commits.\n• The abbreviated option --stdi is rejected rather than accepted as --stdin.\nThese behaviors are important because a shared parser may recognize\nargument forms that the current manual parser rejects.\nExisting tests\nI also investigated the regression tests and found that:\n• t4002 tests normal diff-tree --stdin behavior.\n• t4013 tests --stdin with log formatting and pathspecs.\n• t4068 tests the failure of diff-tree --merge-base when only one\ncommit is supplied.\n• Other test scripts exercise --stdin in different workflows.\nMy searches did not identify a direct diff-tree test for combining\n--stdin and --merge-base, although I would verify the full coverage\nbefore proposing a new test.\nWhy investigate this code?\nThe manual loop is small, but my investigation showed that it serves a\ndeliberate purpose.\nThe question is whether parse_options() can replace the final\nrecognition of --stdin and --merge-base while preserving their handoff\nfrom setup_revisions() and the command's existing restrictions.\nProposed approach\nI would:\n1. Keep setup_revisions() responsible for common revision and diff arguments.\n2. Evaluate whether parse_options() can safely process the remaining\ncommand-specific arguments.\n3. Compare the current behavior with possible shared-parser option\ndefinitions and flags.\n4. Preserve the existing restrictions involving --stdin, --merge-base,\nrevisions, and pathspecs.\n5. Use existing tests and add regression coverage where a meaningful\ngap is established.\n6. Discuss whether the conversion improves maintainability before\nimplementing it.\nIf the conversion proves worthwhile, I would prepare a focused patch\nseries for review.\nOtherwise, I would document the findings and consider a different candidate.\n5.3 Additional parsing improvements\nI understand that identifying suitable conversion targets is part of\nthe internship project.\nFrom my earlier investigations of commands such as git hook, git\nls-remote, git name-rev, git archive, and git hash-object, I learned\nthat not every loop over argv represents unnecessary manual option\nparsing.\nI would therefore continue looking for candidates where using a shared\nAPI could solve a genuine correctness, consistency, or maintainability\nproblem.\nBefore selecting a task, I would check whether the code actually\nparses options, what behavior needs to be preserved, whether tests\nalready exist, and whether another contributor is working on the same\narea.\nI would discuss promising candidates with Christian and Siddharth\nbefore beginning implementation.\n6. How I Plan to Approach the Work\nI plan to work in small, reviewable steps.\nUnderstand the problem first. I would read the relevant source code,\ndocumentation, tests, and previous discussions. Before changing a\nparser, I want to understand what it currently does and why the change\nwould help.\nDiscuss the design. I would compare the existing implementation with\nthe appropriate shared API, consider alternative approaches, and raise\ncompatibility questions with my mentors before making substantial\nchanges.\nTest what matters. I would reuse existing tests where possible and add\nfocused tests to protect important behavior. If fixing a demonstrated\nbug, I would aim to write a test that fails before the fix and passes\nafterward.\nImplement the smallest useful change. I would avoid unrelated changes\nand preserve command-specific checks that remain necessary even after\na parser conversion.\nWork through review. I would build Git, run the relevant tests, submit\npatches to the mailing list, and revise them based on feedback.\nMy first contribution taught me that a good commit message should\nexplain why a change is useful, not only what code was modified.\n7. Risks and Alternative Approaches\nThe main technical risk is the interaction between setup_revisions()\nand parse_options().\nBoth git diff-index and git diff-tree rely on revision-processing\ninfrastructure, so a conversion could unintentionally change how Git\ninterprets options, revisions, or pathspecs.\nFor diff-index, the command-specific meaning of -m must remain\nprotected. For diff-tree, the handling of --stdin and its restrictions\nmust be preserved.\nAnother risk is changing accepted command-line syntax. For example,\nparse_options() may recognize abbreviated or negated options that the\nexisting manual parser rejects.\nI would address these risks by establishing current behavior,\ncomparing alternative designs, and testing the proposed\nimplementation.\nA manual parser may also be appropriate for its command. If using the\nshared API creates more complexity than it removes, I would discuss\nretaining the existing implementation or selecting another candidate.\nI would also follow upstream discussions to avoid duplicating another\ncontributor's work.\nFinally, I would leave enough time for reviews and revisions, since a\npatch is not complete simply because it passes tests locally.\n8. Proposed 13-Week Internship Timeline\nThis is my proposed timeline, which I expect to refine with Christian\nand Siddharth based on project priorities and technical findings.\nWeek Proposed work and milestone\n1 Review current parsing APIs and related upstream work. Confirm the\nfirst implementation target and expected outcome with mentors.\n2 Complete the design evaluation for diff-index, establish baseline\ntests, and discuss compatibility concerns.\n3 Begin implementing the first agreed improvement and add focused\nregression tests where needed.\n4 Validate the implementation and submit the first patch series for review.\n5 Respond to feedback, refine the code and tests, and submit revisions.\n6 Continue review and integration work while beginning research on\nanother suitable candidate.\n7 Evaluate diff-tree or another mentor-approved target, including its\ntechnical benefits and compatibility requirements.\n8 Finalize the second task's design and establish relevant test coverage.\n9 Implement and test the second agreed improvement, if appropriate.\n10 Submit the next patch series and begin addressing reviewer feedback.\n11 Continue revisions and investigate smaller follow-up improvements\nwhere time permits.\n12 Resolve outstanding feedback, verify relevant tests, and update\ndocumentation where needed.\n13 Complete the final technical summary, document remaining work, and\nprepare the internship report.\nThese stages are flexible. Git's review process may require several\niterations, so implementation and review activities may overlap.\nFor example, while waiting for feedback on one patch, I could\ninvestigate another candidate or improve relevant tests.\nI would provide weekly progress updates and aim for clear technical\ncheckpoints at least every two weeks.\nMinimum intended outcome: Complete at least one technically justified\nparsing improvement through implementation, testing, and upstream\nreview, subject to mentor agreement.\nFurther goal: Contribute additional reviewed improvements if time and\ntechnical findings permit.\n9. Communication Plan\nOne thing I particularly appreciate about Git is its review culture.\nMy first contribution showed me that reviews are not only about\ncorrecting mistakes. They also help contributors understand the\nreasons behind technical decisions.\nDuring the internship, I intend to communicate primarily through the\nGit mailing list, where I would ask technical questions, submit\npatches, and participate in review discussions.\nI will provide weekly written progress updates, preferably through a\nblog as Christian recommends, and maintain regular communication with\nSiddharth.\nMy updates will explain what I completed, what is under review, any\ndifficulties I encountered, and what I intend to work on next.\nWhen requesting help, I would describe the problem, explain what I\nhave investigated, and ask specific questions.\nI would also like to continue reading and testing other contributors'\nchanges. My independent testing of Hussain's check-ref-format\nconversion helped me appreciate this part of open-source development.\n10. Availability\nI will be available throughout the internship, from December 7, 2026,\nto March 8, 2027.\nI can dedicate at least 30 hours per week to the project and do not\nanticipate commitments that would interfere with my internship work.\nIf my availability changes, I will communicate that promptly and\ncoordinate with my mentors.\n11. What I Hope to Achieve\nBy the end of the internship, I hope to have contributed meaningful,\nwell-tested improvements to Git's command-line argument handling.\nMy expected outcomes include:\n• At least one technically justified parsing improvement submitted for\nupstream review.\n• Additional parsing improvements where appropriate and agreed with mentors.\n• Regression tests that protect important command behavior.\n• Clear patch submissions and constructive responses to reviews.\n• Better understanding of Git's parsing APIs, revision infrastructure,\nand testing framework.\n• Stronger C programming, debugging, and technical communication skills.\nI also want to become more confident reading large codebases and\nexplaining not only what a change does, but why it is needed and what\nrisks it introduces.\nI understand that the value of my work will depend more on the\nusefulness and quality of the contributions than on the number of\ncommands converted.\n12. Beyond Outreachy\nI want this internship to be the beginning of my continued involvement\nin open-source development.\nWorking with Git during the contribution period has shown me how much\nthere is to learn from even a small patch and how valuable\nconstructive feedback can be.\nI hope to continue contributing to Git, follow technical discussions,\nreview changes where I can, and gradually take on more challenging\nwork.\nAs I gain experience, I would also like to help other newcomers become\nmore comfortable contributing to open-source projects, just as members\nof the Git community have helped me.\n13. References\nMy Git work\n1. Microproject: t1402: test --no-allow-onelevel option precedence\nhttps://lore.kernel.org/git/20261029121715.3845-1-fiendora5@gmail.com/\n2. Integrated microproject: Commit 0110f33aa8\nIntegration merge commit: cc117c8364\n3. git column technical investigation:\nhttps://gitlist.dev/t/66794\nRelevant project work and documentation\n4. Christian Couder's early_scan_options() series:\nhttps://lore.kernel.org/git/20260902161047.476753-1-christian.couder@gmail.com/\n5. Git General Application Information:\nhttps://git.github.io/General-Application-Information/\n6. Git General Microproject Information:\nhttps://git.github.io/General-Microproject-Information/\n7. Git documentation — git diff-index:\nhttps://git-scm.com/docs/git-diff-index\n8. Git documentation — git diff-tree:\nhttps://git-scm.com/docs/git-diff-tree\n9. Relevant source files:\no builtin/diff-index.c\no builtin/diff-tree.c\no revision.c\no parse-options.h\n10. Relevant regression tests:\no t/t4002-diff-basic.sh\no t/t4013-diff-various.sh\no t/t4068-diff-symmetric-merge-base.sh\no t/t4017-diff-retval.sh\no t/t4035-diff-quiet.sh\nI would appreciate feedback from the Git community on whether git\ndiff-index and git diff-tree are suitable candidates for using the\nshared parsing API, whether the proposed approach is appropriate given\ntheir interaction with setup_revisions(), and what additional work\nwould be useful to prioritize during the internship.\nThank you for the guidance I have received throughout the contribution period.\nBest regards,\nFien Dora\n\n"},{"id":"558599","messageId":"AS4PR02MB83363999DA64DD82F6E25FB0EB7B2@AS4PR02MB8336.eurprd02.prod.outlook.com","threadId":"66807","inReplyTo":"CACWAS-UqbkgfzsJ2283=OgoUHRs-FeRNYc0zkBR2y0XD4jTWsw@mail.gmail.com","subject":"Email formatting (was RE: [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed)","fromName":"Richard Kerry","fromEmail":"richard.kerry@atos.ai","sentAt":"2026-11-17T09:41:46Z","receivedAt":"2026-11-17T09:41:46Z","isPatch":false,"sender":{"key":"richard.kerry@atos.ai","avatar":null},"body":"\nI don't know whether it's because of my mail reader, which is Outlook (I know it isn't a favourite in these parts but this is a corporate machine), but this email has come through to me with no indentation and no blank lines between any lines.\n\nI don't know whether the guidelines explicitly mention this but for myself I find both these properties make it difficult to read.\n\nThere are a small number of fairly frequent contributors to the list who are also in the habit of not putting blank lines around additions (or even putting just one after the addition) within long blocks of text with reply marks (ie '>' characters).  That also doesn't help me be able to easily read contributions.  If there is a mass of text with all but a handful of lines starting with '>' they are very difficult to spot.\n\nWould it be reasonable for me to ask that the guidelines should request at least a little bit of breaking of large slabs of text, whether plain text, as here, or long replies, as elsewhere?\n\nRegards,\nRichard.\n\n\nKind regards,\n\nRichard Kerry\nBNCS Engineer - Media Competency Centre\nMidCity Place, 71 High Holborn - London WC1V 6EA - UK\natos.ai\n\n\n> -----Original Message-----\n> Sent: 09 November 2026 05:22\n> Subject: [Outreachy] Draft internship proposal: Improve how command\n> arguments and options are scanned and parsed\n>\n>\n> Community: Git\n> Project: Improve how command arguments and options are scanned and parsed\n> Mentors: Christian Couder and Siddharth Asthana Internship period: December 7,\n> 2026 - March 8, 2027 1. About Me Hello everyone, I'm Fien Dora, a Computer\n> Engineer with an interest in C programming, systems programming, and\n> understanding how things work in the background.\n> I've always enjoyed mathematics and solving problems. I've always been curious\n> about compilers, and what happens when a command is sent. That curiosity\n> pushed me to start learning programming. In 2023, I joined the ALX learning\n> program, where I was introduced to C, shell scripting, and systems programming.\n> Of everything I was learning, C caught my attention the most.\n> I liked that C helped me understand what was happening closer to the computer\n> itself like compilers, interpreters, memory, and how software communicates with\n> hardware.\n> I am still growing as a C programmer, especially when it comes to understanding\n> large codebases, but I enjoy taking time to understand a problem and working\n> through it until things become clearer.\n> That is one of the reasons I was drawn to Git's Outreachy project.\n> Availability: 30 hours per week from 7 December 2026 to 8 March 2027.\n> 2. Why Git and Outreachy?\n> To me, Git is the reason behind successful software development. I usually use Git\n> mainly as a tool for tracking changes or versions, working with branches, and\n> collaborating with other developers.\n\n\nAtos is a trading name used by the Atos group. The trading entity is registered in England and Wales: Atos IT Services UK Limited (registered number 01245534). The registered office is located at: Second Floor, MidCity Place, 71 High Holborn, London, WC1V 6EA. The VAT No. is: GB232327983. This e-mail and the documents attached are confidential and intended solely for the addressee and may contain confidential or privileged information. If you receive this e-mail in error, you are not authorised to copy, disclose, use, or retain it. Please notify the sender immediately and delete this email from your systems. As emails may be intercepted, amended, or lost, they are not secure. Atos therefore can accept no liability for any errors or their content. Although Atos endeavours to maintain a virus-free network, we do not warrant that this transmission is virus-free and can accept no liability for any damages resulting from any virus transmitted. The risks are deemed to be accepted by everyone who communicates with Atos by email.\n\n"},{"id":"558638","messageId":"xmqqik1vfizh.fsf@gitster.g","threadId":"66807","inReplyTo":"AS4PR02MB83363999DA64DD82F6E25FB0EB7B2@AS4PR02MB8336.eurprd02.prod.outlook.com","subject":"Re: Email formatting (was RE: [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-17T17:47:14Z","receivedAt":"2026-11-17T17:47:14Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Kerry <richard.kerry@atos.ai> writes:\n\n> I don't know whether it's because of my mail reader, which is\n> Outlook (I know it isn't a favourite in these parts but this is a\n> corporate machine), but this email has come through to me with no\n> indentation and no blank lines between any lines.\n>\n> I don't know whether the guidelines explicitly mention this but\n> for myself I find both these properties make it difficult to read.\n>\n> There are a small number of fairly frequent contributors to the\n> list who are also in the habit of not putting blank lines around\n> additions (or even putting just one after the addition) within\n> long blocks of text with reply marks (ie '>' characters).  That\n> also doesn't help me be able to easily read contributions.  If\n> there is a mass of text with all but a handful of lines starting\n> with '>' they are very difficult to spot.\n>\n> Would it be reasonable for me to ask that the guidelines should\n> request at least a little bit of breaking of large slabs of text,\n> whether plain text, as here, or long replies, as elsewhere?\n\nWe do tell our folks that all text (commit log messages, code,\ndocumentation sources and e-mail communications) must be\nline-wrapped to comfortably fit on an 80-column terminal after\ngetting \"> quoted\" a few times in the discussion exchange, which\nmeans that the practical limit is around 70 columns [jc: I\nline-wrapped your message above as you sent four long lines, with a\nblank line between each pair].\n\nI do prefer to see a blank line between paragraphs, and here\n\"paragraph\" includes a block of \"> quoted\" text, so I do not mind if\nsomebody adds to the documentation near where we talk about the\nline-length limit and line-wrapping such a rule.\n\nThanks for raising the issue.\n\n"},{"id":"558643","messageId":"CAFpMFfBJdBukP87oX9a-GMvOncs_US-LbqqTHP6n=7hv-JUJWQ@mail.gmail.com","threadId":"66807","inReplyTo":"xmqqik1vfizh.fsf@gitster.g","subject":"Re: Email formatting (was RE: [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed)","fromName":"Okhuomon Ajayi","fromEmail":"okhuomonajayi54@gmail.com","sentAt":"2026-11-17T18:20:30Z","receivedAt":"2026-11-17T18:20:30Z","isPatch":false,"sender":{"key":"okhuomonajayi54@gmail.com","avatar":null},"body":"On Tue, Nov 17, 2026 at 6:47 PM Junio C Hamano <gitster@pobox.com> wrote:\n\n> I do prefer to see a blank line between paragraphs, and here\n> \"paragraph\" includes a block of \"> quoted\" text, so I do not mind if\n> somebody adds to the documentation near where we talk about the\n> line-length limit and line-wrapping such a rule.\n>\n> Thanks for raising the issue.\n\nHi Junio,\n\nI can add that to the documentation, next to where we already\ntalk about the line-length limit and line wrapping: a blank\nline between paragraphs, and a quoted block counts as a\nparagraph too.\n\nI'll send the patch once it is written.\n\nThanks,\n\nOkhuomon.\n\n"},{"id":"558644","messageId":"20261117184912.9491-1-okhuomonajayi54@gmail.com","threadId":"66807","inReplyTo":"CAFpMFfBJdBukP87oX9a-GMvOncs_US-LbqqTHP6n=7hv-JUJWQ@mail.gmail.com","subject":"[PATCH] MyFirstContribution: leave a blank line between mailing-list paragraphs","fromName":"Okhuomon Ajayi","fromEmail":"okhuomonajayi54@gmail.com","sentAt":"2026-11-17T18:49:12Z","receivedAt":"2026-11-17T18:49:12Z","isPatch":true,"sender":{"key":"okhuomonajayi54@gmail.com","avatar":null},"body":"A short reply is hard to spot when it is packed against a long run\nof quoted lines. Leave a blank line between paragraphs. A block of\nquoted text counts as a paragraph.\n\nSigned-off-by: Okhuomon Ajayi <okhuomonajayi54@gmail.com>\n---\nThis is the documentation change mentioned in the previous message.\n\n Documentation/MyFirstContribution.adoc | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex c58253fd54..9c189b6c9e 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1357,6 +1357,9 @@ relevant to your response. It is usually helpful to trim away unrelated context,\n such as large portions of the patch that are not being discussed, while keeping\n enough quoted text for readers to understand what you are responding to.\n \n+Leave a blank line between paragraphs. A block of quoted text counts\n+as a paragraph, so leave a blank line before and after it.\n+\n Make sure your email client has a plaintext email mode and it is turned on; the\n Git list rejects HTML email. Please also follow the mailing list etiquette\n outlined in the\n\nbase-commit: 7fb6055e678f800320d8ab8cd8f201d9493d1ba0\n-- \n2.56.0\n\n\n"}]}