From 64c69290937842312ec663d0f1c4b418260bd3eb Mon Sep 17 00:00:00 2001
From: Nathan Cutler <ncutler@suse.com>
Date: Tue, 2 Jul 2024 18:52:31 +0200
Subject: [PATCH] obs_basic_workflow: explain how to "move" a file

Fixes: https://github.com/openSUSE/obs-docu/issues/236

Signed-off-by: Nathan Cutler <ncutler@suse.com>
---
 xml/obs_basic_workflow.xml | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/xml/obs_basic_workflow.xml b/xml/obs_basic_workflow.xml
index 481693a6..9b19c62b 100644
--- a/xml/obs_basic_workflow.xml
+++ b/xml/obs_basic_workflow.xml
@@ -154,14 +154,15 @@
  <sect1 xml:id="sec.obs.basicworkflow.create-new">
   <title>Creating a New Package</title>
   <para>
-   This section covers how to create packages from a project hosted on &gh;
-   (the <quote>upstream project</quote>). We assume that this project contains source code
-   which you want to package for different &suse; distributions.
+   This section covers how to create packages for an arbitrary software project,
+   which we will refer to here as the <quote>upstream project</quote>. We
+   assume that this project contains source code
+   which you want to package for one or more &suse; (openSUSE) distributions.
    We assume the setup of your home project in your &obsa; instance is
    already done. If not, refer to <xref linkend="sec.obs.basicworkflow.setuphome"/>.
   </para>
   <para>
-   To create a package from an upstream project, do the following:
+   To create a package from the upstream project, do the following:
   </para>
   <procedure>
    <title>General Procedure to Build a RPM Package</title>
@@ -312,6 +313,34 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail;</screen>
     <screen>&prompt.user;<command>osc</command> commit</screen>
    </step>
   </procedure>
+  <para>
+   To delete a file in your working directory, merely deleting it from the local
+   filesystem (<command>rm FILE</command>) is not sufficient, since
+   &osccmd;, like any other Source Code Control System, will just complain
+   that the file is missing. If you really want to delete a file, use the command:
+  </para>
+  <screen>&prompt.user;<command>osc</command> delete FILE</screen>
+  <para>
+   While there is no dedicated &osccmd; to "move" (rename) a file,
+   the desired end result can be obtained using the following procedure:
+  </para>
+  <procedure>
+   <title>Procedure for Moving a File within a Locally Checked-out OBS Package</title>
+   <step>
+    <screen>&prompt.user;<command>cp</command> ORIGINAL_FILE NEW_FILE</screen>
+   </step>
+   <step>
+    <screen>&prompt.user;<command>osc</command> delete ORIGINAL_FILE</screen>
+   </step>
+   <step>
+    <screen>&prompt.user;<command>osc</command> add NEW_FILE</screen>
+   </step>
+   <step>
+    <para>And, finally:</para>
+    <screen>&prompt.user;<command>osc</command> status</screen>
+    <para>to verify that the end result is as intended.</para>
+   </step>
+  </procedure>
  </sect1>
 
  <sect1 xml:id="sec.obs.basicworkflow.builderrors">