All of lore.kernel.org
 help / color / mirror / Atom feed
* [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed
@ 2026-11-09  5:21 Fien Dora
  2026-11-17  9:41 ` Email formatting (was RE: [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed) Richard Kerry
  0 siblings, 1 reply; 5+ messages in thread
From: Fien Dora @ 2026-11-09  5:21 UTC (permalink / raw)
  To: git

Applicant: Fien Dora
Community: Git
Project: Improve how command arguments and options are scanned and parsed
Mentors: Christian Couder and Siddharth Asthana
Internship period: December 7, 2026 – March 8, 2027
1. About Me
Hello everyone,
I'm Fien Dora, a Computer Engineer with an interest in C programming,
systems programming, and understanding how things work in the
background.
I've always enjoyed mathematics and solving problems. I’ve always been
curious about compilers, and what happens when a command is sent. That
curiosity pushed me to start learning programming. In 2023, I joined
the ALX learning program, where I was introduced to C, shell
scripting, and systems programming. Of everything I was learning, C
caught my attention the most.
I liked that C helped me understand what was happening closer to the
computer itself like compilers, interpreters, memory, and how software
communicates with hardware.
I am still growing as a C programmer, especially when it comes to
understanding large codebases, but I enjoy taking time to understand a
problem and working through it until things become clearer.
That is one of the reasons I was drawn to Git's Outreachy project.
Availability: 30 hours per week from 7 December 2026 to 8 March 2027.
2. Why Git and Outreachy?
To me, Git is the reason behind successful software development. I
usually use Git mainly as a tool for tracking changes or versions,
working with branches, and collaborating with other developers.
The project on argument-parsing was particularly interesting to me
because It combines my interest in C and systems programming with the
opportunity to understand and improve software that many developers
depend on.
Another thing I have come to appreciate about Git is its community.
During this contribution period, it was very strange to me that the
git community was a mailing list but I discovered how much attention
Git contributors give to reviewing changes. Reviewers do not simply
tell you that something is wrong. They explain why it is a problem and
suggest a better way to approach it, which was very amazing.
I experienced this during my first contribution, when Junio reviewed
my patch and pointed out weaknesses in how I explained its purpose.
His feedback helped me understand that a patch should not only work;
it should also have a clear reason for existing.
I also learned Git's mailing-list conventions through that process.
I value this experience as I learn from experienced developers while
contributing to a real project, rather than learning programming
concepts only through exercises.
I have also been encouraged by previous Outreachy interns who have
contributed to Git's internal code and testing infrastructure. Their
experiences show that meaningful contributions can begin with small,
carefully understood changes.
I look forward to this internship to help me become more confident
working with C and participating in open-source development.
Most importantly, I want to continue contributing to open source after
Outreachy.
3. My Git Contributions and What I Have Learned
3.1 My first contribution: git check-ref-format
Patch: t1402: test --no-allow-onelevel option precedence
Discussion: https://lore.kernel.org/git/20261029121715.3845-1-fiendora5@gmail.com/
Commit: 0110f33aa8
Status: Queued by Junio and integrated into Git's next branch during
the contribution period.
For my microproject, I worked on the tests for git check-ref-format.
While reading its code, I learned that it uses a manually written loop
to handle some command-line options instead of the shared
parse_options() API.
I focused on two options: --allow-onelevel and --no-allow-onelevel.
These options determine whether Git accepts a refname containing only
one component. When both options are supplied, the last one determines
the result.
I added two tests to t/t1402-check-ref-format.sh to protect that
behavior in both argument orders.
The code change itself was small, but getting the patch ready for
review taught me a lot.
My first commit message explained what the tests did, but Junio
pointed out that it did not sufficiently explain why those tests were
useful.
He helped me see that check-ref-format was worth testing specifically
because it used a handcrafted parser and its behavior could matter
during future parsing changes.
In another review, he questioned a statement I made about a planned
conversion. I had described possible future work as though it had
already been decided.
That was an important lesson: I should distinguish between something
that already exists, something another contributor is doing, and
something I am only proposing.
I revised the patch explanation, and the contribution went through
three versions.
Junio eventually replied that the changes were well explained and
would be queued.
I also learned about Git's email conventions, including replying below
relevant quoted text and keeping quotes short enough for others to
follow a discussion.
Looking back, the most valuable part of this contribution was not just
having a patch accepted. It was learning how to explain my reasoning,
respond to feedback, and improve my work through review.
3. My Git Contribution Experience
3.1 First microproject: Testing option precedence in git check-ref-format
Patch: t1402: test --no-allow-onelevel option precedence
Mailing-list discussion:
https://lore.kernel.org/git/20261029121715.3845-1-fiendora5@gmail.com/
Commit: 0110f33aa8
My first contribution involved investigating the behavior of two
conflicting options in git check-ref-format:
• --allow-onelevel
• --no-allow-onelevel
These options control whether a refname with only one component is accepted.
I examined the existing implementation and test coverage and added two
regression tests to t/t1402-check-ref-format.sh.
The tests verify that when both options are supplied, the last one
determines the effective behavior, regardless of their order.
After building Git locally and running the relevant tests, I submitted
the signed-off patch to the Git mailing list.
The contribution went through three versions following feedback from
Junio C Hamano.
One of the most important things I learned was that a patch should
explain not only what a change does, but also why the change is
useful.
Junio's feedback helped me recognize weaknesses in my initial
explanation, particularly where I made assumptions about possible
future parser changes.
I revised the commit message to explain the reason for protecting the
existing behavior more accurately.
After reviewing the revised patch, Junio indicated that it was well
explained and would be queued. The contribution subsequently reached
Git's next integration branch.
The review process was especially valuable to me. It showed me how
much thought goes into even a small contribution and encouraged me to
become more careful with technical explanations, assumptions, and
tests.
3.2 Independent testing of another contributor's check-ref-format conversion
After my first contribution, I intended for a follow up contribution
of git check-ref-format conversion and how it behaves when its manual
argument parsing were replaced with Git's shared parse_options() API.
I studied a conversion proposed by fellow contributor Hussain Sitamouwala.
I checked out the proposed changes locally, built Git, and ran the
relevant test suites.
In that testing environment:
• All 107 tests in t1402-check-ref-format.sh passed.
• All 96 tests in t0040-parse-options.sh passed.
I also manually tested cases involving option precedence, repeated
options, abbreviated names, unsupported option forms, and the --
separator.
I did not identify unexpected regressions in the cases tested.
This was an independent testing exercise, not a patch I authored or a
formal review submitted to the mailing list.
It helped me understand that changing a command's parser requires
examining more than its normal use cases. Even when existing
functionality continues working, a new parser may recognize additional
argument forms or produce different errors.
This reinforced the importance of understanding existing behavior
before implementing a conversion.
3.3 Studying early_scan_options() and git fast-import
I also studied Christian Couder's early_scan_options() series and
examined how the API is used in fast-import.
This helped me understand why certain commands need to inspect
particular options before normal argument parsing begins.
I learned about PARSE_OPT_EARLY and how early scanning can help
commands process options that influence configuration or
initialization.
Studying this implementation led me to investigate another possible
use of the API.
3.4 Investigating git column
While examining other built-in commands, I noticed that
builtin/column.c manually checks for --command= before invoking
parse_options().
I studied the implementation and tested several argument forms,
including attached values, separate values, abbreviated option names,
option ordering, and repeated options.
The investigation raised a compatibility question: should replacing
the manual check with early_scan_options() preserve the current
restrictions or accept additional forms recognized by the shared
parser?
I prepared a technical proposal explaining the findings and requesting feedback.
Discussion:
https://gitlist.dev/t/66794
I also became aware that another Outreachy applicant had identified
git column as a potential future conversion target.
Because Git development is collaborative, I believe coordinating
related work is important. I therefore consider this an investigated
candidate rather than an implementation task already assigned to me.
3.5 Investigating other Git commands
To understand the broader project, I searched Git's built-in C
commands for manual argument-processing code.
My initial searches identified several candidates, including git hook,
git ls-remote, git name-rev, git archive, git hash-object, and git
diff-index.
After examining their implementations, I learned that not every loop
over argv represents manual option parsing.
For example, git ls-remote already uses parse_options() and processes
ref patterns afterward. Similarly, git name-rev processes object
names, while git hash-object processes filenames after option parsing.
These investigations taught me to distinguish normal argument
processing from code that might genuinely benefit from a shared
parsing API.
A conversion should address a meaningful problem rather than simply
replace existing code.
This process eventually led me to git diff-index, which I would like
to explore as an initial internship candidate.
4. Understanding of the Internship Project
Git provides shared parsing APIs, including parse_options() and
early_scan_options().
However, some built-in commands still use manually written code to
recognize and process command-line options.
These implementations can sometimes duplicate functionality, create
inconsistent behavior, or make future maintenance more difficult.
I understand the goal of this project as identifying suitable
opportunities to replace manual parsing with shared APIs while
preserving the command's expected behavior.
A successful conversion involves more than replacing string comparisons.
It requires understanding the existing command, identifying why the
change would be useful, studying how other parsing mechanisms interact
with it, and establishing regression tests.
I would like to approach the work incrementally, beginning with an
investigated candidate and expanding to additional suitable tasks with
mentor guidance.
5. Proposed Technical Work
During the contribution period, I investigated how Git commands
process their arguments and identified two possible areas for further
work: git diff-index and git diff-tree.
Both commands use setup_revisions() to process common revision and
diff arguments before handling some command-specific options manually.
I would like to investigate whether these remaining options could be
handled through Git's shared parse_options() API, provided the change
improves maintainability without affecting existing behavior.
5.1 Primary candidate: git diff-index
File: builtin/diff-index.c
git diff-index uses setup_revisions() to process revision-related and
common diff arguments. It then manually handles three command-specific
options:
argc = setup_revisions(argc, argv, &rev, NULL);

for (i = 1; i < argc; i++) {
    const char *arg = argv[i];

    if (!strcmp(arg, "--cached"))
        option |= DIFF_INDEX_CACHED;
    else if (!strcmp(arg, "--merge-base"))
        option |= DIFF_INDEX_MERGE_BASE;
    else if (!strcmp(arg, "-m"))
        rev.match_missing = 1;
    else
        usage(diff_cache_usage);
}
The options are --cached, --merge-base, and -m.
I examined this loop and the relevant parts of setup_revisions() in
revision.c. I found that setup_revisions() processes shared arguments
while preserving certain unrecognized options for the calling command.
Another detail is that git diff-index calls
diff_merges_suppress_m_parsing() before setup_revisions(). This
prevents the common diff-merges parser from interpreting -m, allowing
diff-index to preserve its command-specific meaning.
Why investigate this code?
The command has a small manual parser that may benefit from Git's
shared parsing infrastructure. However, its interaction with
setup_revisions() means a conversion is not as simple as replacing the
string comparisons with a struct option array.
A useful conversion should reduce command-specific parsing code
without making the implementation more complicated or changing
established behavior.
Proposed approach
I would:
1. Document how the three options are preserved and handled after
setup_revisions().
2. Examine how diff_merges_suppress_m_parsing() protects the meaning of -m.
3. Establish the existing behavior of option ordering, repeated
options, invalid arguments, and pathspecs.
4. Compare this behavior with a possible parse_options() implementation.
5. Discuss compatibility concerns and the proposed design with my mentors.
6. Implement a focused conversion if the shared API provides a clear benefit.
Testing
I have already examined relevant tests in:
• t/t4002-diff-basic.sh
• t/t4013-diff-various.sh
• t/t4068-diff-symmetric-merge-base.sh
One interesting finding was that t4068 runs several --merge-base tests
against both git diff and git diff-index using a shared test loop.
My initial search missed this coverage because the test script used a
variable instead of writing the command name directly.
I would use the existing tests as a baseline and add focused
regression tests only where they protect important behavior or address
identified gaps.
Expected deliverable
If the design is appropriate, I would prepare a small, tested patch
series improving the command-specific parsing in git diff-index and
submit it for upstream review.
If a conversion introduces unnecessary complexity, I would discuss an
alternative approach or another suitable candidate with my mentors.
5.2 Secondary candidate: git diff-tree
File: builtin/diff-tree.c
I also investigated git diff-tree, which uses setup_revisions() before
manually handling two command-specific options: --stdin and
--merge-base.
Its implementation contains the following loop:
while (--argc > 0) {
    const char *arg = *++argv;

    if (!strcmp(arg, "--stdin")) {
        read_stdin = 1;
        continue;
    }
    if (!strcmp(arg, "--merge-base")) {
        merge_base = 1;
        continue;
    }
    usage(diff_tree_usage);
}
While examining this code, I discovered that the manual parser is
deliberately connected to Git's revision-processing infrastructure.
Before calling setup_revisions(), git diff-tree sets disable_stdin =
1. I traced this into revision.c and found that it causes
setup_revisions() to preserve --stdin for the command instead of
processing it through the revision parser.
I also examined how handle_revision_opt() uses diff_opt_parse() and
overwrite_argv() to preserve unrecognized options. At the end of
setup_revisions(), Git returns the remaining argument count and
terminates the argument list with NULL.
This helped me understand how diff-tree receives its command-specific
options after revision processing.
Behavior verified during my investigation
I tested the command using my locally built Git executable and confirmed that:
• --stdin and --merge-base cannot be used together.
• --merge-base requires exactly two commits.
• The abbreviated option --stdi is rejected rather than accepted as --stdin.
These behaviors are important because a shared parser may recognize
argument forms that the current manual parser rejects.
Existing tests
I also investigated the regression tests and found that:
• t4002 tests normal diff-tree --stdin behavior.
• t4013 tests --stdin with log formatting and pathspecs.
• t4068 tests the failure of diff-tree --merge-base when only one
commit is supplied.
• Other test scripts exercise --stdin in different workflows.
My searches did not identify a direct diff-tree test for combining
--stdin and --merge-base, although I would verify the full coverage
before proposing a new test.
Why investigate this code?
The manual loop is small, but my investigation showed that it serves a
deliberate purpose.
The question is whether parse_options() can replace the final
recognition of --stdin and --merge-base while preserving their handoff
from setup_revisions() and the command's existing restrictions.
Proposed approach
I would:
1. Keep setup_revisions() responsible for common revision and diff arguments.
2. Evaluate whether parse_options() can safely process the remaining
command-specific arguments.
3. Compare the current behavior with possible shared-parser option
definitions and flags.
4. Preserve the existing restrictions involving --stdin, --merge-base,
revisions, and pathspecs.
5. Use existing tests and add regression coverage where a meaningful
gap is established.
6. Discuss whether the conversion improves maintainability before
implementing it.
If the conversion proves worthwhile, I would prepare a focused patch
series for review.
Otherwise, I would document the findings and consider a different candidate.
5.3 Additional parsing improvements
I understand that identifying suitable conversion targets is part of
the internship project.
From my earlier investigations of commands such as git hook, git
ls-remote, git name-rev, git archive, and git hash-object, I learned
that not every loop over argv represents unnecessary manual option
parsing.
I would therefore continue looking for candidates where using a shared
API could solve a genuine correctness, consistency, or maintainability
problem.
Before selecting a task, I would check whether the code actually
parses options, what behavior needs to be preserved, whether tests
already exist, and whether another contributor is working on the same
area.
I would discuss promising candidates with Christian and Siddharth
before beginning implementation.
6. How I Plan to Approach the Work
I plan to work in small, reviewable steps.
Understand the problem first. I would read the relevant source code,
documentation, tests, and previous discussions. Before changing a
parser, I want to understand what it currently does and why the change
would help.
Discuss the design. I would compare the existing implementation with
the appropriate shared API, consider alternative approaches, and raise
compatibility questions with my mentors before making substantial
changes.
Test what matters. I would reuse existing tests where possible and add
focused tests to protect important behavior. If fixing a demonstrated
bug, I would aim to write a test that fails before the fix and passes
afterward.
Implement the smallest useful change. I would avoid unrelated changes
and preserve command-specific checks that remain necessary even after
a parser conversion.
Work through review. I would build Git, run the relevant tests, submit
patches to the mailing list, and revise them based on feedback.
My first contribution taught me that a good commit message should
explain why a change is useful, not only what code was modified.
7. Risks and Alternative Approaches
The main technical risk is the interaction between setup_revisions()
and parse_options().
Both git diff-index and git diff-tree rely on revision-processing
infrastructure, so a conversion could unintentionally change how Git
interprets options, revisions, or pathspecs.
For diff-index, the command-specific meaning of -m must remain
protected. For diff-tree, the handling of --stdin and its restrictions
must be preserved.
Another risk is changing accepted command-line syntax. For example,
parse_options() may recognize abbreviated or negated options that the
existing manual parser rejects.
I would address these risks by establishing current behavior,
comparing alternative designs, and testing the proposed
implementation.
A manual parser may also be appropriate for its command. If using the
shared API creates more complexity than it removes, I would discuss
retaining the existing implementation or selecting another candidate.
I would also follow upstream discussions to avoid duplicating another
contributor's work.
Finally, I would leave enough time for reviews and revisions, since a
patch is not complete simply because it passes tests locally.
8. Proposed 13-Week Internship Timeline
This is my proposed timeline, which I expect to refine with Christian
and Siddharth based on project priorities and technical findings.
Week Proposed work and milestone
1 Review current parsing APIs and related upstream work. Confirm the
first implementation target and expected outcome with mentors.
2 Complete the design evaluation for diff-index, establish baseline
tests, and discuss compatibility concerns.
3 Begin implementing the first agreed improvement and add focused
regression tests where needed.
4 Validate the implementation and submit the first patch series for review.
5 Respond to feedback, refine the code and tests, and submit revisions.
6 Continue review and integration work while beginning research on
another suitable candidate.
7 Evaluate diff-tree or another mentor-approved target, including its
technical benefits and compatibility requirements.
8 Finalize the second task's design and establish relevant test coverage.
9 Implement and test the second agreed improvement, if appropriate.
10 Submit the next patch series and begin addressing reviewer feedback.
11 Continue revisions and investigate smaller follow-up improvements
where time permits.
12 Resolve outstanding feedback, verify relevant tests, and update
documentation where needed.
13 Complete the final technical summary, document remaining work, and
prepare the internship report.
These stages are flexible. Git's review process may require several
iterations, so implementation and review activities may overlap.
For example, while waiting for feedback on one patch, I could
investigate another candidate or improve relevant tests.
I would provide weekly progress updates and aim for clear technical
checkpoints at least every two weeks.
Minimum intended outcome: Complete at least one technically justified
parsing improvement through implementation, testing, and upstream
review, subject to mentor agreement.
Further goal: Contribute additional reviewed improvements if time and
technical findings permit.
9. Communication Plan
One thing I particularly appreciate about Git is its review culture.
My first contribution showed me that reviews are not only about
correcting mistakes. They also help contributors understand the
reasons behind technical decisions.
During the internship, I intend to communicate primarily through the
Git mailing list, where I would ask technical questions, submit
patches, and participate in review discussions.
I will provide weekly written progress updates, preferably through a
blog as Christian recommends, and maintain regular communication with
Siddharth.
My updates will explain what I completed, what is under review, any
difficulties I encountered, and what I intend to work on next.
When requesting help, I would describe the problem, explain what I
have investigated, and ask specific questions.
I would also like to continue reading and testing other contributors'
changes. My independent testing of Hussain's check-ref-format
conversion helped me appreciate this part of open-source development.
10. Availability
I will be available throughout the internship, from December 7, 2026,
to March 8, 2027.
I can dedicate at least 30 hours per week to the project and do not
anticipate commitments that would interfere with my internship work.
If my availability changes, I will communicate that promptly and
coordinate with my mentors.
11. What I Hope to Achieve
By the end of the internship, I hope to have contributed meaningful,
well-tested improvements to Git's command-line argument handling.
My expected outcomes include:
• At least one technically justified parsing improvement submitted for
upstream review.
• Additional parsing improvements where appropriate and agreed with mentors.
• Regression tests that protect important command behavior.
• Clear patch submissions and constructive responses to reviews.
• Better understanding of Git's parsing APIs, revision infrastructure,
and testing framework.
• Stronger C programming, debugging, and technical communication skills.
I also want to become more confident reading large codebases and
explaining not only what a change does, but why it is needed and what
risks it introduces.
I understand that the value of my work will depend more on the
usefulness and quality of the contributions than on the number of
commands converted.
12. Beyond Outreachy
I want this internship to be the beginning of my continued involvement
in open-source development.
Working with Git during the contribution period has shown me how much
there is to learn from even a small patch and how valuable
constructive feedback can be.
I hope to continue contributing to Git, follow technical discussions,
review changes where I can, and gradually take on more challenging
work.
As I gain experience, I would also like to help other newcomers become
more comfortable contributing to open-source projects, just as members
of the Git community have helped me.
13. References
My Git work
1. Microproject: t1402: test --no-allow-onelevel option precedence
https://lore.kernel.org/git/20261029121715.3845-1-fiendora5@gmail.com/
2. Integrated microproject: Commit 0110f33aa8
Integration merge commit: cc117c8364
3. git column technical investigation:
https://gitlist.dev/t/66794
Relevant project work and documentation
4. Christian Couder's early_scan_options() series:
https://lore.kernel.org/git/20260902161047.476753-1-christian.couder@gmail.com/
5. Git General Application Information:
https://git.github.io/General-Application-Information/
6. Git General Microproject Information:
https://git.github.io/General-Microproject-Information/
7. Git documentation — git diff-index:
https://git-scm.com/docs/git-diff-index
8. Git documentation — git diff-tree:
https://git-scm.com/docs/git-diff-tree
9. Relevant source files:
o builtin/diff-index.c
o builtin/diff-tree.c
o revision.c
o parse-options.h
10. Relevant regression tests:
o t/t4002-diff-basic.sh
o t/t4013-diff-various.sh
o t/t4068-diff-symmetric-merge-base.sh
o t/t4017-diff-retval.sh
o t/t4035-diff-quiet.sh
I would appreciate feedback from the Git community on whether git
diff-index and git diff-tree are suitable candidates for using the
shared parsing API, whether the proposed approach is appropriate given
their interaction with setup_revisions(), and what additional work
would be useful to prioritize during the internship.
Thank you for the guidance I have received throughout the contribution period.
Best regards,
Fien Dora

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2026-11-17 18:49 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-09  5:21 [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed Fien Dora
2026-11-17  9:41 ` Email formatting (was RE: [Outreachy] Draft internship proposal: Improve how command arguments and options are scanned and parsed) Richard Kerry
2026-11-17 17:47   ` Junio C Hamano
2026-11-17 18:20     ` Okhuomon Ajayi
2026-11-17 18:49       ` [PATCH] MyFirstContribution: leave a blank line between mailing-list paragraphs Okhuomon Ajayi

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.