Command reference

Every command and option, briefly. New here? The beginner guide explains when to use each command and what to do with the result. gsoc is a shorter alias for git-into-gsoc.

git-into-gsoc --help                   # commands grouped by journey step
git-into-gsoc issues --help            # one command's options
git-into-gsoc --version
git-into-gsoc --install-completion     # tab completion for your shell

How to read the commands:

• Options come after the command, except the top-level --version.
• Data commands accept --output rich (the default, tables and panels) or --output json (for scripts and assistants). doctor, cache, mcp, and --version do not take --output.
• A repository can be written as owner/name, as any GitHub URL, or as the git@github.com:owner/name.git form that git remote -v prints. An issue can be written as owner/name#123, owner/name 123, or any issue or pull request URL, including a link copied from a single comment.
• Uppercase words such as OWNER/REPO, YOUR_USERNAME and NUMBER are placeholders for your own values.
• Nothing here posts to GitHub or submits anything to GSoC. Commands that save do so in a file on your computer, and say so.

Get started

git-into-gsoc            # home: where the program is, your progress, and what to run next
git-into-gsoc start      # four questions, then organizations that fit you

The four questions: your GitHub username (optional; it reads the languages of your public repositories and suggests them), the languages and tools you know, the topics you would enjoy (numbers from a list, or your own words), and hours per week. Run start again whenever your answers change.

Learn and plan

git-into-gsoc proposal draft.md --github YOUR_USERNAME --ideas-file ideas.txt

Notes:

• program reads the year's milestones from the official site. When Google has not published that year, it projects the previous official year forward and marks every date as an estimate with an uncertainty window. When the site is unreachable or does not return a year, it uses an embedded snapshot of the official dates for the years the snapshot holds.
• next combines the program phase and its deadlines, a time budget when your profile has hours per week (hours until the next milestone, split by what the phase needs), your newest 10 tracked issues re-checked live with any status changes (it says how many older ones it left out), pull requests of yours merged since your last check (recorded in your progress, with a word for the first one), new beginner issues in the places you follow, and posts about the coming GSoC in your shortlisted organizations' repositories (an organization whose maintainers say it will not take part becomes the first action). When your profile has a GitHub username, it also sorts your open pull requests in other people's repositories into "needs you" (a merge conflict, a failing check, requested changes with no commit since, a comment with no reply, a draft) and "waiting" (with a nudge to follow up once after five quiet days). Until you shortlist an organization, it names the ones start matched, so the step after start is an org command and not a fresh ranking. --no-check skips the live re-checks. When a check cannot reach GitHub, next keeps the statuses and the check time it saved before, so the next run looks at the same days again.
• proposal FILE never rewrites your draft. It checks for the required sections, counts week-by-week timeline entries and buffer time, looks for concrete references to files, functions, and issues, and lists the generic phrases and leftover placeholders that Google's spam guidance warns about. Linked GitHub pull requests and GitLab merge requests (on gitlab.com or a project's own GitLab) are looked up, so one written by someone else is flagged with --github, and one the draft calls merged but that is open or was closed without merging is flagged too. --ideas-file measures how much of the text is copied from the organization's ideas page. --no-verify skips the lookups. Link text is not a placeholder, and links and fenced code blocks do not count as words.

Discover organizations

git-into-gsoc orgs --tech python,javascript --topics education -n 5
git-into-gsoc orgs --query "symbolic math"
git-into-gsoc org "SymPy"
git-into-gsoc ideas "SymPy" --skills python
git-into-gsoc mentors "SymPy"
git-into-gsoc projects "graph neural networks" --since 2024

Notes:

• --tech and --topics take comma-separated lists in your own words. Synonyms (healthcare finds radiology; web dev, k8s) and common misspellings (pyhton) are understood, and the output says when a word was corrected. Under the table, the top three organizations show their evidence with its source, readiness facts (such as how many ideas state an easy or medium difficulty), caveats, and skills their ideas often ask for that you did not list. When a word matches dozens of organizations ("ai", or "python" alone), a tip suggests narrower words with the count each matches. Fit is not a chance of acceptance; how recommendations work explains the ranking.
• --year defaults to the configured target year. When that year's organizations are not announced, the most recent official list is used and the caption says so. A name that took part in earlier years but is not on the current list gets an explanation instead of an empty table.
• org also lists issues in the organization's repositories whose title names GSoC and the coming year (a preparation tracker, or a notice that it will not take part) and says when a maintainer wrote that it will not take part or has not decided. When GitHub's search limit stops that check, it says so and still shows what the project wiki says, and it shows, with its date, what the monthly check found the organization said.
• ideas reads the page in its most structured form: raw markdown for GitHub wikis and files, the HTML export for Google Docs, the wikitext of a MediaWiki page whose ideas are templates. A table of ideas is read row by row; a table of past years' accepted projects is not. Empty fields were not on the page, and a ? marks a block with no labelled fields, often a section heading rather than an idea. When a page lists each idea as a link to its own page (ML4SCI, CERN-HSF), the table shows that page instead of empty columns. When the page has more ideas than --limit shows, a line under the table says how many there are. When the ideas shown link to more than one GitHub repository, each idea says which one it links to ("links to edulinq/lms-toolkit"; repo in JSON), preferring a repository whose issue it links. An umbrella page that only links to sub-projects is followed, up to 30 pages but never its blog posts or contributors' reports (--no-follow stops that); ideas kept as GitHub issues are read through the issue search; a link that redirects to a wiki's home page is reported as unreachable. The panel quotes any sentence on the page about using AI tools, because policies differ. Ideas are matched to your skills by meaning (reactjs is React; c matches C, not every word with the letter c), each lists the skills it would teach you, and ideas that need more hours than the longest coding period allows (22 weeks) at your hours per week are marked "too big" and listed last. Below the table are links to folders in community archives of accepted proposals for the organization; read them for scope, never copy, and remember they contain personal details.
• mentors reads the official GSoC archive of completed projects, the only public source that names who mentored which project. Names show past mentors, not next year's; make contact in the organization's public channel.

Explore repositories and issues

The repository lookup examples below use SymPy. Replace OWNER/REPO#NUMBER in the last command with the issue you choose.

git-into-gsoc repos "SymPy" --language python
git-into-gsoc repo sympy/sympy
git-into-gsoc issues --language python -n 10
git-into-gsoc issues --repo sympy/sympy
git-into-gsoc issue OWNER/REPO#NUMBER

Notes on repos and repo:

• repos resolves a GSoC organization to its GitHub organizations and reads its ideas page when it can. When the page is an umbrella index (NumFOCUS, for example), it follows up to eight GitHub links and ranks those projects' repositories too, each marked with the page it came from (linked_projects in JSON). When the index links only to project pages on its own site, as UC OSPO's does, it reads those pages and adds up to ten repositories they link to (five without a GitHub token, since each costs one of the 60 requests an hour), one per project first, each marked "Linked from its ... project page". An umbrella with no GitHub organization of its own, such as the Python Software Foundation, gets only the projects its ideas page links to. An organization whose code link is a GitLab group or project (GNOME, GNU Mailman) gets that group's most recently active projects from GitLab's public API, ranked by ideas-page mentions, activity, stars, and language, without beginner-issue counts or outside-contribution checks; repo and orient take a project link on such a host. Any other host gets an error with a link to the ideas page.
• repo samples recent closed pull requests to compute merge rates without bots, and separately for outside contributors. It needs about six API calls, plus one commit listing when some outside pull requests were closed without merging, to find the ones a maintainer committed another way. Pick a repository explains the grade. A project link on a GitLab host (repo https://gitlab.gnome.org/GNOME/gitg) gets the same grade from GitLab's public API: its merged and closed merge requests, with project members and the people who merge as insiders; CONTRIBUTING, Code of Conduct, templates, and .gitlab-ci.yml from its file tree; its license and main language; and open issues under a common beginner label (4. Newcomers, Newcomers, good first issue, Good first issue). The time to a first reply is not read there, so merge times stand in for it. --track saves the link.
• When GitHub does not answer a read, often because of a rate limit, repo leaves the signals that come from it out of the grade and says to run it again later; it does not count them as missing. draft claim then says the project's rule for claiming was not read, instead of saying the project has no contributing guide.

Notes on issues and issue:

• Where it searches: with --repo, that repository; with --org, a GSoC organization's name or a GitHub login (with a name, also the organizations whose repositories its ideas page names, marked "named on the ... ideas page" and listed after the organization's own; when the page names none but links to project pages, as UC OSPO's does, up to eight organizations those pages link to, marked "linked from the ... project pages"; with neither, an organization whose code link is a GitLab group or project, such as GNOME on gitlab.gnome.org or QEMU on gitlab.com, is searched through GitLab's public API: open, unassigned issues carrying a common beginner label (4. Newcomers, good first issue, easy, help wanted, or your --label, spelled exactly as the project spells it), with no language filter, at most three per project, each checked for merge requests; comments there need a sign-in, so an issue with comments shows unknown. Any other host gets an error saying where the code lives). With the default --scope gsoc and neither option, only repositories owned by GSoC organizations that use the language, the organizations whose work matches your interests first; --scope all searches every public repository. With no --language, --org, or --repo, it uses the first language in your saved profile and says so. --language html or css also searches CSS, Vue, JavaScript, and TypeScript repositories, because GitHub tags few web projects as mostly HTML or CSS.
• Which labels: "good first issue" and "help wanted", or the label given with --label. With --repo, also that repository's own beginner labels, up to three ("Easy", "Starter", "🌱 Good first issue"); with --org, also common names such as "starter", "easy", and "beginner". The labels used are labels_used in JSON. A label that only looks like a beginner label does not count: "Good First Issue (Taken)", or Oppia's "Impact: Low -- ONLY DO IF GOOD FIRST ISSUE", which postpones issues.
• What is left out: assigned issues, issues with a linked pull request, archived repositories, and anything not updated in a year. A label such as in progress, claimed, taken, wip, or has-pr counts as a claim even without an assignee. For an issue imported from Jira, as many Jenkins and Apache issues are, a pull request that names the old Jira key (such as JENKINS-43785) counts as linked, at the cost of one extra search. A link to a pull request or commit given as an example does not count.
• How results are ordered: only a beginner label lifts an issue to the top; an issue labelled only "help wanted" scores at most 75, because those are often larger than they look. An issue filed by a maintainer is marked and scores a little higher, since such issues reflect real priorities. Issues open more than two years or labelled backlog score lower. No single organization fills more than three places in a search across several. Each issue says what in it fits your profile ("Names CSS, which you know").
• Cautions: an issue that may not suit a first contribution (a tracker or call for testing, one open for years, one with no beginner label, one several people asked for, one whose label says the project wants no AI-generated work) shows a caution saying why and comes after the issues without one.
• Statuses: the top candidates are verified against their timelines and get a status from available to unknown; find an issue that is free defines each one and says what to do.
• issue adds a caveat when a pull request opened since the issue looks like the same work but never links the issue (one extra search), and names first a label saying the project wants no AI-generated work. A GitLab issue link from any GitLab server (gitlab.com, gitlab.gnome.org, invent.kde.org), or the host/group/project#N form the issues table prints, is checked through GitLab's public API for state, assignees, labels, and merge requests; its comments need a sign-in, so it says to read them yourself, and when the merge requests cannot be read the status is unknown rather than available.
• An issue that a merged pull request says it fixes ("Fixes issue #12", "This should resolve #12") is likely_taken even while it stays open, because GitHub closes an issue only for a few exact phrases merged into the default branch. A merged pull request that only mentions the issue stays a caveat.
• recommend marks a starter issue that someone asked to work on before, with no pull request since, as "asked before", as issues does.
• When nothing turns up, issues says what to try next instead of printing an empty table, with the repository's issues link and, for a GSoC organization, its public chat or mailing list. With --repo, it suggests the owner's other repositories only when it has other active ones, and for a GSoC organization's repository it points to that organization's ideas.

Notes on orient and pointers:

• orient lists the repository's instruction files for AI assistants (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and similar) and reads the first two for policy sentences. Many projects state their AI-use rules there and nowhere else. Read them, and have any assistant you use read them too.
• orient makes about twenty cached GitHub calls and prints facts and paths only: every line names a real file, commit, or check, and the purpose labels on the code map are marked as guesses. Next to the test command it shows the environment CI really sets up, read from the same workflow: runtime versions including matrix values, service containers such as a database, and the systems the jobs run on. Use those versions locally; a README's setup section can be years older than the workflow. It also says when the repository expects a changelog or news entry, from a news-fragment folder such as changelog/ or from the contributing guide and pull request template. A project link on a GitLab host (orient https://gitlab.gnome.org/GNOME/gitg) gets the same sheet from GitLab's public API: the top level of the tree and up to 100 entries in each of its first 20 directories, up to 100 commits from the last 90 days, the branch recent merge requests went to, a gate when the default branch only takes merge requests, and the test commands and runtime images read from .gitlab-ci.yml; a worked-example merge request is not shown there, because its changed files need a sign-in.
• "Before you open a PR" lists the gates GitHub enforces that CONTRIBUTING often leaves out, read from the default branch's active rules (required approvals and code-owner review, required checks, staying up to date, signed commits, linear history, a merge queue) and from workflows that close pull requests without a linked or assigned issue or that check the title. draft pr repeats them. Classic branch protection is visible only to admins, so an empty list means no rulesets were found, not that there are no rules.
• pointers never proposes a fix. It extracts file links, stack-trace frames, paths, and identifiers from the issue and matches them against the repository tree; when the issue names no file, it searches the code for the title's most distinctive words (marked "title words"). Among closed issues with the same beginner label it prefers ones whose titles share words with this issue (the table says "recent" instead of "similar" when none do), finds the pull request merged within seconds of the close (or, with lower confidence, the most recent earlier merge), lists the files it touched, and summarises how many files a typical fix changes and how often fixes touch tests and docs. GitHub code search needs a token and is limited to two calls per run; without a token you get ready-made search links instead. A GitLab issue link gets the same pointers from GitLab's public API: paths resolved against the tree, closed issues with the same label and the merge requests that closed them, and the days each took; code search and the files a merge request changed need a sign-in there (GITLAB_TOKEN with GITLAB_HOST), so without one you get search links and no fix norm.

Get recommendations

git-into-gsoc profile --github YOUR_USERNAME --tech python,c++ --interests science --hours 10 --experience new --tz Asia/Kolkata
git-into-gsoc recommend
git-into-gsoc recommend --tech html,css --interests accessibility --experience new --hours 8

Notes:

• profile --experience new means no pull request merged in someone else's project yet. With --github and no --experience, the level is read from how many of your pull requests were merged in other people's repositories (one GitHub search), and the panel says where it came from. GSoC projects are about 90, 175, or 350 hours over 8 to 22 weeks (GSoC FAQ); when your hours per week are too few for a size, profile and next say which sizes fit.
• recommend uses the saved profile when you give no options, saves the skills and interests you give so the next run matches, and takes --experience and --hours as one-run overrides. With a GitHub username it reads your recent public repositories to infer your main language. It prints whether the organizations are confirmed for the coming year (until Google announces the list, none is); the organizations that fit, with evidence, readiness facts, caveats, and skills to learn for the top three; ideas that fit you from each top organization's latest ideas page, leaving out ideas too big for your hours; starter issues from those organizations (and, when they have fewer than three, from other GSoC organizations that use your first language), leaving out issues someone is already working on and saying how many; and a path from where you are that changes with your experience and hours. The top five organizations (three without a GitHub token) are checked for posts about the coming year, and one that says it will not take part is marked "sitting out" and moved last. How recommendations work has the sources, the ranking, and how it was measured.

Write and keep evidence

git-into-gsoc contributions --github YOUR_USERNAME --org "SymPy"
git-into-gsoc draft claim --issue OWNER/REPO#NUMBER
git-into-gsoc log --goal "Reproduce #NUMBER" --done "Reproduced on main" --stuck "Flaky test" --next "Ask in Zulip"

Notes:

• contributions counts public activity only, through GitHub searches (what it searches).
• diagnose knows these shapes: a missing module, a name missing from an installed module (a build left behind after a pull, or a dependency at another version), the wrong runtime version, a missing compiler or C headers, a service such as a database not running, a missing environment variable, a missing command, permissions, the network, a port in use, a lock-file mismatch, memory, a failed style or lint check, and failing tests. It reads logs copied from GitHub Actions or gh run view --log as they are.
• pr-check looks for a merge conflict, failing checks (GitHub's check runs, and the commit statuses that CI such as Prow and Jenkins report instead, with a link to each failing log), a linked issue (a failure when a workflow closes pull requests without one), a description, the template checklist, AI disclosure when the template asks, commit sign-off when the project requires it, commit style, tests changed alongside code, a changelog entry when one is expected, and size.
• diagnose given a GitHub Actions log also quotes what the failing step printed, its red lines first, because projects often explain their own checks there.
• pr-check with a GitHub token reads the end of up to two failed CI logs and quotes what the failing step printed, such as a project's own explanation and the link it gives. Without a token, or when GitHub no longer keeps a log, it says why the log was not read.
• draft fills in real context when you give it: the organization's channels; the project's claim convention read from its CONTRIBUTING (a /assign command, a .take command, "we do not assign issues", or "wait until you are assigned"), shown as the first rule with the link, or a plain note when the guide says nothing about claiming; whether commits need a sign-off or the pull request template asks for an AI disclosure; the issue's availability; and your latest note for a status post. The general rules after the project's own come from projects that wrote them down, such as pandas and Kubernetes. The pr draft ends with the exact commands for a first pull request (clone your fork, add the upstream remote, branch from the real default branch, run the tests, push). It never fills placeholders with observations you have not made. With --check, the message you wrote is checked for leftover placeholders (HTML tags such as <details> are not placeholders), phrases that read as machine-written, a greeting with nothing else, a question with no question, a bare "can I work on this", and a pull request description with no linked issue or testing note.
• draft claim for an issue that someone asked to work on before, with no pull request since, opens by asking that person whether they are still on it. With three or more earlier requests, it warns you to lead with a plan instead of another request.
• log follows the three questions GSoC organizations ask for in weekly updates. Each field holds up to 2,000 characters, and links must be web addresses. next reminds you when the last note is a week old.

Save local progress

git-into-gsoc progress summary
git-into-gsoc progress note --value "Next: read the contribution guide."

-v is short for --value. Saving actions print Saved. and the summary; with --output json, a saving action prints the whole saved state. A value that is not a repository or an issue is refused rather than saved. See keep track of your progress.

Setup and maintenance

git-into-gsoc setup                               # every assistant found, user scope
git-into-gsoc setup --dry-run --assistant all     # preview every assistant
git-into-gsoc setup --scope project --assistant claude-code --assistant cursor

Setup merges into existing JSON and TOML files rather than replacing them. In its own git-into-gsoc entry it changes only the command and the settings it needs, so settings you added there, such as env or disabled, stay. It writes a .bak copy first, refuses to touch a file it cannot parse, and reports unchanged on re-runs. With --scope project, it never follows a symbolic link (a file that points somewhere else) inside the project, so a cloned repository cannot steer it into other folders; that file or folder is reported as skipped. An assistant it cannot configure gets a printed manual command. Use it in your AI assistant covers each assistant; configuration covers tokens and settings.

Use output in a script

git-into-gsoc issues --language rust -n 5 --output json > issues.json
git-into-gsoc repo sympy/sympy --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['health']['grade'])"

Successful JSON goes to standard output. Expected failures print error: ... and usually a hint: ... line to standard error and exit with code 1; these errors are not JSON. Invalid command syntax exits with code 2, and a missing argument shows an example to type. One exception: when org, ideas, mentors, or projects --org cannot find the organization, --output json prints the result with found: false, error, and hint to standard output, and still exits with code 1. A successful command can still return data such as availability unknown, so inspect the result as well as the exit code.

Configuration · Troubleshooting · Guide contents

Source: docs/cli.md on GitHub. Corrections are welcome.