update docs for latest#226
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9b5d03aab3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - `--project <id>`: Project ID (required) | ||
| - `--cred <file>`: Path to credentials JSON file | ||
| - `--token <token>`: Token for temporary access (alternative to `--cred`) | ||
| - `--url <url>`: Optional Gen3 endpoint override |
There was a problem hiding this comment.
When a user supplies --url to override the Gen3 endpoint, the command will silently keep using the endpoint parsed from --token/--cred or the existing profile: cmd/remote/add/init.go registers the flag, but gen3Init in cmd/remote/add/gen3.go declares a new local apiEndpoint and only assigns it from the token, credential file, or loaded profile. Documenting this as an endpoint override can send users to the wrong server during setup or credential refresh, so either the docs should not claim override behavior or the CLI should wire the flag through.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR updates user- and developer-facing documentation to better align install/setup and troubleshooting guidance with the current git-drs CLI and repository layout.
Changes:
- Updated Go version prerequisites in
README.mdanddocs/developer-guide.mdto matchgo.mod(Go 1.26.2+). - Refreshed installation and troubleshooting instructions (PATH setup wording, HPC Git LFS cleanup commands, and replaced unsupported commands with supported ones).
- Updated
docs/commands.mdto reflect currentgit drs initflags/defaults and revisedgit drs remote add gen3documentation.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates source-build Go prerequisite to match go.mod. |
| docs/developer-guide.md | Updates development Go prerequisite to match go.mod. |
| docs/installation.md | Improves PATH setup wording and aligns HPC Git LFS cleanup commands with downloaded version. |
| docs/commands.md | Updates init flag docs and revises remote add gen3 section; removes duplicate add-url section. |
| docs/troubleshooting.md | Replaces invalid commands and updates recovery flows to supported init/remote commands and .git/drs/ paths. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --project <project-id> \ | ||
| [--bucket <bucket-name>] | ||
| [--organization <program>] \ | ||
| [--bucket <bucket-name>] \ | ||
| [--cred <credentials-file> | --token <token>] \ | ||
| [--url <server-url>] |
| - `--cred <file>`: Path to credentials JSON file | ||
| - `--token <token>`: Token for temporary access (alternative to `--cred`) | ||
| - `--url <url>`: Optional Gen3 endpoint override | ||
| - `--organization <name>`: Program/organization scope used for bucket mapping |
All user-facing
|
| Old command | New command |
|---|---|
git lfs track |
git drs track |
git lfs untrack |
git drs untrack |
git lfs ls-files |
git drs ls-files |
git lfs pull |
git drs pull |
git lfs pull -I "pattern" |
git drs pull |
git lfs install |
git drs install |
git lfs version |
git drs version |
git lfs pre-push |
git drs pre-push-prepare |
git lfs env |
git drs remote list |
git lfs logs last |
cat .git/drs/*.log |
git lfs push --all |
git drs push |
Additional documentation updates
- Removed the Git LFS Commands section from
docs/commands.mdand replaced it withgit drscommand guidance. - Reworked troubleshooting guidance to use
git drsworkflows and diagnostics. - Kept implementation-level
lfsidentifiers where they are part of real config keys, paths, code symbols, or file format contracts.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 13 out of 13 changed files in this pull request and generated 8 comments.
Comments suppressed due to low confidence (1)
docs/precommit.md:69
- This calls the pointer format a “Git DRS pointer”, but the actual pointer format is the Git LFS pointer spec (
version https://git-lfs.github.com/spec/v1). To avoid confusion, describe these as “Git LFS pointers” or “Git LFS-compatible pointers used by Git DRS”.
## Cache Scope (Important)
Only files whose **staged content** is a valid Git DRS pointer are in scope:
version https://git-lfs.github.com/spec/v1
oid sha256:
| - `--project <id>`: Project ID (required) | ||
| - `--cred <file>`: Path to credentials JSON file | ||
| - `--token <token>`: Token for temporary access (alternative to `--cred`) | ||
| - `--url <url>`: Optional Gen3 endpoint override | ||
| - `--organization <name>`: Program/organization scope used for bucket mapping |
|
|
||
| - Identifies remote and project from configuration | ||
| - Transfers all DRS records for a given project from the server to the local `.git/drs/lfs/objects/` directory | ||
| - Transfers all DRS records for a given project from the server to the local `.git/drs/objects/` directory |
| **What it does:** | ||
|
|
||
| - Checks local `.git/drs/lfs/objects/` for DRS metadata | ||
| - Checks local `.git/drs/objects/` for DRS metadata |
| - Processes all staged files | ||
| - Creates DRS records for new files | ||
| - Only processes files that don't already exist on the DRS server |
| ### DRS Object Management | ||
|
|
||
| Objects are stored in `.git/drs/lfs/objects/` during pre-commit and referenced during push/pull workflows. | ||
| Objects are stored in `.git/drs/objects/` during pre-commit and referenced during push/pull workflows. |
| 1. `add-url` performs object metadata lookup (HEAD/attributes). | ||
| 2. Synthetic OID is derived from ETag (`sha256(etag)`). | ||
| 3. A local sentinel object is written into `.git/lfs/objects/...`. | ||
| 3. A local sentinel object is written into `.git/drs/objects/...`. |
| * Never performs network I/O | ||
| * Never queries DRS or DRS | ||
| * Ignores all non-LFS files | ||
| * Ignores all non-tracked files |
|
|
||
| * `path` is repo-relative | ||
| * `lfs_oid` comes from the staged LFS pointer | ||
| * `lfs_oid` comes from the staged DRS pointer |
Docs: Align Install/Setup Guidance With Current CLI Behavior
Why this change
Install/setup documentation had drifted from current CLI behavior and module requirements, which could lead to failed setup steps or confusing troubleshooting paths. This PR updates setup-facing docs to match the current codebase.
What changed
README.mdGo 1.24+toGo 1.26.2+(matchesgo.mod).docs/developer-guide.mdGo 1.24+toGo 1.26.2+.docs/installation.mdv3.7.1).~/.zshrc,~/.bashrc,~/.profile).docs/commands.mdgit drs initoption docs:--transfersdefault is1(not4)--upsert,--multipart-threshold,--enable-data-client-logsgit drs remote add gen3docs:--projectdocumented as required--cred/--tokendocumented as auth inputs--urlchanged from required to optional overridegit drs add-urlsection and kept one canonical section.docs/troubleshooting.mdgit drs list-configwith supportedgit drs remote list.git drs init --cred/--profileguidance.git drs init,git drs remote add ... --cred|--token)..git/drs/.Validation performed
go.mod(Go version)cmd/initialize/main.go(initflags/defaults)cmd/remote/add/gen3.go(remote add gen3behavior)git-drs init --helpgit-drs remote add gen3 --helpUser impact
Scope