Skip to content

Latest commit

 

History

History
552 lines (470 loc) · 38.9 KB

read-git.md

File metadata and controls

552 lines (470 loc) · 38.9 KB
id GIT
title read_git
status normative
governs
crates/agent/src/git.rs
crates/agent/src/git/config.rs
crates/agent/src/git/dates.rs
crates/agent/src/git/declined.rs
crates/agent/src/git/diff.rs
crates/agent/src/git/log.rs
crates/agent/src/git/objects.rs
crates/agent/src/git/out.rs
crates/agent/src/git/resolve.rs
crates/agent/src/git/revision.rs
crates/agent/src/git/search.rs
crates/agent/src/git/show.rs
crates/agent/src/git/status.rs
crates/agent/src/git/survey.rs
crates/agent/src/git/tags.rs
crates/agent/src/workspace.rs
crates/agent/src/tools.rs
crates/agent/src/tools/offered.rs
crates/core/src/policy.rs
documented-by docs/website/docs/reference/tools.md

Scope

Reading a repository's history from the files under its .git, and its status from those and the working tree, without starting git. query, repository, revision, path, pattern, since, until, count, skip and messages are routing: the first names which question is asked, the next four name which repository, which commits, which files and which lines it is asked about, and the rest bound what a log, a list of tags or a search lists and how much of each it prints. The only content argument is the why every tool takes (TOOL-5). The result is the answer, or a reference where a path it showed is untrusted. What it shows is scanned for credentials before the planner receives it, as a file read is (credential-protection.md): the lines it prints of a file are scanned as a read of that file, one side of a diff at a time and from the line they start at, and the rest of the answer as a read of .git. A person agreeing to be shown one file's key has agreed to nothing about another's.

Clauses

GIT-1: history is read from the files under .git, and no program is started

log lists commits one per line, newest first: the first ten characters of the id, the day it was authored, its author and its subject, as git log --format='%h %ad %an %s' --date=short --abbrev=10 prints them, and asked for messages, the rest of each message beneath its line (GIT-12). show prints a commit with its message and its diff as git show does, a tag with its message and then its commit, and <revision>:<path> as the file or directory stood at that revision. diff compares two commits' trees as git diff prints them. How far apart a file's changes lie does not count against matching its two sides line by line. That takes at most four million steps, a step being one comparison of two lines or one line read, and a search for a shortest edit is given up past a thousand edits. A file that exceeds the bound is described by a notice in place of hunks. The notice names the lines the sides differ between, the lines within those that could not be matched, and the most lines they could have removed and added, numbered as the files number them. A diff compares only the lines between the first line that differs and the last, with three lines of context kept at either end, so what a diff costs follows the change and not the file (GIT-9). Revisions are read in git's syntax, as git resolves them: names, ids and their prefixes, ~N, ^N, ^{commit} and ranges. A...B is what each side has that the other lacks: a diff compares the merge base of the two with B, as git diff A...B does, and a log lists the commits reachable from either and not from both, as git log A...B does. Where the two have several merge bases, a diff measures from the most recent one, and a log leaves out what every one of them reaches. Two histories with no commit in common are refused by name. Loose and packed objects, deltas included, read the same.

What each question means is fixed by this reader. No key in the repository's configuration names a program it runs, a driver it applies or a filter it passes bytes through, and no remote URL is ever part of an answer. A merge is shown without a diff and names the diff to ask for, a binary file is described by its size, a submodule is shown as the commit it records, and a shallow commit is read as a root, as git reads it.

Why. git runs what its configuration names: core.fsmonitor on a status, gpg.program on a log that shows signatures, a pager and an alias on anything, and include.path pulls that configuration in from any file. The configuration is part of the tree being inspected, so running git over an unknown repository is running a program somebody else wrote, which is why command-line.md keeps git on the road where a person vouches for it. A reader whose behaviour no file can change answers the common question, what happened in this history, with nobody asked.

Built on gitoxide's plumbing crates for hashes, objects, packs and refs, none of which starts a process. The history walk, the tree diff and the line diff are written here, and .config/deny.toml bans the gix crates that start one. gix-path, which those crates depend on, has a module that starts git and sh; nothing calls it, and SANDBOX-30 records the test that fails if anything does.

verified-by: bravebot_agent::turn::read_git_shows_the_planner_the_history_of_a_trusted_repository verified-by: bravebot_agent::git::log_lists_commits_newest_first_one_line_each verified-by: bravebot_agent::git::show_prints_a_commit_its_message_and_its_diff_as_git_does verified-by: bravebot_agent::git::show_lists_a_directory_and_prints_a_file_at_a_revision verified-by: bravebot_agent::git::diff_compares_two_commits_as_git_diff_prints_them verified-by: bravebot_agent::git::edits_far_apart_in_a_long_file_are_two_hunks verified-by: bravebot_agent::git::a_stretch_that_cannot_be_lined_up_is_named_by_its_lines verified-by: bravebot_agent::git::revisions_resolve_through_names_ancestry_and_peels_as_git_does verified-by: bravebot_agent::git::ranges_and_pairs_are_read_as_git_reads_them verified-by: bravebot_agent::git::a_range_leaves_out_what_its_start_already_reaches verified-by: bravebot_agent::git::a_range_leaves_out_its_start_whatever_the_commit_times verified-by: bravebot_agent::git::a_symmetric_range_measures_from_the_merge_base verified-by: bravebot_agent::git::a_symmetric_range_over_a_criss_cross_history_is_read_as_git_reads_it verified-by: bravebot_agent::git::a_symmetric_range_with_no_common_ancestor_is_refused_by_name verified-by: bravebot_agent::git::a_path_after_a_revision_is_read_as_a_name_whatever_it_holds verified-by: bravebot_agent::git::a_path_keeps_only_the_commits_that_changed_it verified-by: bravebot_agent::git::a_log_narrowed_to_a_path_follows_the_side_a_merge_kept_it_from verified-by: bravebot_agent::git::bytes_that_are_not_utf8_are_shown_escaped_and_diffed_as_bytes verified-by: bravebot_agent::git::a_tag_is_shown_with_its_message_then_its_commit verified-by: bravebot_agent::git::a_merge_is_shown_without_a_diff_and_names_the_diff_that_gives_one verified-by: bravebot_agent::git::a_binary_file_is_described_rather_than_printed verified-by: bravebot_agent::git::a_submodule_is_shown_as_the_commit_it_records_and_not_read verified-by: bravebot_agent::git::a_shallow_commit_is_read_as_having_no_parents verified-by: bravebot_agent::git::a_signature_time_is_shown_in_its_own_zone verified-by: bravebot_agent::git::objects_in_a_pack_and_stored_as_deltas_read_as_loose_ones_do verified-by: bravebot_agent::git::a_configuration_naming_programs_and_remotes_changes_no_answer_and_runs_nothing

GIT-2: a repository is opened only where the trust map trusts all of its .git

The map is asked about .git as a subtree, so a rule distrusting one file anywhere beneath it, a pack somebody fetched or a ref somebody else wrote, keeps the repository closed. Nobody having said anything about a repository is not trust in it. The question is asked of the name the planner wrote and the rules alone, before any file under .git is read, and a repository it fails is refused with a sentence pointing at run, where the turn is offered one.

The files a read opens are listed before any of them is decoded, and that list is what the rules are held against. A file a read opens is on it; a file no read opens is not. That is the configuration, whatever case its name is written in, the refs a name can reach, which leaves out a .lock and any name with a part starting ., the loose objects, and each pack index with the pack beside it. A status adds the index, info/exclude and info/attributes. A listing that runs past the search deadline is declined as a read out of time is.

Why. Reading history means following ids the files hold: a ref naming a commit, a commit its parent and its tree, a tree its entries. Following them over bytes nobody vouched for is the driver branching on untrusted content, which labels.md admits nowhere.

Why this does not contradict command-line.md. There, .git/config is never read to decide how a command is routed, because it is content nobody vouched for. Here nothing under .git is read until the map vouches for all of it, and the configuration then decides only whether this reader declines (GIT-8), never what it runs.

verified-by: bravebot_agent::turn::read_git_does_not_open_a_repository_nobody_vouched_for verified-by: bravebot_core::policy::a_repository_is_trusted_beneath_only_where_nothing_inside_it_is_distrusted verified-by: bravebot_core::policy::a_repository_nobody_vouched_for_is_not_trusted_beneath verified-by: bravebot_agent::git::survey_lists_the_files_a_read_opens_and_none_it_does_not verified-by: bravebot_agent::git::status_surveys_the_index_and_the_info_files_it_reads verified-by: bravebot_agent::git::a_name_under_git_in_another_case_is_listed_as_the_reader_spells_it verified-by: bravebot_agent::turn::a_distrusted_file_deep_under_git_keeps_the_repository_closed

GIT-3: an answer is labelled by the whole of .git and by every path it showed

A path it showed is the working-tree path of a file whose history the answer printed, spelled from the workspace root, so a repository in sub shows sub/<path>. An answer showing a path the map distrusts is as untrusted as that file, and reaches the planner as a reference, however trusted the .git it came out of. A log naming no path showed none and is labelled by .git alone.

Only an answer labelled trusted is examined for credentials. If the driver may not examine an answer, which happens only if the trust map changes between the label and the examination, the refusal is worded by the driver (TOOL-6): it says the answer is closed to read_git, prints the label, and names run only where the turn is offered it and the person vouching for the repository on every turn. A turn offered no run is told that only the person can open it. The tool returns no reference at that point, so the refusal does not say to use one, and it holds no byte of the answer.

A path is held against the map only where it names one file one way. A path written through .., . or a doubled slash is refused, a tree entry git would not check out, .. or a name holding a /, is not read, a name that is not UTF-8 is left out as GIT-4 leaves out a withheld one, and a tree or file named by its id alone, with no path, is refused.

Why. A blob holds the bytes of the file it committed. Labelled by where it was stored rather than by what it holds, a file the map distrusts would reach the planner through its history.

verified-by: bravebot_agent::turn::a_history_answer_showing_a_distrusted_path_is_quarantined verified-by: bravebot_agent::tools::tests::untrusted_refusals::the_git_refusal_names_run_only_where_the_turn_holds_it verified-by: bravebot_agent::tools::tests::untrusted_refusals::an_untrusted_git_answer_is_refused_in_the_helpers_words verified-by: bravebot_agent::workspace::a_repository_below_the_root_is_read_under_the_rules_on_its_own_path verified-by: bravebot_core::policy::a_repository_answer_is_untrusted_where_a_path_it_showed_is verified-by: bravebot_core::policy::a_repository_answer_is_untrusted_where_anything_under_git_is verified-by: bravebot_agent::git::a_path_not_plainly_inside_the_repository_is_refused verified-by: bravebot_agent::git::a_tree_entry_whose_name_would_leave_its_directory_is_not_read verified-by: bravebot_agent::git::a_path_whose_name_is_not_utf8_is_left_out_as_withheld verified-by: bravebot_agent::git::a_tree_or_file_named_by_its_id_alone_is_refused

GIT-4: a deny rule over a file covers its history

A file the question names, by path or by <revision>:<path>, is refused under a deny rule as a read of it is, before anything under .git is opened. A file a rule covers that an answer would otherwise show, in a diff, a listing, a search or a log narrowed to it, is left out, and the answer says something was left out.

A rule covering .git or any file beneath it keeps the repository closed. read_git reads every file there or none.

Neither refusal says to read it with git instead, although git would print the bytes. A rule over a path does not cover a command line, so the sentence would be the way round the rule that this clause closes, and which paths a command line may reach is the permission rules' question rather than this reader's.

Why. Otherwise show HEAD:.env is the way round every rule on .env. The repository closes whole because a history with the denied file's objects removed is not one this reader can walk: which object a file holds is not known until it is read.

verified-by: bravebot_agent::git::a_refusal_a_deny_rule_caused_points_at_nothing_else verified-by: bravebot_agent::turn::a_deny_rule_over_a_file_refuses_reading_its_history verified-by: bravebot_agent::turn::a_repository_holding_a_file_a_deny_rule_covers_is_not_opened verified-by: bravebot_agent::workspace::a_repository_a_deny_rule_names_is_not_opened verified-by: bravebot_agent::workspace::a_rule_over_the_file_a_symlinked_repository_lands_on_leaves_it_out_of_a_commit verified-by: bravebot_agent::workspace::a_rule_over_a_git_file_a_symlinked_repository_lands_on_keeps_it_closed verified-by: bravebot_agent::git::a_withheld_path_is_left_out_of_every_answer_and_the_answer_says_so verified-by: bravebot_agent::git::a_withheld_path_is_neither_read_nor_listed verified-by: bravebot_agent::turn::a_named_file_a_deny_rule_covers_is_refused_before_the_repository_is_opened

GIT-5: the question is log, show, diff, status, tags or search, and anything else is refused by name

A word off the list is refused and the planner is told to use run, where the turn is offered one. A revision form this reader does not implement, HEAD^@ or @{upstream} among them, is refused by name, and a query given the other shape of revision, one where it takes two or two where it takes one, is told which query takes it. A status given a revision is told to use diff. A pattern given to anything but search, a search given none, an empty one or one that is not a regular expression, and a list of tags given a path are each refused by name.

Why. A guess answers a question the planner did not ask as though it had. HEAD^@ read as the forms this reader knows is HEAD^, so it would come back as a confident answer to something else. A pattern or a path dropped without a word is the same guess: a log with its pattern dropped is every commit, read as the ones that matched.

verified-by: bravebot_agent::tools::tests::arguments::a_query_off_the_list_names_run_only_where_the_turn_holds_one verified-by: bravebot_agent::turn::read_git_answers_status_and_refuses_a_query_off_the_list verified-by: bravebot_agent::turn::read_git_searches_the_files_at_a_revision_and_pages_the_lines verified-by: bravebot_agent::turn::read_git_lists_the_tags_a_revision_reaches_newest_version_first verified-by: bravebot_agent::git::revision_syntax_read_git_does_not_implement_is_refused_by_name verified-by: bravebot_agent::git::a_query_given_the_wrong_shape_of_revision_says_which_query_takes_it verified-by: bravebot_agent::git::a_pattern_is_for_search_alone_and_tags_take_no_path

GIT-6: since and until are whole days in UTC

Both ends are included: until reaches the last second of its day. A value that is not a day on the calendar, written YYYY-MM-DD, is refused with the form it takes.

Why. A planner asking for commits since the 15th means the whole of the 15th, and a day like 2023-02-30 read leniently lands on a neighbouring one with nobody told.

verified-by: bravebot_agent::turn::since_and_until_are_whole_days_and_anything_else_is_refused verified-by: bravebot_agent::git::since_and_until_bound_the_log_by_whole_days verified-by: bravebot_agent::git::only_a_real_calendar_day_is_read_as_one verified-by: bravebot_agent::turn::since_and_until_include_the_first_and_last_second_of_their_day

GIT-7: a git run whose output is sealed names read_git

Where a stage of a run was git, its output could not be shown to the planner, and read_git opens the repository git finds from the directory that stage worked in, for a question about history, the result says once that read_git reads history with nobody asked in a trusted repository. A stage works in the directory the line ran in, moved by each -C that leads its arguments. The repository git finds is in the nearest directory at or above that one, inside the session's directory or one the person added, that holds a .git. A stage that names its repository by --git-dir, --work-tree or GIT_DIR is judged by the directory it worked in.

A run of any other program says nothing about it, and neither does a git run whose repository read_git declines: a .git that is a file (GIT-8), which includes a directory below a linked worktree, a repository the map does not trust or a rule covers (GIT-2, GIT-4), or a repository read_git cannot be asked for by name, because the name is not text or lies under a directory named ~. A delegate's checkout, whose .git is also a file, is a repository read_git opens (CHECKOUT-12).

Whether read_git opens the repository is decided by the opener a read_git call goes through. The checks a call makes on the name it was given before it reaches the opener are not made. Nothing under .git is read until the map has vouched for all of it (GIT-2).

Why. A planner that ran git and got a sealed result does not otherwise learn that the question has an answer it can read. Said after every run, the sentence would be noise the planner learns to skip. Said after a run in a repository read_git declines, it names a call that is refused, and the planner then spends a round on that call before it asks run again.

verified-by: bravebot_agent::turn::a_sealed_git_run_names_read_git_and_another_programs_does_not verified-by: bravebot_agent::turn::a_sealed_git_run_in_a_subdirectory_of_a_repository_names_read_git verified-by: bravebot_agent::turn::a_sealed_git_run_in_a_linked_worktree_does_not_name_read_git verified-by: bravebot_agent::turn::a_sealed_git_run_in_a_repository_nobody_vouched_for_does_not_name_read_git verified-by: bravebot_agent::turn::a_sealed_git_run_is_judged_by_the_directory_dash_c_names verified-by: bravebot_agent::workspace::read_git_opens_the_directories_a_question_would_open verified-by: bravebot_agent::workspace::read_git_opens_a_repository_in_a_directory_that_was_added verified-by: bravebot_agent::workspace::read_git_opens_no_repository_whose_name_is_not_text verified-by: bravebot_agent::workspace::read_git_opens_no_repository_under_a_directory_named_tilde

GIT-8: a repository whose files change what a read means is declined, not followed

Declined, with a sentence pointing at run where the turn is offered one:

  • a .git that is a file, or that holds a symbolic link where a read goes
  • objects borrowed through objects/info/alternates, refs and objects shared through commondir, and objects replaced or parents grafted through refs/replace or info/grafts
  • configuration that includes another file, sets core.worktree, or names a repository format or an extension this reader does not know, in the shared file or the per-worktree one
  • a ref under worktrees/ or main-worktree/, which lives in another worktree's directory
  • symbolic refs that point at each other

Configuration git reads without changing what history means is read, whatever its comments, quoting, line endings and continued lines.

CHECKOUT-12 opens one kind of linked worktree: a delegate's checkout, found from the driver's own record of it and never from its .git file.

The description of read_git says that it declines the .git file a linked worktree or a submodule has, except at the root of a checkout the delegate was started in. A planner working in a linked worktree then goes to run first, or learns that no tool on its list reads that history where it holds none.

Why. Each of these sends a read to files the list in GIT-2 does not hold, or answers with objects other than the ones stored. Past any of them this reader answers a different question from the one git would, and the rules were held against files it did not read.

verified-by: bravebot_agent::git::a_repository_whose_files_send_a_read_elsewhere_is_declined verified-by: bravebot_agent::git::a_symbolic_link_where_a_read_goes_is_declined_rather_than_followed verified-by: bravebot_agent::git::configuration_that_changes_what_a_read_means_is_declined verified-by: bravebot_agent::git::configuration_git_reads_to_the_same_meaning_is_accepted verified-by: bravebot_agent::git::the_per_worktree_configuration_is_held_to_the_same_rules verified-by: bravebot_agent::git::a_ref_in_another_worktrees_directory_is_never_read verified-by: bravebot_agent::git::a_loop_of_symbolic_refs_is_declined verified-by: bravebot_agent::tools::read_git_says_a_dot_git_that_is_a_file_is_declined verified-by: bravebot_agent::git::a_configuration_naming_programs_and_remotes_changes_no_answer_and_runs_nothing

GIT-9: an answer is bounded, and one that stopped short says so

A log lists 20 commits, a list of tags 20 tags and a search 20 lines unless the planner names a count, and never more than 200. An answer holds at most 2,000 lines and each line at most 2,000 characters. A file past 1 MiB is described by its size, read from the object's header alone, and not searched. A diff reads a file up to 4 MiB: it compares only the lines between the first line that differs and the last, so a one-line change in a file of 1.6 MB prints its hunk at the line numbers the file has. A side past 4 MiB is described by its size and not diffed. A higher cap for a diff only, over the region the sides differ in, was chosen over a cap of the region alone because finding the region reads both sides whole, so a bound on what a diff holds has to be on the size of a side, and 4 MiB holds the sides, their escaped copies and one entry per line of the region. An answer stops at the search deadline. An answer cut by any of these says it was cut, and one that was not makes no such claim. A status that stops at the deadline says it can be narrowed with a path and that search.maxSeconds sets the deadline, and names git status through run where the turn holds run. It does not suggest a range or a count, which a status does not take. The description of a file past the size cap, in a diff, a show of a commit and a search as in a show of a file, names what can still read it from the tools the turn's list holds: read_file on the working copy, run, both, or neither (TOOL-6). The words depend on the turn's list and the size in the header, never on a byte of the file.

Why. A repository's history is as large as the repository, and a planner handed part of it as though it were the whole draws conclusions from what is missing.

verified-by: bravebot_agent::git::a_log_that_reaches_its_count_stops_and_says_it_was_cut verified-by: bravebot_agent::git::an_answer_past_its_lines_or_a_line_past_its_width_is_cut verified-by: bravebot_agent::git::a_file_past_the_size_cap_is_described_by_its_size verified-by: bravebot_agent::git::a_changed_line_in_a_file_past_the_size_cap_is_diffed_at_its_own_line_numbers verified-by: bravebot_agent::git::a_change_in_the_middle_of_a_large_file_keeps_its_line_numbers verified-by: bravebot_agent::git::a_large_file_added_deleted_or_binary_is_diffed_as_a_small_one_is verified-by: bravebot_agent::git::the_notes_for_a_file_past_the_diff_and_search_caps_name_only_the_tools_the_turn_holds verified-by: bravebot_agent::git::a_read_out_of_time_says_so verified-by: bravebot_agent::tools::a_status_out_of_time_names_what_narrows_a_status_and_a_log_keeps_its_advice verified-by: bravebot_agent::git::a_listing_or_a_diff_that_fills_the_answer_says_it_was_cut_only_when_more_was_left verified-by: bravebot_agent::turn::a_log_lists_twenty_commits_unasked_and_never_more_than_two_hundred

GIT-10: status lists what git status --short --no-renames lists

Staged changes compare the index with the tree at HEAD, unstaged ones the working tree with the index, and untracked paths follow, sorted, each as XY path the way git prints them. A conflict is coded by the stages the index holds (UU, AA, DU and the rest), a file added with intent is A, or D once its file is gone or a directory stands in its place, and a directory holding nothing tracked is one line, dir/, or none where everything in it is ignored. A nested repository, a directory whose .git is a file or holds a HEAD, reached through a symbolic link or not, is one line too. Only files and symbolic links are listed, never a fifo or a socket, and status.showUntrackedFiles is read: no lists nothing untracked, and all lists each file rather than its directory. A path filter lists that path and what is beneath it, not the directories above it. A path holding a space, a quote, a backslash, a control character or, with core.quotePath on as it is by default, a byte past ASCII is quoted as git quotes it. A tree where nothing changed says so, and where the trust map withheld a path, says only that nothing changed among the paths it could read.

A file whose stat data matches the index is taken as unchanged unless the index was written no later than the file last changed, or the entry records a size of zero for content that is not empty, as git takes it; any other file is read and hashed. A symbolic link is compared by where it points, the executable bit counts where core.filemode says it does, a submodule replaced by a file is a type change, and a path under a directory that is now a symbolic link is deleted rather than followed. Ignore files are read as git reads them, per directory with info/exclude beneath them, and so are attributes files. A file an attribute or core.autocrlf would convert on its way into the index, and a submodule, is listed under a heading as not compared rather than guessed at. The heading points at git status through run only where the turn's list holds run (TOOL-6). An ignore or attributes file the trust map withholds is not guessed at either: nothing untracked beneath a withheld ignore file is listed, though an untracked directory holding one is, as git lists it for the ignore file itself, and a withheld attributes file leaves every file beneath its directory whose stat data changed not compared. A rule withholding a name counts only where a file stands at it, and a withheld ignore file counts only where untracked files are listed. A file replaced between being looked at and being read is not compared either, and is never followed through a link or waited on as a fifo. Renames are not detected. Nothing is written, the index included.

Declined, with a sentence pointing at run where the turn is offered one: a split or sparse index, one holding an extension this reader does not know that git would need, one whose checksum does not match, one naming a path git would not check out, a repository whose configuration sets core.bare, and one that names an ignore or attributes file outside it through core.excludesFile, core.attributesFile or attr.tree. The global and system configuration and the global ignore file are not read, so on Windows, where Git for Windows sets core.autocrlf in the system file, line endings are taken as converted unless the repository's own configuration says they are not.

Why. Status is the question a planner asks most, and the one git answers by running what core.fsmonitor names. Where this reader cannot tell what git would print, it says so rather than printing something else: a filter or line-ending conversion changes the bytes a file is hashed as, and an index this reader does not parse in full lists entries it cannot see.

verified-by: bravebot_agent::git::status_lists_staged_unstaged_and_untracked_as_git_status_short_does verified-by: bravebot_agent::git::a_clean_tree_says_so_and_a_version_four_index_reads_the_same verified-by: bravebot_agent::git::matching_stat_data_is_trusted_unless_the_index_is_as_new_as_the_file verified-by: bravebot_agent::git::a_merge_conflict_is_coded_by_the_stages_the_index_holds verified-by: bravebot_agent::git::a_file_an_attribute_converts_is_not_compared verified-by: bravebot_agent::git::a_link_above_a_tracked_file_is_not_followed verified-by: bravebot_agent::git::an_untracked_directory_is_one_line_and_one_of_only_ignored_files_is_none verified-by: bravebot_agent::git::a_changed_executable_bit_is_a_change verified-by: bravebot_agent::git::a_layout_status_cannot_read_as_git_would_is_declined verified-by: bravebot_agent::git::a_path_with_a_space_is_quoted_as_git_quotes_it verified-by: bravebot_agent::git::paths_are_quoted_and_filtered_as_git_quotes_and_filters_them verified-by: bravebot_agent::git::an_intent_to_add_entry_whose_file_is_gone_is_a_deletion verified-by: bravebot_agent::git::a_replaced_submodule_a_smudged_entry_and_a_socket_read_as_git_reads_them verified-by: bravebot_agent::git::status_show_untracked_files_is_read_from_the_config verified-by: bravebot_agent::git::a_git_file_makes_a_nested_repository_and_a_quote_or_backslash_is_escaped verified-by: bravebot_agent::git::a_withheld_attributes_or_ignore_file_is_not_guessed_at verified-by: bravebot_agent::git::a_withheld_rule_counts_only_where_a_file_it_withholds_is_read verified-by: bravebot_agent::git::the_not_compared_heading_names_run_only_where_the_turn_holds_it verified-by: bravebot_agent::git::the_note_for_a_file_past_the_size_cap_names_only_the_tools_the_turn_holds verified-by: bravebot_agent::turn::read_git_answers_status_and_refuses_a_query_off_the_list

GIT-11: status is answered only where the trust map trusts the whole working tree

The map is asked about the repository's directory as a subtree, as GIT-2 asks about .git, and a tree it fails is refused with a sentence pointing at run where the turn is offered one. log, show and diff in the same repository are answered as before.

Why. Status reads every file in the tree: it hashes their bytes, reads their ignore and attributes files, and prints their names. Each of those is the driver branching on the file, so a file nobody vouched for keeps status closed, as a pack nobody vouched for keeps the repository closed.

verified-by: bravebot_agent::turn::status_is_answered_only_where_the_whole_working_tree_is_trusted verified-by: bravebot_agent::workspace::a_status_below_the_root_is_asked_about_its_own_directory

GIT-12: a log is read a page at a time, with whole messages where asked

skip passes over that many of the commits a log matches before it lists any, as git log --skip does. It counts the commits the log would list once its range, path and days are applied, not the commits walked on the way to them. A log that stopped with commits still to list, at its count or at its lines, names the skip that lists the next of them, and one that listed its last commit names none.

With messages, each commit's line is followed by the rest of its message, every line indented four spaces as git show indents it, so a line that is not indented starts a commit. A commit goes on a page whole or waits for the next one. The exception is a commit whose message alone is longer than an answer, which is shown as far as it fits and cut, so that the next skip moves past it.

Why. A commit's body is where it says why it was made and what it closes, and a history longer than one answer is common. A planner given neither reruns git through run, where the answer may be sealed, or narrows the question until commits drop out of it. A skip that counted walked commits would pass over a different set from the one the planner was shown, and a message cut at the foot of a page would be read as the whole of it.

verified-by: bravebot_agent::turn::read_git_pages_through_a_log_and_shows_whole_messages_when_asked verified-by: bravebot_agent::git::a_log_with_messages_prints_each_commit_whole_beneath_its_line verified-by: bravebot_agent::git::skip_passes_over_the_commits_a_log_already_listed verified-by: bravebot_agent::git::a_page_of_messages_ends_at_a_whole_commit

GIT-13: tags are listed newest version first, and with a revision only those it reaches

tags lists the repository's tags, loose and packed alike and a loose one over a packed one of the same name, in the order git tag --sort=-v:refname lists them: a run of digits is compared as a number, so v0.10.0 comes before v0.9.0. Each line is the tag's name and the commit it names as a log prints it, or for a tag that names a tree or a file, its id and what it is. Given a revision, only the tags whose commit that revision's history holds are listed, as git tag --merged lists them, and a tag naming no commit is not. A list of tags shows no path and is labelled by .git alone. It pages by count and skip as a log does (GIT-12), naming the skip that lists the next of them.

Why. Where the last release ended is the newest tag the history being released holds. Sorted as names, v0.9.0 would be taken as newer than v0.10.0, and without a revision a tag on another branch would be taken as the one before this release.

verified-by: bravebot_agent::turn::read_git_lists_the_tags_a_revision_reaches_newest_version_first verified-by: bravebot_agent::git::tags_are_listed_newest_version_first_loose_and_packed_alike verified-by: bravebot_agent::git::tags_given_a_revision_are_only_those_its_history_holds verified-by: bravebot_agent::git::tags_page_by_count_and_skip

GIT-15: staged is a question only the driver asks, and no tool argument names it

staged prints what the index holds that HEAD does not, as git diff --cached --no-renames prints it: the hunks of each path that was added, changed or deleted in the index, as diff prints them for two trees. Nothing is read from the working tree. A path in conflict and a path marked only with git add -N hold no staged content, so a conflicted path is named on a line of its own and neither is given hunks. An index that matches HEAD says nothing is staged. It is labelled as every other answer is (GIT-3), by the whole of .git and by each path it showed, and a path the trust map withholds is left out and the answer says so.

Query::named does not return it, so query has no value that asks for it and the planner is not offered it. It exists for /commit-message (CMD-23), which asks it of the working directory's own repository.

Why. A draft of a commit message needs what is about to be committed, and status lists paths without their changes and diff compares only commits. Offering the question to the planner would widen a tool nobody asked to widen.

verified-by: bravebot_agent::git::staged_prints_the_index_against_head_and_not_the_working_tree verified-by: bravebot_agent::git::staged_says_so_when_the_index_matches_head verified-by: bravebot_agent::git::staged_leaves_out_a_withheld_path_and_says_so verified-by: bravebot_agent::git::staged_names_a_conflicted_path_and_prints_no_hunks_for_it verified-by: bravebot_agent::git::the_staged_question_is_not_one_a_tool_can_name verified-by: bravebot_agent::commit_message::the_staged_source_is_drafted_from_the_index_and_not_the_working_tree

GIT-14: a search is labelled by every file it read, matched or not

search prints the lines of the files at one revision, HEAD unless another is named, that pattern matches, as git grep -n prints them: path:line:text, with the text following the colon byte for byte, in the order git lists the tree, with a binary file that matches named rather than printed and a file past the size cap described by its size and, where the turn holds read_file or run, by what can read it (GIT-9). A path narrows it to that file or the files beneath it. A symbolic link and a submodule are not searched, as git grep over a tree searches neither. The pattern is written as file_grep's is (SEARCH-1).

Every file the search read is a path it showed (GIT-3), whether or not a line in it matched, so one file the map distrusts makes the whole answer a reference. A file the trust map withholds is not read, and the answer says one was left out only where it was inside the path searched. A search pages by the lines it prints, counting a binary file that matches and a file past the cap as one each, and names the skip that lists the next of them.

Why. Finding nothing in a file says something about what it holds too. Labelled by its matches alone, a search over a file the map distrusts would come back trusted whenever the file happened not to match, and whether it matched is exactly what that file's author controls. A page counted in anything other than the lines it printed would repeat or skip one on the next.

verified-by: bravebot_agent::turn::read_git_searches_the_files_at_a_revision_and_pages_the_lines verified-by: bravebot_agent::turn::a_search_that_read_a_distrusted_file_is_quarantined_matched_or_not verified-by: bravebot_agent::turn::what_a_distrusted_blob_holds_changes_a_searchs_counts_and_nothing_else verified-by: bravebot_agent::turn::the_skip_a_cut_read_git_search_offers_stays_inside_a_distrusted_blobs_body verified-by: bravebot_agent::workspace::a_search_pattern_is_held_to_trusted_public_before_anything_is_read verified-by: bravebot_agent::git::search_lists_the_lines_a_pattern_matches_at_a_revision_as_git_grep_does verified-by: bravebot_agent::git::a_search_prints_an_indented_line_with_exactly_the_indentation_the_file_has verified-by: bravebot_agent::git::a_search_shows_every_file_it_read_whether_or_not_it_matched verified-by: bravebot_agent::git::a_search_leaves_out_a_withheld_file_and_says_so verified-by: bravebot_agent::git::a_search_pages_by_the_lines_it_prints verified-by: bravebot_agent::git::a_file_past_the_size_cap_is_shown_whether_or_not_the_pattern_would_match_it verified-by: bravebot_agent::turn::a_search_that_met_a_distrusted_file_past_the_size_cap_is_quarantined