How to Git(Hub)

Ha azt szeretné, hogy segítse létrehozása Sponge, van egy fantasztikus kívül az API-hoz, vagy szeretné javítani a Dokumentumok, akkor kell majd, hogy megismerkedjen a git GitHub. Ha már ismeri elágazás, branches, issues, pull-kéri, valamint vállalja, akkor csak hagyja ki ezt a témát. Ha fogalmad sincs, miről beszélünk, akkor olvass tovább.

Megjegyzés

This guide assumes that you’ve read Installing Git and that you’ve already setup your machine with a Git client of your choice.

The Basic Concept of Git and GitHub

Git lehetővé teszi számos különböző fejlesztők számára, hogy dolgozzon ki egy darab szoftver egyszerre. A GitHub egy olyan weboldal, ahol a fejlesztők együtt, majd megosztani a munkát másokkal. A Git támaszkodik Git a menedzsment szerint működik.

Javaslat

Ha még nem ismeri, a Git és GitHub szókincs, nézd meg a szószedet oldalon a GitHub.

Repo Overview

In this case the repo is named SpongePowered, has two branches named master and feature 1 and also some commits on both branches.

Let’s put these terms into context - beginning with the repository. The repository (short: repo) is the place where a project stores its files. The SpongePowered repositories are located at GitHub. However, this repo has some access restrictions to preserve it from unwanted or malicious changes. You can’t simply make changes yourself, as the repo is read-only for regular users. Now you may wonder how you’re supposed to file proposals and changes. Well, that’s where forks come into play. You can grab a copy of the SpongePowered repos, and make your changes there. When you’re done, you open it as a pull request (PR) on our repository. Your proposed additions and changes can then be reviewed, and staff will tell you if something is wrong, or needs improvement, and eventually merge the final PR.

Itt egy rövid összefoglaló a fent leírt eljárást, mielőtt megyünk bele a részletekbe:

  1. A villa a repo, az ön választása

  2. A klón a helyi gép

  3. Create a new branch

  4. Módosítsa a kívánt beállításokat

  5. Test if everything works

  6. Commit the changes

  7. Sync them to GitHub

  8. Javaslom, hogy a változások egy PR hogy a SpongePowered Repo

  9. Amend to your PR if necessary

  10. Your PR gets pulled into master by staff

Details please!

1. Forking a Repo

Megjegyzés

Ez a lépés csak akkor szükséges, ha nem nyomja jogok a repo változtatásokat hajt végre. Ha dolgozol, a saját repo, nem a villa szükséges. Csak hagyja ki ezt a lépést, illetve a klón közvetlenül. Ha a változtatások Sponge és nem személyzet, ez a lépés szükséges.

Now that you know the basic concept, we’ll discuss the details. First you need to fork the repository you want to make changes to. This can be done on GitHub.com, where you’ll find a Fork button at the top of the repositories page. After pressing it, GitHub will do some work and present a clone of the original repo to you. You’ll notice that the clone is now located at YourGitHubAccount/ClonedRepoName. Alright, first step completed.

Megjegyzés

All branches from the original repository will get forked too, you receive an exact clone of the forked repo.

Repo forking

2. A klónozás a Villát, hogy A helyi Gép

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice (Installing Git) and clone your fork to your local machine. The client will ask you for a folder to store everything in. Second step finished, well done!

Megjegyzés

Most steps can be done via GUI of your choice. If you’re experienced with a command line interface, then you can use it too. Each step will show you the required commands to achieve the desired result.

Alternatively, you can do this via CLI (command line interface, CMD or powershell on windows). Note that you need to create the folder everything is getting cloned to yourself before typing this command:

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
Repo cloning

3. Creating a New Branch

Now that you have a local clone of your fork, it’s time to create a branch to work on. Branches were designed to be able to develop and test different features or additions at the same time, without causing problems and errors due to interferences of the additions. It’s strongly advised that you don’t make your changes on the master branch. Instead, create a new branch yourself (with a sensible name) and make the changes there.

This implies that we need to create a branch first, so let’s go! You can do this via your client (there should be a create branch button somewhere), or you can use the CLI with git:

git checkout -b [name_of_your_new_branch]

This will create a branch with the name of your choice and switch to it. All changes you’re about to make will be on this branch. If you need to switch to another branch (for example master), just reuse this command. Third step done! Good job so far! To get an overview of your branches, just have a look at your git client or use:

git branch
Branches

Most itt az ideje, hogy a módosítások. Használja a szerkesztő, vagy IDE a választás erre.

4. Test if Your Changes Work

A SpongeAPI a megvalósítások meg kell futtatni gradle compileJava. Folytassa a következő lépéssel, ha befejezi hiba nélkül. Ha nem, a megfelelő korrekciókat, majd próbálja meg újra.

For SpongeDocs you can just submit your PR. It will get built automatically and reveal possible errors. Another option is to build the Docs locally. Have a look at the Readme.md on the Docs for further instructions.

5. Commit the Changes

When you’re done, you need to bundle them into a single package (a commit) and get them into the branch. Again, your git client will help you out. Add a meaningful name to your commit and a short description if needed. This can be done via CLI too:

Először gyűjtsd össze az összes fájlokat vagy mappákat szeretne helyezni egy elkövetni:

git add <file>
git add <folder>

Most, hogy a fájlokat ad hozzá a listához a szükséges változtatásokat tartalmazza a elkövetni, csak

git commit

Megnyílik a sms ablak, ahol lehet hozzáadni egy üzenetet, ha a vágy. Nézd meg az alábbi képet. Észre fogod venni, hogy a követ még a helyileg tárolt csak, nem pedig a villát a GitHub.

Megjegyzés

Lehet több vállalja a PR. Csak változz át minden, ami kell magát a változások. Egyesítheti az vállalja fel egyetlen követett el később.

Így most a hatodik lépés megtörtént. Majdnem!

Committing

6. Sync to GitHub

Most kell, hogy a változások a villát a GitHub. Mindent, amit tettél eddig csak a helyileg tárolt most. Mint mindig, akkor használja a git ügyfél erre (van egy gomb valahol a GUI), vagy meg tudod csinálni keresztül CLI:

git push <remote> <branch>

In this case it should be:

git push origin feature/YourFeature
Pushing commits

7. Propose the Changes in a PR to the SpongePowered Repo

You can either go to your forks page on GitHub.com (there should be a notice at the top of your forks page to guide you), or you can use your GitHub client to create a pull-request. The official GitHub for Win client uses the top right corner of the window for this.

PRs

8. Amend Your PR if Necessary

Ha azt akarjuk, hogy a változások, hogy a PR, akkor most, hogy több vállalja, hogy a branch létre felett. További vállalja kell hozzá, hogy a PR automatikusan.

9. Your PR Gets Pulled

That’s it. We’re all set! Great job!

Advanced Git

Squashing with Rebase

Let’s say you have finished your additions to the repo, and let’s pretend that you made 137 commits while getting it done. Your commit history will certainly look cluttered. It would be a shame if they were all recorded into the repo, wouldn’t it? Too many trivial commits also clutters the project commit history. Fortunately, Git has a nice tool to circumvent this, it’s called a rebase. Rebasing can take your 137 small commits and just turn them into one big commit. Awesome, isn’t it? Instead of reinventing the wheel, we’ll just pass you a link to a very short and easily understandable squashing tutorial:

Gitready: Squashing with Rebase

This is what it does, nicely visualized:

Squashing commits

Setting Up a Remote

Naturally the original repo is the direct parent of your fork and your fork is the direct parent of your local clone. However, the original repo isn’t the direct parent of your clone. This isn’t a problem in the first place, but it prevents you from updating your clone to the latest changes on the original repo. If you setup the original repo as a remote (read: „parent”) of your clone, you’ll be able to grab all changes made to this repo and apply it to your local clone. Look below to see how grabbing and updating works.

Setting up a remote

Alright. This step is done through CLI as most GUIs are missing this (rather advanced) functionality:

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

If you’re unsure if that worked as intended or if you want to check which remotes are currently set, you can check via:

git remote -v

the output should look like:

origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin    https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream  https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

Megjegyzés

If you see the warning fatal: The current branch YourBranchName has no upstream branch., then the branch may not be on the upstream remote. This may happen if this is the first time you are pushing a commit for the new branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin YourBranchName.

Rebasing

Let’s say you made some changes to your desired branch, but in the meantime someone else updated the repo. This means that your fork and your clone are outdated. This is not a big problem, but to avoid problems when merging your additions later on, it’s strongly advised to rebase your changes against the latest changes on the original repo. If you haven’t set up the remote repo yet, do it before trying to rebase.

A successful rebase requires several steps:

1. Fetch the Changes on the Remote Repo

First you need to fetch the changes on the remote repository. This is (again) done via CLI:

git fetch upstream

This will add all changes from the remote upstream and put them into a temporary upstream/master branch.

2. Merge Remote Changes locally

Now we need to select our local master branch:

git checkout master

After that we’ll merge the changes that are included in upstream/master into our local master branch:

git merge upstream/master

Alright, this is what we’ve done so far:

Rebasing 1

3. Rebase Local Branch against Updated Master

Next up is rebasing the local branch you’re working in against local master. We need to switch to your working branch (here: feature/yourfeature) and then perform a rebase. This is done via:

git checkout feature/yourfeature
git rebase master

This will rewind your branch, add the commits from master and then apply your own changes again. The result looks like this:

Rebasing 2

4. Push Everything to your Fork

The last thing we need to do is to push everything to the fork. If you’ve already created a PR, it will get updated automatically:

git checkout master
git push -f
git checkout feature/yourfeature
git push -f
Rebasing 3

You made it, awesome! Good job and well done and thanks for flying Rebase-Air!