diff --git a/README.md b/README.md index f5730b788246..761932673205 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,28 @@ Welcome to GitHub Docs! GitHub’s documentation is open source, meaning anyone from inside or outside the company can contribute. For full contributing guidelines, visit our [contributing guide](https://docs.github.com/en/contributing). -## Quick links by contributor type +Here’s a ready-to-paste PR description for the rebase documentation change. Since there’s no confirmed issue number, I’ve left the issue field blank rather than inventing one. GitHub has enough imaginary paperwork already. -* **Hubbers (GitHub employees):** See [CONTRIBUTING.md](https://github.com/github/docs-content/blob/main/CONTRIBUTING.md) in the `docs-content` repository for GitHub-specific processes. +Why: -* **Open source contributors:** See [CONTRIBUTING.md](https://github.com/github/docs/blob/main/.github/CONTRIBUTING.md) in the `docs` repository for a quick-start summary. +Closes: -## How we sync changes across Docs repositories +Clarifies the interactive rebase workflow so readers understand how to amend the current commit and safely update a remote branch after rewriting Git history. -There are two GitHub Docs repositories: +What’s being changed (if available, include any code snippets, screenshots, or gifs): -- **`github/docs`** (public): Open to external contributions +* Clarifies how to edit files, stage changes with git add, and update the current commit with git commit --amend during an interactive rebase. +* Explains how to amend a commit message without changing staged file contents. +* Clarifies when to resume the rebase with git rebase --continue. +* Updates the guidance for pushing rebased history, including git push --force-with-lease and git push origin HEAD --force-with-lease. +* Explains why --force-with-lease is safer than --force, while noting the remaining risks when updating shared branches. -- **`github/docs-internal`** (private): For GitHub employee contributions. +Only the relevant sections of content/get-started/using-git/using-git-rebase-on-the-command-line.md are intended to change. -The two repositories sync frequently. Content changes in one are reflected in the other. Hubbers might prefer to post in `docs` when working with a customer, but `docs` has limitations on the types of contributions it accepts to safeguard the site and our workflows. Internal contributions should usually go to `docs-internal`. +Check off the following: -**Important:** The `docs` repository accepts contributions to content files (`.md` files in `/content` and select `/data` sections like reusables only). Infrastructure files, workflows, and site-building code are not open for external modification. +* [ ] A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. +* [ ] The changes in this PR meet the docs fundamentals that are required for all content. +* [ ] All CI checks are passing and the changes look good in the review environment. -## New to contributing - -Here are some resources to help you get started with open source contributions: - -* [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) -* [Set up Git](https://docs.github.com/en/get-started/git-basics/set-up-git) -* [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) -* [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) - -## License - -This project is dual-licensed under: - -* **Creative Commons Attribution 4.0** - for documentation and content in the assets, content, and data folders (see [LICENSE](LICENSE)) -* **MIT License** - for code (see [LICENSE-CODE](LICENSE-CODE)) +One important catch: the PR still needs to be opened from the fork, and the final Markdown formatting correction around the --force-with-lease and --force option names should be made first. The GitHub integration previously rejected both write attempts with a 403, so this description is ready, but the PR itself is not open. diff --git a/content/get-started/using-git/using-git-rebase-on-the-command-line.md b/content/get-started/using-git/using-git-rebase-on-the-command-line.md index 3a9cf64cc7b5..e113f7fc3c47 100644 --- a/content/get-started/using-git/using-git-rebase-on-the-command-line.md +++ b/content/get-started/using-git/using-git-rebase-on-the-command-line.md @@ -107,7 +107,11 @@ Once you are satisfied with your changes, run git rebase --continue ``` -At this point, you can edit any of the files in your project to make any additional changes. For each change you make, you'll need to perform a new commit, and you can do that by entering the `git commit --amend` command. When you're finished making all your changes, you can run `git rebase --continue`. +At this point, you can edit the files in your project to make the changes you want to include in the current commit. Stage your changes with `git add`, then run `git commit --amend` to update the current commit rather than create a separate commit. + +If you only want to change the commit message, run `git commit --amend` without changing the staged file contents. + +When you're finished, run `git rebase --continue` to resume the rebase. Git then gets to the `reword 4ca2acc` command. It opens up your text editor one more time, and presents the following information: @@ -128,18 +132,21 @@ As before, Git is showing the commit message for you to edit. You can change the ## Pushing rebased code to GitHub -Since you've altered Git history, the usual `git push origin` **will not** work. You'll need to modify the command by "force-pushing" your latest changes: +Since you've rewritten Git history, a regular `git push` may be rejected. To update the remote branch, you may need to force-push: ```shell -# Don't override changes -$ git push origin main --force-with-lease +$ git push --force-with-lease +``` -# Override changes -$ git push origin main --force +This command pushes the current branch to its configured upstream. If you want to specify the remote and branch explicitly, use: + +```shell +$ git push origin HEAD --force-with-lease ``` -> [!WARNING] -> Force pushing has serious implications because it changes the historical sequence of commits for the branch. Use it with caution, especially if your repository is being accessed by multiple people. +This command pushes the current branch (HEAD) to the corresponding branch on origin. + +The --force-with-lease option is safer than --force because it checks the expected remote branch state and can refuse to update the branch if the remote has changed unexpectedly. However, it does not eliminate every risk of overwriting others’ work. Before force-pushing to a shared branch, check for collaborators’ changes and coordinate with them as needed. ## Further reading