WebSVN – SvarDOS – Diff – /doc/svn quickstart.txt


 
 
                                SVN QUICKSTART
 
                [authored by Mateusz Viste, the 29th June 2023]
 
 
=== INTRO =====================================================================
 
This document is aimed at people that are committing changes to the SvarDOS
svn repository: developers, packagers, writers, translators...
 
If you are reading this, then you probably received a write access to the
SvarDOS svn server at svn.svardos.org, ie. a login and password.
 
Subversion isn't hugely popular these days, hence people are less and less
comfortable with it. But worry not - it's extremely straightforward!
 
Here you will learn the few most basic operations that will allow you to
interact with svn right away.
 
 
=== REPOSITORY CHECKOUT =======================================================
 
This is one time action that you need to perform so your svn client pulls the
current state of the SvarDOS repository to your disk. It's called a "checkout":
 
  svn co svn://your.username@svn.svardos.org/svardos
 
This will create a "svardos" directory on your disk. All further actions will
be always performed from within this directory.
 
 
=== PERIODIC UPDATES ==========================================================
 
The repository changes with time, so you need to make sure that your local copy
is always up to date. To do so, you only need to execute a single command from
time to time. We call it an "update":
 
  svn up
 
 
=== ADD NEW FILES OR DIRECTORIES ==============================================
 
If you need to create a new subdirectory somewhere in the repo, you can either
ask your svn client to do it, or do it yourself and then ask your svn client to
track it.
 
Option 1:
  svn mkdir newdir
 
Option 2:
  mkdir newdir
  svn add newdir
 
If you creates a new file (new translation, new package, new code file...), you
need to tell svn about it so it starts to version it:
 
  svn add newfile.txt
 
Once done, you should review your changes and commit them (we will talk about
it below).
 
 
=== DELETE A FILE OR DIRECTORY ================================================
 
Deleting a file or directory via svn is as simple as this:
 
  svn del file_to_dele.txt
  svn del dir_to_delete
 
And of course, you need to commit the changes to apply them on the server.
 
 
=== REVIEWING YOUR CHANGES BEFORE COMMIT ======================================
 
You have done some changes on your local data, and are ready to push them to
the server? Thath's great, but I encourage you to review your changes one last
time, asking svn to list them.
 
1. Display the list of changed files or directories:
 
  svn st
 
2. Display the difference between your local files and the server's content:
 
  svn diff
 
 
Both these operations will show you the state compared to the last known
content of the server. To make sure nothing changed on the server in the mean
time, you should update your local copy (svn up) beforehand.
 
 
=== UNDOING (REVERTING) LOCAL CHANGES =========================================
 
You made some huge mistake and would like to erase your local changes to revert
back to the last known server's state? Easy:
 
  svn revert file_or_dir_to_revert
 
It is worth mentionning that this works even if you deleted your local copy of
the file or dir.
 
 
=== COMMIT ====================================================================
 
Finally, you made your changes, reviewed them, made sure your local files are
up to date, and are ready to push things to the server. Awesome. To push all
your changes at once, do a general commit:
 
  svn commit -m "short description of the changes"
 
If you prefer to push your changed files in separate commits for a better
visibility, then that' s no problem either:
 
  svn commit -m "fixed bug #123" changed_file.c
  svn commit -m "improved polish translations" pl.txt
  svn commit -m "updated FDISK to ver 1.3.7" fdisk-1.3.7.svp fdisk-1.3.7.zip
 
 
=== WHY SVN? ==================================================================
 
Nowadays most project rely on git for their versioning. Many people think
that's because of some technical superiority of git. I think that's rather a
bandwagon trend.
 
Of course I have nothing against git. It is a very impressive technology and an
outstanding solution to the specific problem it was designed for: enabling
collaboration of huge, unorganized teams on a complex code base while having no
centralized authority. But when it comes to more limited projects, it is my
opinion that git is an unnecessary complication that presents no added value
over svn, while having a number of downsides:
 - lack of a centrally managed repository,
 - lack of monotonically increasing revisions,
 - non-obvious usage,
 - poor storage of binary files,
 - inefficient client-side storage (stores the entire history)
 - ...
 
Subversion, on the other hand, is simpler due to its centralized nature.
Syncing (updating) local files is both faster and leaner than with git, because
svn cares only about the latest available revision, it does not keep the entire
project's history on the client side. In a word - it's simpler, and I am always
in favor of technical simplicity as long as it does not come with significant
limitations.
 
 
======================================================================= EOF ===
 

Subversion Repositories SvarDOS

(root)/doc/svn quickstart.txt – Rev 1254 → 1255

Rev 1254		Rev 1255
1		1
2		2
3	`SVN QUICKSTART`	3	`SVN QUICKSTART`
4		4
5	`[authored by Mateusz Viste, the 29th July 2023]`	5	`[authored by Mateusz Viste, the 29th June 2023]`
6		6
7		7
8	`=== INTRO =====================================================================`	8	`=== INTRO =====================================================================`
9		9
10	`This document is aimed at people that are committing changes to the SvarDOS`	10	`This document is aimed at people that are committing changes to the SvarDOS`
11	`svn repository: developers, packagers, translators...`	11	`svn repository: developers, packagers, writers, translators...`
12		12
13	`If you are reading this, then you probably received a write access to the`	13	`If you are reading this, then you probably received a write access to the`
14	`SvarDOS svn server at svn.svardos.org, ie. a login and password.`	14	`SvarDOS svn server at svn.svardos.org, ie. a login and password.`
15		15
16	`Subversion isn't hugely popular these days, hence people are less and less`	16	`Subversion isn't hugely popular these days, hence people are less and less`
17	`comfortable with it. But worry not - subversion is extremely straightforward!`	17	`comfortable with it. But worry not - it's extremely straightforward!`
18		18
19	`Here you will learn the few most basic operations that will allow you to`	19	`Here you will learn the few most basic operations that will allow you to`
20	`interact with svn right away.`	20	`interact with svn right away.`
21		21
22		22
23	`=== REPOSITORY CHECKOUT =======================================================`	23	`=== REPOSITORY CHECKOUT =======================================================`
24		24
25	`This is one time action that you need to perform so your svn client pulls the`	25	`This is one time action that you need to perform so your svn client pulls the`
26	`current state of the SvarDOS repository to your disk. It's called a "checkout":`	26	`current state of the SvarDOS repository to your disk. It's called a "checkout":`
27		27
28	`svn co svn://your.username@svn.svardos.org/svardos`	28	`svn co svn://your.username@svn.svardos.org/svardos`
29		29
30	`This will create a "svardos" directory on your disk. All further actions will`	30	`This will create a "svardos" directory on your disk. All further actions will`
31	`be always performed from within this directory.`	31	`be always performed from within this directory.`
32		32
33		33
34	`=== PERIODIC UPDATES ==========================================================`	34	`=== PERIODIC UPDATES ==========================================================`
35		35
36	`The repository changes with time, so you need to make sure that your local copy`	36	`The repository changes with time, so you need to make sure that your local copy`
37	`is always up to date. To do so, you only need to execute a single command from`	37	`is always up to date. To do so, you only need to execute a single command from`
38	`time to time. We call it an "update":`	38	`time to time. We call it an "update":`
39		39
40	`svn up`	40	`svn up`
41		41
42		42
43	`=== ADD NEW FILES OR DIRECTORIES ==============================================`	43	`=== ADD NEW FILES OR DIRECTORIES ==============================================`
44		44
45	`If you need to create a new subdirectory somewhere in the repo, you can either`	45	`If you need to create a new subdirectory somewhere in the repo, you can either`
46	`ask your svn client to do it, or do it yourself and then ask your svn client to`	46	`ask your svn client to do it, or do it yourself and then ask your svn client to`
47	`track it.`	47	`track it.`
48		48
49	`Option 1:`	49	`Option 1:`
50	`svn mkdir newdir`	50	`svn mkdir newdir`
51		51
52	`Option 2:`	52	`Option 2:`
53	`mkdir newdir`	53	`mkdir newdir`
54	`svn add newdir`	54	`svn add newdir`
55		55
56	`If you creates a new file (new translation, new package, new code file...), you`	56	`If you creates a new file (new translation, new package, new code file...), you`
57	`need to tell svn about it so it starts to version it:`	57	`need to tell svn about it so it starts to version it:`
58		58
59	`svn add newfile.txt`	59	`svn add newfile.txt`
60		60
61	`Once done, you should review your changes and commit them (we will talk about`	61	`Once done, you should review your changes and commit them (we will talk about`
62	`it below).`	62	`it below).`
63		63
64		64
65	`=== DELETE A FILE OR DIRECTORY ================================================`	65	`=== DELETE A FILE OR DIRECTORY ================================================`
66		66
67	`Deleting a file or directory via svn is as simple as this:`	67	`Deleting a file or directory via svn is as simple as this:`
68		68
69	`svn del file_to_dele.txt`	69	`svn del file_to_dele.txt`
70	`svn del dir_to_delete`	70	`svn del dir_to_delete`
71		71
72	`And of course, you need to commit the changes to apply them on the server.`	72	`And of course, you need to commit the changes to apply them on the server.`
73		73
74		74
75	`=== REVIEWING YOUR CHANGES BEFORE COMMIT ======================================`	75	`=== REVIEWING YOUR CHANGES BEFORE COMMIT ======================================`
76		76
77	`You have done some changes on your local data, and are ready to push them to`	77	`You have done some changes on your local data, and are ready to push them to`
78	`the server? Thath's great, but I encourage you to review your changes one last`	78	`the server? Thath's great, but I encourage you to review your changes one last`
79	`time, asking svn to list them.`	79	`time, asking svn to list them.`
80		80
81	`1. Display the list of changed files or directories:`	81	`1. Display the list of changed files or directories:`
82		82
83	`svn st`	83	`svn st`
84		84
85	`2. Display the difference between your local files and the server's content:`	85	`2. Display the difference between your local files and the server's content:`
86		86
87	`svn diff`	87	`svn diff`
88		88
89		89
90	`Both these operations will show you the state compared to the last known`	90	`Both these operations will show you the state compared to the last known`
91	`content of the server. To make sure nothing changed on the server in the mean`	91	`content of the server. To make sure nothing changed on the server in the mean`
92	`time, you should update your local copy (svn up) beforehand.`	92	`time, you should update your local copy (svn up) beforehand.`
93		93
94		94
95	`=== UNDOING (REVERTING) LOCAL CHANGES =========================================`	95	`=== UNDOING (REVERTING) LOCAL CHANGES =========================================`
96		96
97	`You made some huge mistake and would like to erase your local changes to revert`	97	`You made some huge mistake and would like to erase your local changes to revert`
98	`back to the last known server's state? Easy:`	98	`back to the last known server's state? Easy:`
99		99
100	`svn revert file_or_dir_to_revert`	100	`svn revert file_or_dir_to_revert`
101		101
102	`It is worth mentionning that this works even if you deleted your local copy of`	102	`It is worth mentionning that this works even if you deleted your local copy of`
103	`the file or dir.`	103	`the file or dir.`
104		104
105		105
106	`=== COMMIT ====================================================================`	106	`=== COMMIT ====================================================================`
107		107
108	`Finally, you made your changes, reviewed them, made sure your local files are`	108	`Finally, you made your changes, reviewed them, made sure your local files are`
109	`up to date, and are ready to push things to the server. Awesome. To push all`	109	`up to date, and are ready to push things to the server. Awesome. To push all`
110	`your changes at once, do a general commit:`	110	`your changes at once, do a general commit:`
111		111
112	`svn commit -m "short description of the changes"`	112	`svn commit -m "short description of the changes"`
113		113
114	`If you prefer to push your changed files in separate commits for a better`	114	`If you prefer to push your changed files in separate commits for a better`
115	`visibility, then that' s no problem either:`	115	`visibility, then that' s no problem either:`
116		116
117	`svn commit -m "fixed bug #123" changed_file.c`	117	`svn commit -m "fixed bug #123" changed_file.c`
118	`svn commit -m "improved polish translations" pl.txt`	118	`svn commit -m "improved polish translations" pl.txt`
119	`svn commit -m "updated FDISK to ver 1.3.7" fdisk-1.3.7.svp fdisk-1.3.7.zip`	119	`svn commit -m "updated FDISK to ver 1.3.7" fdisk-1.3.7.svp fdisk-1.3.7.zip`
120		120
121		121
122	`=== WHY SVN? ==================================================================`	122	`=== WHY SVN? ==================================================================`
123		123
124	`Nowadays most project rely on git for their versioning. Many people think`	124	`Nowadays most project rely on git for their versioning. Many people think`
125	`that's because of some technical superiority of git. I think that's rather a`	125	`that's because of some technical superiority of git. I think that's rather a`
126	`bandwagon trend.`	126	`bandwagon trend.`
127		127
128	`Of course I have nothing against git. It is a very impressive technology and an`	128	`Of course I have nothing against git. It is a very impressive technology and an`
129	`outstanding solution to the specific problem it was designed for: enabling`	129	`outstanding solution to the specific problem it was designed for: enabling`
130	`collaboration of huge, unorganized teams on a complex code base while having no`	130	`collaboration of huge, unorganized teams on a complex code base while having no`
131	`centralized authority. But when it comes to more limited projects, it is my`	131	`centralized authority. But when it comes to more limited projects, it is my`
132	`opinion that git is an unnecessary complication that presents no added value`	132	`opinion that git is an unnecessary complication that presents no added value`
133	`over svn, while having a number of downsides:`	133	`over svn, while having a number of downsides:`
134	`- lack of a centrally managed repository,`	134	`- lack of a centrally managed repository,`
135	`- lack of monotonically increasing revisions,`	135	`- lack of monotonically increasing revisions,`
136	`- non-obvious usage,`	136	`- non-obvious usage,`
137	`- poor storage of binary files,`	137	`- poor storage of binary files,`
138	`- inefficient client-side storage (stores the entire history)`	138	`- inefficient client-side storage (stores the entire history)`
139	`- ...`	139	`- ...`
140		140
141	`Subversion, on the other hand, is simpler due to its centralized nature.`	141	`Subversion, on the other hand, is simpler due to its centralized nature.`
142	`Syncing (updating) local files is both faster and leaner than with git, because`	142	`Syncing (updating) local files is both faster and leaner than with git, because`
143	`svn cares only about the latest available revision, it does not keep the entire`	143	`svn cares only about the latest available revision, it does not keep the entire`
144	`project's history on the client side. In a word - it's simpler, and I am always`	144	`project's history on the client side. In a word - it's simpler, and I am always`
145	`in favor of technical simplicity as long as it does not come with significant`	145	`in favor of technical simplicity as long as it does not come with significant`
146	`limitations.`	146	`limitations.`
147		147
148		148
149	`======================================================================= EOF ===`	149	`======================================================================= EOF ===`
150		150