129 lines
4.5 KiB
Text
129 lines
4.5 KiB
Text
Git is a flexible tool, and different projects and communities have
|
|
developed different workflows to collaborate and integrate changes. This
|
|
page describes an often-used workflow (but certainly not the only one)
|
|
when collaborating on GitLab, GitHub, or Forgejo-aneksajos.
|
|
|
|
|
|
### Forking
|
|
|
|
Forks are a copy of a repository. This is an ideal place to make
|
|
modifications (e.g. new functionality, content, big fixes, etc) and test
|
|
them, before the commits are requested to be included in the main
|
|
repository (\"upstream\") project via a Merge
|
|
Request.
|
|
|
|
To fork a git repository, go to the project\'s main page and click on
|
|
the **Fork** button.
|
|
|
|
On the next page, set the Project URL for the new fork along with its
|
|
name and visibility level; then click **Fork project**. Now you have a
|
|
complete copy of the upstream project\'s git repository (but no issues,
|
|
etc). You can `git clone` this new fork to checkout the content locally
|
|
and make changes. When you `git push`, commits will be pushed to your
|
|
fork, and not the upstream project\'s repository.
|
|
|
|
### Feature Branches
|
|
|
|
A powerful feature of git\'s is **branches**. A local git repository
|
|
always has a branch checked out, and the primary branch is usually named
|
|
either `master` or `main`.
|
|
|
|
It is common to keep local `master` pristine and create branches for
|
|
each distinct feature/bug-fix you wish to make. This way, development of
|
|
unrelated work can proceed independently and not block each other\'s
|
|
progress. One can be ready for inclusion upstream without the others
|
|
needing to be ready yet.
|
|
|
|
To create a new branch based on the current branch:
|
|
|
|
git checkout -b <new_branch_name>
|
|
|
|
Or to create a new branch based on a specific branch:
|
|
|
|
git checkout -b <new_branch_name> master
|
|
|
|
### Merge/Pull Requests
|
|
|
|
After you\'ve committed your changes and pushed those commits to your
|
|
fork, you can request that the changes be included in the upstream
|
|
project\'s repository. This is called a **Merge Request** or **Pull
|
|
Request**.
|
|
|
|
To do so:
|
|
|
|
1. Go to the main page of your fork in the browser.
|
|
|
|
2. - *GitLab*: Click on **Merge requests** (in the left-side menu).
|
|
>
|
|
>
|
|
> - *GitHub* / *Forgejo-aneksajo*: Click on **Pull requests** (near the top of the
|
|
> page, below the name of the repository).
|
|
|
|
3. Select the **source branch** of your fork and the **target branch**
|
|
(most likely `master` or `main`) of the upstream repository to merge
|
|
your commits into:
|
|
- *GitLab*: Progress with **Compare branches and continue**. On the
|
|
next page, the differing commits are listed on the bottom.
|
|
- *GitHub* / *Forgejo-aneksajo*: The new commits are listed after selecting branches.
|
|
Select **Create pull request** to progress.
|
|
|
|
4. Give the merge request a title and summary that describes the
|
|
changes that the commits makes.
|
|
|
|
5. Finish the process:
|
|
- *GitLab*: **Create merge request**
|
|
- *GitHub* / *Forgejo-aneksajo*: **Create pull request**
|
|
|
|
### Updating a Fork
|
|
|
|
When working on a fork over an extended period of time, development on
|
|
the upstream project may have continued and your fork is now behind. A
|
|
fork can be brought up to date with the upstream repository with the
|
|
following steps:
|
|
|
|
1. Add the upstream repository as a **remote** on your local clone
|
|
Note, this only has to be done once:
|
|
|
|
git remote add upstream <url>
|
|
|
|
2. **Fetch** the latest changes from upstream:
|
|
|
|
git fetch upstream
|
|
|
|
3. The next step depends on what you want to do, and if you have local
|
|
changes.
|
|
|
|
- If you have local commits, you can **rebase** them on top of
|
|
upstream\'s. If there are conflicts, it will prompt you to
|
|
resolve them:
|
|
|
|
git rebase upstream/master
|
|
|
|
- If you have no local changes, you can create a new branch that
|
|
matches the latest upstream:
|
|
|
|
git checkout -b <new_branch_name> upstream/master
|
|
|
|
- Alternatively, if you have no local changes (or none that are
|
|
valuable), you can reset your current branch to match upstream
|
|
exactly.
|
|
|
|
::: warning
|
|
::: title
|
|
Warning
|
|
:::
|
|
|
|
This will throw away any and all local changes in your current
|
|
branch. If you have local changes that you care about, you
|
|
probably want to use `git rebase` (above).
|
|
:::
|
|
|
|
```
|
|
git reset --hard upstream/master
|
|
```
|
|
|
|
4. Then proceed as usual, making your local changes, committing,
|
|
pushing to the fork, and then opening a [merge or pull
|
|
request](/learning/git_workflows/#mergepull-requests) through the
|
|
web UI.
|
|
|