First you have to stage the files you want to commit.
$ git add [files...]
Or you can stage all files.
$ git add .
You can double-check and see which files you staged.
$ git status
Now after everything is staged, you are ready to commit the changes.
$ git commit -m "Your commit message here"
Now that you have your changes committed, you can push it.
$ git push
Or sometimes you have to specify the remote/branch explicitly.
$ git push origin master
$ git pull
Or to specify it more explicitly.
$ git pull origin master
If the conflict cannot be automatically merged (non-fast-forward), you can go in the affected files and merge the changes yourself. Your changes and the origin's changes will be marked, you can remove the marking, and merge it manually.
After manually merging the file, you can simply stage your changes, and commit (note that you don't need to provide a commit message).
$ git add . $ git commit # [An editor will appear, simply exit it] $ git push
$ git help X
Where X is the command you may want to understand. A
will show up with all the different options, and examples.
You probably forgot to specify a commit message, simply type your commit message and exit. This also happens when you intentionally leave out the commit message when merging commits, or after an automatic merge. In that case you can exit by :qEnter in Vim, or Ctrl+X with nano. Otherwise;
If it is vim, you'll have to enter INSERT mode before typing by pressing i, then you can type. After you are done, simply press Esc to go back to NORMAL mode, then to save and exit, type :wqEnter.
Otherwise, with nano simply type directly, and press Ctrl+X followed by a Y.
Let's say you want to tag the current commit as
v0.1, we type
$ git tag v0.1
To push (or pull) the tag, you have to include
--tags with your push command
$ git push --tags
And the tag will appear on GitLab.
To delete a tag, simply do
$ git tag -d v0.1
Check out the documentation on Git Branching Basics, which provides explanations with diagrams.
Check out git-scm docs, which goes in-depth in many aspects of the git tool.
Also check out Oh Shit, Git!?!, you'll need it when you screw up your repo :).
GitLab doesn't allow force pushes by default (unlike GitHub), this prevents people from accidentally pushing a corrupted or old repository accidentally to origin.
You will probably have to clone a fresh repository, and salvage the changes from the previous repository manually. This prevents us from corrupting the origin repository.
Diagrams are made with PlantUML, which is written in a very minimal format. You can check out examples on their main website.
You need LaTeX installed on your computer, then you can run the command
$ pdflatex file.tex
file is the name of the file. It will produce a
Those files are automatically generated by LaTeX, you should ignore them.
You need to install PlantUML on your system, then simply run
$ plantuml diagram.txt -o diagram.png
diagram.png would be your output image file.
Make sure you are in the root directory of the Go project, and run
$ go build
Or to directly run the project
$ go run main.go
$ go fmt ./...
Note the three dots, this recursively formats files in the project tree.
To find issues, run the vet
$ go vet ./...
To run all unit tests, simply run
$ go test ./...
You can just add it in the package imports section on the top of the
Go file you want to use it in. With Go Modules enabled, this should
be automatically downloaded when you try to use
go run or
Otherwise, you can run
$ go get ./...
Learn X in Y Minutes have their dedicated page on Golang too!
Check out the Go project structure in the Main Style Guide.
XORM is the Object-Relational Mapping library we are using, this automatically hooks up with any database engine (PostgreSQL/SQLite/MySQL, or even MSSQL.. ew). This engine automatically generates the schema, and syncs the database. It also does the heavy-lifting for CRUD queries. You can check the documentation on their website.
Macaron (or Go-Macaron) is a minimal web framework for Go, do note that this library relies on
net/http library on many things, such as templating, and the framework is just
a middleware between you and the
net/http library. So it is important to know what is provided
by the built-in library or Macaron, so you can find the appropriate documentation.
Usually if it relates to these points, it is a Macaron thing:
- Routing (and parameters in URLs)
- Templating (built on top of Golang's templating, so it is mostly identical)
- Data binding (forms bound to structs)
- Sessions and cache
- Captchas and CSRF protection
Check out Macaron's wiki as it contains really helpful information, and it will be used very frequently as a reference, just like XORM's docs.
To keep the command-line usage of the program neat and simple, we use urfave's cli library. This allows us to have multiple command-line commands, with flags and options, in a neat way. This is very simple, and usually just setup a couple of times when adding new commands in the beginning of the project's life-cycle.
We use BurntSushi's TOML library for handling TOML files. We use the TOML as the configuration file format, you can check out TOML's language spec. It is supposed to be better than YAML and INI (also, ew) format.
To help with writing unit tests, we use the testify unit testing library which
simplifies the testing. Although Go provides a
testing library, it does not have assertions. This library provides them,
among other things, such as data mocking with its
mock package, among other things.
If there are other libraries, you can check them. A good tool is the
go doc command-line tool,
also a better tool is the GoDoc website, you can simply enter any package
and it will download it, and preview a web documentation.
It is important to also be aware of Go's built-in library, as it is really powerful.
A nice website for discovering libraries is Go Awesome, it is also a source of inspiration.
A project called Gitea is one of the main inspirations of this projects layout, and it uses the same libraries listed above. You can learn by checking out Gitea's source code, as it is done and structured similarly to our project.
To run Makefiles you need GNU Make installed on your system.
Then you are able to use the
make command, which will run the
Makefile in the current directory.
Makefiles may have multiple rules, such as
all to run all rules (and produce a target). Consult the
README file of the project, which would list the appropriate make commands for different scenarios.
Usually, you would run a command like
$ make all
Usually, Makefiles are simple and don't require modification once things are set.
Use whatever you like.
If you are here for some recommendations, then:
- Visual Studio Code (currently trendy, but has poor speed performance)
- [neo]vim and emacs (has a learning curve, but pays off in the long run)
- Jetbrain's GoLand (made by same company who made IntelliJ)
- Geany (a good lightweight alternative to VS Code and other Electron-based editors)
Using Linux (or most Unix-based/like systems, this includes macOS) will help with development, as the tools can be run locally. Unlike with Windows, you may need to work-around with Windows Subsystem for Linux (WSL) or Cygwin, which might not work as expected like on a proper Unix system. Although it is not necessary, especially with organisational roles.
How to get Linux?
- Use lab computers or connect to them using X2Go (may be slow), or via ssh (with PuTTY).
- Setup a Virtual Machine with VirtualBox.
- Dual-boot your system.
- Nuke and pave your system with Linux.
Ubuntu is a popular Linux distribution, which is easy to install and has a lot of online support.
You should have these packages installed on your system:
- git: For version control.
- LaTeX: For document typesetting.
- GNU Make: For build automation.
- Go: The programming language.
- PlantUML: For diagram generation.
Other programs worth installing:
- A database server, such as PostgreSQL or MariaDB
- zathura: A minimal PDF viewer which reloads files automatically when updated.
- sxiv: A minimal image viewer which reloads images automatically when updated.
You can get one at https://shields.io/, and add it in Settings>General>Badges on GitLab project or group.
Do note that our repositories are private, so shields will not be able to view the statistics of our projects.
There is no need to undo anything. Simply figure out why the CI build failed, it
could be due to formatting or compilation issue. Make sure you run
make to format
and test the project before committing and pushing to GitLab.
But it happens sometimes, and it is fine. This is the reason why we have CI.