Skip to content

Git Workflow

Jump to bottom Edit New page
PermieBTS edited this page Aug 9, 2019 · 14 revisions

9.0 Git Workflow

9.1 Adapted from Marko Paasila's Learn to Code Strategies repo.

9.1.1 We suggest the following practices to manage own and others' versions of the code. Git is oddly confusing to many, but it's incredibly popular and flexible - and absolutely worth learning. Git has shorthand commands, and I will try to avoid them as they can cause even more confusion if you don't understand the separate stages which they combine.

9.2 The following instructions are written for linux

It won't tell you to open a terminal every time it is needed. Where I put stuff in between tags like this: < stuff >, don't copy what I wrote but substitute it (and the tags) with your personal content.

9.3 Prepare

9.3.1 Create a personal Github repository

9.3.1.1 Create a personal GitHub repo

9.3.1.2 Clone DEXBot to your personal repository by going to https://github.com/Codaone/DEXBot and pressing "Fork". Not "Clone or download", but "Fork".

9.4 Now that you have a public repository, you must pair it with a local copy on your computer:

9.4.1 Install and configure git

sudo apt install git gitg meld

9.4.2 gitg is the default graphical interface to git, and meld is a graphical tool to compare files and git versions. Now you have to configure git with at least the following information:

git config --global user.name "<Name Surname>"
git config --global user.email "<email@domain.tld>"

9.5 Create and add your public key to Github

Git uses ssh by default, and Github can authenticate you by your ssh keypair. This will enable you to "push" code to Github with a simple command from your terminal.

ssh-keygen

9.5.1 Accept the defaults by pressing enter. If you want additional security, you can provide a passphrase. This will require you to enter it every time you use ssh or push with git. You can also leave it empty. It's pretty safe. Now you will have a private key: id_rsa and a public key: id_rsa.pub.

9.5.2 Now go to Github settings page for key's. Add a new key, and into the input field paste your public key, which you can get with less ~/.ssh/id_rsa.pub. Just copy the text and paste it into Github. That's it.

9.6 Clone your personal Github repository to your computer

9.6.1 Go into a directory where you want to "dexbot" folder to be created. Copy the link from "Clone or download" of your personal repository. Choose "Use SSH". Then on your terminal enter: git clone <the link you just got> dexbot. The last "dexbot" in the command is the name of the folder which will be created. You can use whatever name you want.

9.6.2 Now you have a Github repository with DEXBot and a local repository with the same DEXBot. Go into the directory with cd dexbot. Your computer now refers to the Github repository as "origin". Now you can import versions from other repositories too, so you can pull improvements directly from them:

9.7 Add references to interesting upstream repositories

9.7.1 I will use Codaone and Bitfag as examples, but you can use whatever and as many as you like.

git remote add codaone git@github.com:Codaone/DEXBot.git
git remote add bitfag git@github.com:bitfag/DEXBot.git
git remote add <some other> <git@some other public repo.git>

9.7.2 Now you can refer to those repositories as "codaone" or "bitfag", and your personal one as "origin". Fetch a local copy of each of these with git fetch codaone or git fetch bitfag etc.

9.8 Workflow

9.8.1 Pull current state from others

9.8.1.1 git fetch codaone will get you a local copy of all branches of codaone/dexbot. You can do the same with bitfag and whatever else remote repositories you added. This will not make any changes to your current branch (any files in your file structure). Now you will be able to checkout(view) any branch of any of the configured repositories or compare/merge them to your current branch.

9.8.2 To checkout a branch means to observe or work on the versions of files in that branch. The files and directories will represent that branch, and no stuff from other branches will be visible to you. Checkout a branch with: git checkout codaone/whatever_branch or git checkout some_local_branch. Remote branches need to be prepended with the remote repository name, but the local branches need none.

9.8.3 I recommend not to checkout "remote" branches for other than testing them as such. You can make install them to try. Any time you do this, dexbot-gui/cli will be replaced by the new one.

9.9 Create a local branch for your own work

9.9.1 I recommend doing all work in a local branch specific to what you intend to accomplish. Choose what branch you want to start working from. The safest starting point is currently codaone:master, so git checkout codaone/master and then make a branch with git branch my_specific_intention. Then checkout your new branch. There's a shorthand for this, but it's better to learn what's going on.

9.10 Save a snapshot of the current state or your work

9.10.1 Whatever files you have worked on, and which you want to save, need to be added to version control: git add <filename.suffix> for each of them. Now git is tracking them.

9.10.2 You can see the state of version control with git status. It will tell you which files have changed or staged. If you edit a file and save it, "git status" will tell you it has changed. You need to save the new state separately with git commit -m "what has changed". Now the changes have been saved locally, and you can return to this point any time in the future and see what happened. Once committed, "git status" will no more show the files as changed, as they are a part of the new state

9.11 Make your changes public

9.11.1 You might be happy with what you did. You can push the changes to your public repository as a separate branch, or merge them to your master and push the new master to github.

9.12 Getting up to date and making a new contribution

9.12.1 Assuming you are a new contributor that has forked codaone master and added remote:

$ git remote -v
codaone    git@github.com:Codaone/DEXBot.git (fetch)
codaone    git@github.com:Codaone/DEXBot.git (push)
origin    https://github.com/NewDeveloper/DEXBot.git (fetch)
origin    https://github.com/NewDeveloper/DEXBot.git (push)

9.12.2 To get latest development branch from codaone, do:

$ git checkout -b devel --track codaone/devel

9.12.3 Then, make feature edits on your own branch locally, example Issue #500 called user experience bugs:

$ git checkout -b  500-user-experience-bugs
$ git add ….
$ git commit -m "……."
$ git push --set-upstream origin 500-user-experience-bugs

9.12.4 If changes appear on devel branch before they are able to make a pull request, in order to merge upstream changes :

$ git fetch codaone devel
$ git merge codaone/devel

9.12.5 To make a pull request:

9.12.5.1 Go to web and click on pull from origin/500-user-experience-bugs to Codaone/devel branch

9.12.5.2 In general, Pull = (fetch+merge)

9.13 Propose your changes to others

9.13.1 You can propose your changes in a branch by making a pull request to the upstream respository

9.13.2 From the Github Guide to creating a pull request:

  • 9.13.2.1 On GitHub, navigate to the main page of the repository.
  • 9.13.2.2 Branch dropdown menuIn the "Branch" menu, choose the branch that contains your commits.
  • 9.13.2.3 Pull Request buttonTo the right of the Branch menu, click New pull request.
  • 9.13.2.4 Drop-down menus for choosing the base and compare branchesUse the base branch dropdown menu to select the branch you'd like to merge your changes into, then use the compare branch drop-down menu to choose the topic branch you made your changes in.
  • 9.13.2.5 Pull request title and description fieldsType a title and description for your pull request.
  • 9.13.2.6 Create pull request buttonTo create a pull request that is ready for review, click Create Pull Request. To create a draft pull request, use the drop-down and select Create Draft Pull Request, then click Draft Pull Request. For more information about draft pull requests, see "About pull requests."

9.14 Trash your work and replace with upstream version

9.14.1 You can undo changes to a repository's commit history by git revert

9.14.2 You can also use other undo commands such as git checkout and git reset to move the HEAD and branch reference pointers to a specific commit. git revert does not move the pointers but it will create a new "revert commit"

9.14.2.1 Example: to revert the changes indicated by the fourth last commit in HEAD, you can do:

git revert HEAD~3

9.15 References

Add a custom footer
Clone this wiki locally