From 6a0bf1c32a4aedf504abb19edcd4a658d875f84a Mon Sep 17 00:00:00 2001 From: Nguyen Tran Date: Fri, 4 Oct 2024 15:06:40 -0400 Subject: [PATCH] add document for using git --- docs/git_workflow.md | 83 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/git_workflow.md diff --git a/docs/git_workflow.md b/docs/git_workflow.md new file mode 100644 index 0000000..afa7e4b --- /dev/null +++ b/docs/git_workflow.md @@ -0,0 +1,83 @@ +When working with a Git repository and its fork, following best practices can help maintain a smooth workflow, keep your fork updated, and avoid common issues like merge conflicts. Here are some good practices: + +### 1. **Keep Your Fork Up-to-Date** + +- **Add an Upstream Remote**: After forking the repository, add the original repository as an upstream remote. + ```bash + git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git + ``` +- **Regularly Fetch from Upstream**: Periodically fetch the changes from the upstream repository to keep your fork up-to-date. + ```bash + git fetch upstream + git checkout main + git merge upstream/main + ``` +- **Rebase Your Work**: Instead of merging, you can use rebase to apply your changes on top of the latest upstream commits, keeping your history cleaner. + ```bash + git pull --rebase upstream main + ``` + +### 2. **Create Feature Branches** + +- Always create a new branch for each feature or bug fix you're working on. Never work directly on the `main` branch of your fork. + ```bash + git checkout -b feature-branch + ``` +- This helps to isolate work and makes it easier to manage pull requests and reviews. + +### 3. **Work in Small, Logical Commits** + +- Make frequent, small, and logical commits that represent single units of change. Use meaningful commit messages that explain the "why" of the change. + ```bash + git commit -m "Fix bug in user authentication" + ``` + +### 4. **Use Pull Requests (PRs) for Collaboration** + +- When you’re ready to contribute changes back to the original repository, create a pull request (PR). Ensure your PR is well-documented and easy to review: + - Write a clear description of what changes you’re introducing. + - Reference any related issues. + - Use PR templates if available. + +### 5. **Sync Your Fork with the Upstream Before Opening a PR** + +- Before submitting a pull request, make sure your fork is up-to-date with the upstream repository: + ```bash + git fetch upstream + git checkout main + git merge upstream/main + ``` +- Resolve any conflicts and ensure that your feature branch is fully synced with the upstream. + +### 6. **Squash or Rebase Commits Before PRs (Optional)** + +- If your branch has many small, work-in-progress commits, consider squashing or rebasing them into a single commit for a cleaner history. + ```bash + git rebase -i main + ``` +- Squashing simplifies the history, making it easier for maintainers to review your changes. + +### 7. **Test Thoroughly** + +- Before pushing your changes or submitting a PR, ensure your changes are thoroughly tested. Run the test suite provided by the project, if available, and add new tests if applicable. + ```bash + git push origin feature-branch + ``` + +### 8. **Handle Conflicts Properly** + +- If your feature branch diverges from the upstream and conflicts arise during merging or rebasing, resolve the conflicts carefully and re-run any tests to ensure nothing is broken. + +### 9. **Clean Up Old Branches** + +- Once a feature branch has been merged, consider deleting it to keep your repository clean: + ```bash + git branch -d feature-branch + git push origin --delete feature-branch + ``` + +### 10. **Document Your Workflow** + +- If you're working on a team or contributing to an open-source project, document your Git workflow and practices. This helps maintain consistency and avoids confusion. + +By following these practices, you'll make sure your forked repository stays organized and in sync with the upstream repository, and your contributions remain easy to manage.