I am Arsh and I recently completed my microproject submission related to improving advice messages when a branch switch fails due to local changes.

Patch discussion: https://github.com/git/git/pull/2233

Through this contribution, I became familiar with Git's advice system, the relevant code paths in unpack-trees.c, and the associated tests. The review discussion also helped me understand the importance of keeping advice messages concise while guiding users toward safe workflows.

Based on that experience, I am planning a GSoC proposal focused on refining advice messages in several common scenarios across Git commands (such as checkout, push, merge, and rebase). So that I can preserve the user understanding while enhancing the UX.

The goal is not to introduce new mechanisms, but to improve clarity of existing advice messages, while not only preserving Git's preference for concise output and script-safe behavior but also making the UI more user-friendly for the terminal usage.

A rough draft of the proposal is attached below.

I would greatly appreciate any feedback on whether this direction would be useful.

Thank you for investing time in reading my draft and proposal.

Signed off by: Arsh Srivastava <arshsrivastava00@gmail.com>

Hi Arsh,

It would be better to share the proposal in plain text on the mailing list instead of attaching a PDF. That makes it easier for reviewers to read inline and give feedback directly on specific parts.

Best, Pushkar

Pushkar Singh <pushkarkumarsingh1970@gmail.com> writes:

Thank you so much for the quick reply. The draft is as follows:-

Name and Contact Information:-
Preferred Name: Arsh
Full Name: Arsh Srivastava
Email: arshsrivastava00@gmail.com
GitHub: https://github.com/arshsrivastava00
Micro-Project Contribution: https://github.com/git/git/pull/2233

Title:- Refining Git Advice Messages for Common Error Scenarios

Synopsis :- Git provides guidance through optional advice messages when operations fail or when repository states require user attention. While these hints are technically accurate, some messages assume familiarity with Git concepts and may leave users unsure about the safest next step. This project proposes refining advice messages across common Git commands such as checkout, push, merge, and rebase. The goal is to improve clarity while preserving Git’s philosophy of concise, script-friendly terminal output.

Benefits to the Community:-
- Improve Git’s usability by making advice messages easier to understand.
- Help beginners recover from common errors more confidently and efficiently.
- Maintain concise and safe workflows aligned with Git’s philosophy.
- Improve consistency across Git commands so that they don’t look very long.
- Contribute incremental improvements that can be easily reviewed and
merged upstream

Deliverables:-
- Audit existing advice messages across key Git commands.
- Identify 12–15 scenarios where wording improvements could improve clarity.
- Refine message wording without increasing verbosity.
- Submit a patch series for each improvement.
- Update related tests in the Git test suite.
- Provide documentation updates where needed

Proposed Timeline:- Weeks 1–2: Review advice paths and finalize scenarios. Weeks 3–4: Improve checkout-related advice messages. Weeks 5–6: Improve push-related advice messages. Weeks 7–8: Refine merge and rebase advice. Weeks 9–10: Address remaining scenarios and ensure consistency. Week 11: Documentation and cleanup. Week 12: Address review feedback and finalize patch series. (if the timeline looks longer I considered Hofstadter's law and gave more space so that work is complete on time)

Related Work:- Git already includes an advice system implemented primarily in advice.c and controlled through configuration options such as advice.*. Previous work in the Git project has focused on improving command consistency and repository integrity checks. This project builds on the existing advice infrastructure and focuses on refining message wording rather than introducing new mechanisms which would have complicated the current git advice system even more.

Biographical Information:- I am Arsh Srivastava. I am a developer interested in open-source systems and developer tools. I have also mentored in SWoC and worked on many more open source projects such as google-deepmind and opencv. I am currently in my 3 year of college where I am studying and I have always been curious and am known for good communication skills and for a creative mind.

On Sun, 15 Mar 2026 at 18:01, Pushkar Singh <pushkarkumarsingh1970@gmail.com> wrote:

Pushkar Singh <pushkarkumarsingh1970@gmail.com> writes:

Thank you so much for the quick reply. The draft is as follows:-

Name and Contact Information:-
Preferred Name: Arsh
Full Name: Arsh Srivastava
Email: arshsrivastava00@gmail.com
GitHub: https://github.com/arshsrivastava00
Micro-Project Contribution: https://github.com/git/git/pull/2233

Title:- Refining Git Advice Messages for Common Error Scenarios

Synopsis :- Git provides guidance through optional advice messages when operations fail or when repository states require user attention. While these hints are technically accurate, some messages assume familiarity with Git concepts and may leave users unsure about the safest next step. This project proposes refining advice messages across common Git commands such as checkout, push, merge, and rebase. The goal is to improve clarity while preserving Git’s philosophy of concise, script-friendly terminal output.

Benefits to the Community:-
- Improve Git’s usability by making advice messages easier to understand.
- Help beginners recover from common errors more confidently and efficiently.
- Maintain concise and safe workflows aligned with Git’s philosophy.
- Improve consistency across Git commands so that they don’t look very long.
- Contribute incremental improvements that can be easily reviewed and
merged upstream

Deliverables:-
- Audit existing advice messages across key Git commands.
- Identify 12–15 scenarios where wording improvements could improve clarity.
- Refine message wording without increasing verbosity.
- Submit a patch series for each improvement.
- Update related tests in the Git test suite.
- Provide documentation updates where needed

Proposed Timeline:- Weeks 1–2: Review advice paths and finalize scenarios. Weeks 3–4: Improve checkout-related advice messages. Weeks 5–6: Improve push-related advice messages. Weeks 7–8: Refine merge and rebase advice. Weeks 9–10: Address remaining scenarios and ensure consistency. Week 11: Documentation and cleanup. Week 12: Address review feedback and finalize patch series. (if the timeline looks longer I considered Hofstadter's law and gave more space so that work is complete on time)

Related Work:- Git already includes an advice system implemented primarily in advice.c and controlled through configuration options such as advice.*. Previous work in the Git project has focused on improving command consistency and repository integrity checks. This project builds on the existing advice infrastructure and focuses on refining message wording rather than introducing new mechanisms which would have complicated the current git advice system even more.

Biographical Information:- I am Arsh Srivastava. I am a developer interested in open-source systems and developer tools. I have also mentored in SWoC and worked on many more open source projects such as google-deepmind and opencv. I am currently in my 3 year of college where I am studying B.Tech CSE with minors in AI/ML and I have always been curious and am known for good communication skills and for a creative mind.

On Sun, 15 Mar 2026 at 18:01, Pushkar Singh <pushkarkumarsingh1970@gmail.com> wrote: